Documentation

User lifecycle: enrollment → authentication

This guide describes the recommended way to model the full lifecycle of a returning user in VerifEye's Redirect — first visit (enrollment) and return visits (authentication) — using a single Verification project.

Key concept: the first verification call is the enrollment

This is the property that makes a single-project lifecycle possible: the same Verification can both onboard a brand-new user and authenticate a returning one — the verifier knows the difference from the state of the face collection.

Recommended pattern: single project + session overrides

The single-project pattern uses one Verification, configured with the full enrollment-time verifier set, and uses session-level overrides to disable verifiers that are only relevant on the first visit.

Verification configuration (one-time setup):

  • Liveness: Verification
  • Face Recognition: UniqueMatchVerification (or MatchVerification — see Verifier choice below)
  • Age: ThresholdVerification or CalculationOnly as needed
  • Gender: CalculationOnly as needed
  • AllowVerifierOverrides: true — required for the return-visit overrides to take effect

See Session Override configurations for the full list of override keys
../verification-configurations/#session-override-configurations

First visit vs. return visit

The two flows use the same Verification URL; only the session-level query string differs.

  First visit (enrollment) Return visit (authentication)
Verification project Same project Same project
Session URL parameters reExternalId=user-123 reExternalId=user-123
reDisableLivenessVerifier=true
reDisableAgeVerifier=true
reDisableGenderVerifier=true
Liveness runs skipped
Face Recognition enrolls the new face under user-123 matches against the stored embedding for user-123
Age / Gender runs (returns reAge, reGender) skipped
Typical result parameters reLivenessResult=passed
reFaceRecognitionResult=passed
reAgeVerificationResult=passed, reAge=…
reGenderVerificationResult=passed, reGender=…		 reFaceRecognitionResult=passed

The Verification URL itself must be signed by your backend in both cases (see the Security page). The session-level override parameters are part of the signed payload, so they cannot be tampered with by the end user.

Verifier choice: comparing the match modes

All three modes perform a 1:1 match against the face stored under reExternalId on return visits. They differ in whether they auto-enroll an unknown reExternalId and whether they enforce cross-identifier uniqueness.

  UniqueMatchVerification MatchVerification MatchOnlyVerification
Auto-enrolls on first (unknown) reExternalId yes yes no
1:1 match on return visit yes yes yes
Fails if no face is registered under reExternalId no no yes
Fails if the same face is already stored under a different reExternalId yes no no
Use when You also need to prevent the same person from registering twice under different IDs (e.g., one-per-person promotions, KYC). You only need to authenticate a known user and don't care about cross-ID uniqueness (e.g., re-authentication for an existing account). Enrollment is handled by a separate, controlled step and unknown users must fail closed instead of being auto-enrolled.

When to use MatchOnlyVerification

Unlike the two modes above, MatchOnlyVerification never enrolls: if no face is registered under the supplied reExternalId, the verifier fails (returning reFaceRecognitionResult=failed) and stores nothing. Choose it when enrollment is handled by a separate, controlled step and you want authentication to fail closed for unknown users instead of silently creating a new identity.

Register your reference images directly through the VerifEye Face API: call Onboard to add each face image to the collection and get its faceId, then Set External Key to associate your reExternalId value with that face. Onboard is the call that keeps the face; Identify only looks one up and stores nothing. On later visits, MatchOnlyVerification performs a 1:1 match against those pre-registered faces. See External Key Management for the full set of endpoints.

Common pitfalls

  • AllowVerifierOverrides must be enabled on the Verification. If it is false, the reDisable…Verifier query parameters on the return visit are silently ignored and the full enrollment flow runs every time.
  • Use the same reExternalId for the same user across visits. This identifier is the only thing linking the first and the return visit; without a stable value, the system treats each visit as a new user and auto-enrolls a fresh embedding.
  • Do not disable Face Recognition on the return visit. Disabling Liveness / Age / Gender is the intended override; disabling Face Recognition removes the authentication step itself.

Last updated: 2026-08-07