Concepts
This section describes the core concepts you will encounter when integrating with VerifEye's Redirect.
Verification session
A verification session represents a single end-user attempt.
- A session has a unique identifier (
reVerificationSessionIdin the final redirect URL). - The session aggregates the individual verifier outcomes into an overall verification result.
Verification
A Verification represents a named, configurable verification experience. It defines how the verification flow must work (rules, enabled verifiers, thresholds, UX options, etc.), and it may also reference or contain a
A verification contains the following configurations:
- Verifier configurations
- Redirect configurations
- Result parameter configurations
- Security configurations
- Session Override configurations
One-time setup (create once, reuse many times)
The API endpoints that create or modify a Verification are one-time setup operations and should be clearly labeled in the documentation as such. A Verification must typically be created only once per face-collection scope, either:
- via the developer/admin portal (recommended for most teams), or
- via a single programmatic call from a secure backend/service.
After creation, the same Verification configuration must be reused for all end-user sessions in that scope by referencing its verification_id (or verification_name, depending on the API design).
What “scope” means (and why it matters)
A Verification is a configuration object that is tied to a particular face collection scope, which depends on your use case:
- Login / authentication for an entire user base: You typically create one Verification for the whole user base (one shared face collection scope), and reuse it for every login attempt.
- Project- or campaign-based access control (separate populations): You create one Verification per project/campaign scope, for example:
-
- protecting a specific survey on a survey platform (each survey can have its own scope), or
-
- a limited-stock promotion (e.g., “Discounted shoes” campaign), where you want to admit new participants only until inventory lasts—each campaign/promo can be isolated via its own face collection scope and Verification.
Do not split one user base across multiple Verifications
Each Verification has its own face collection scope — a user known to one Verification is unknown to another. Creating multiple Verifications for the same user base (for example, one for enrollment and a separate one for authentication) is not recommended: the second Verification will not see the enrollment from the first and will silently auto-enroll the user again, defeating the separation.
For an enrollment-then-authentication flow for the same user base, use a single Verification with session-level overrides. See the User lifecycle guide.
Security guidance (must be created server-side)
Creating a Verification is a privileged administrative action and must be performed from a trusted, secure environment (backend, admin service, or portal). It must not be created by the end user on the client side.
If a user could create or control their own Verification, they could potentially influence the verification behavior (e.g., choose weaker settings, point to a different face collection, or otherwise manipulate the process). Therefore:
- Only admin/backend credentials should be allowed to call “create/update Verification” endpoints.
- Client applications should only receive a reference to an existing Verification (e.g.,
verification_id) and use it to start verification sessions.
Face collection
A face collection is the store of face embeddings that the Face Recognition verifier works against. Each face the verifier processes is turned into an embedding and compared with the embeddings already in the collection — that is what lets VerifEye recognise a returning user, authenticate against a known face, or block a duplicate sign-up.
A collection belongs to a Verification through its Face Recognition configuration, and it is what defines that Verification's face collection scope — the set of people it treats as "already known". Two Verifications pointing at different collections have completely separate populations: a user enrolled in one is unknown to the other.
Face embedding
A face embedding is a compact numerical representation of a face — a vector of numbers that captures its distinctive features, not the image itself. Two embeddings can be compared mathematically: the closer they are, the more likely they belong to the same person.
Embeddings are safe to store
You cannot tell what a person looks like from an embedding, and the original face image cannot be reconstructed or reverse-engineered from it — which is what makes it safe to store. An embedding is essentially a biometric fingerprint: unique to the person it was derived from, and used only to be compared against other embeddings.
Creating and managing a collection
A collection comes into existence in one of two ways:
- Automatically — when you enable Face Recognition on a Verification and reference a collection that does not exist yet, it is created for you.
- Explicitly — create and manage collections up front, for example to pre-register a known set of faces before any session runs.
Like creating a Verification, managing a collection is a privileged, server-side action and must not be exposed to the end user.
Collection id rules
A collection id may contain letters, digits, dot (.), dash (-) and underscore (_), and may be up to 512 characters long. An id that breaks these rules is rejected — it is never silently changed or truncated.
Lifecycle
Changing a live collection resets "who is known"
Because each collection is its own population, repointing a running Verification at a different (or empty) collection means previously enrolled users are no longer recognised and are treated as new. Only change the collection of a live Verification deliberately.
A collection is isolated to the account that owns it; faces are never shared across accounts.
Last updated: 2026-06-17