--- title: "Biometric Authentication | Veriff.com" slug: "biometric-authentication" description: "Verify returning users through facial biometric matching. Available via API, web flow, and SDKs." tags: ["Biometric Authentication", "Identity Verification"] status: "update" updated: 2026-06-11T09:28:02Z published: 2026-06-11T09:28:02Z canonical: "devdocs.veriff.com/biometric-authentication" --- > ## Documentation Index > Fetch the complete documentation index at: https://devdocs.veriff.com/llms.txt > Use this file to discover all available pages before exploring further. # Biometric Authentication Veriff’s Biometric Authentication solution uses facial biometric analysis and advanced AI to swiftly and securely verify that the person authenticating themselves is the person they claim they are. Veriff Biometric Authentication is available via API, web flow, and native SDKs. This fast and fully automated process can be integrated into any stage of the user journey. --- ## Prerequisites - You have a selfie enrollment integration set up by your Solutions Engineer - You have an authentication integration set up and connected to the selfie enrollment integration - You have generated and attached `endUserId` or `vendorData` to each end-user, and can pass Veriff this info - The end-user has an `approved` session from the selfie enrollment integration - You have configured the **decision webhook** to get responses from Veriff (see the [Webhooks](/v1/docs/webhooks-guide) section for info) #### Note about `endUserId` and `vendorData` Veriff strongly recommends (and on occasions require) you create a unique identifier for your end-user, store it and send it to Veriff. Once sent, Veriff returns it unmodified in webhooks and API response payloads, or as `null` if not provided. | `endUserId` | `vendorData` | | --- | --- | | Use `endUserId` when your end-user identifier is **in UUID v4 format**. `endUserId` ties together a specific end-user and their session(s). | Use `vendorData` when your end-user identifier is **not in UUID v4 format**. The field accepts strings up to 1,000 characters containing only non-semantic data that can not be resolved or used outside your systems or environments. `vendorData` is a fixed value that cannot be changed. | --- ## Set up a Biometric Authentication solution ### Selfie enrollment integration To use Veriff’s biometric authentication solution, you first need the selfie enrollment integration. Read on for more information, but **contact your Solutions Engineer for configuration**. In [general terms](https://www.innovatrics.com/glossary/enrollment/)[↗], enrollment is a process of capturing biometrics samples, processing them to create a biometric template and storing the templates onto storage. In Veriff’s case, the enrollment integration is the one during which the raw biometrics data (e.g., end-user's face image) is processed and converted into a mathematical biometric template. The template is stored so it can be used in the future to verify the end-user during a biometric authentication session. The image is taken from an approved docment+selfie session, or a selfie-only session that is run in the enrollment integration. If the session is approved (the image quality meets certain criteria, the `endUserId`/`vendorData` is present, there is no suspicion of fraudulent activity, etc.) the selfie image from the session is stored and can be used as a reference image. #### Pass selfie images to Veriff The image that is used for enrollment (biometric data capturing, processing and conversion into a biometric template) can come from different sources. With Veriff’s Doc & Selfie IDVWithout Veriff’s Doc & Selfie The selfie image taken from an approved document+selfie verification session becomes the reference image. It is converted into a biometric template and stored for future use. It is possible to migrate* images from previous IDV sessions for authentication. An document+selfie / selfie-only session is done inside the biometric enrollment integration. If the session is approved, the selfie enrollment image is converted into a biometric template and stored for future. If existing face images are available: previously collected selfie images become reference images and are enrolled. This may require migration*. *In cases of migration, contact your Solutions Engineer for more info. ### Authentication integration This is the integration that you will use to create biometric authentication sessions for the end-users. It must be connected to the enrollment integration, so the system has access to the following end-user-related data in the enrollment integration: - Biometric template - Approved session data - `endUserId`/`vendorData` > [!NOTE] > Contact your **solutions engineer** for info and configuration. Once ready, you can start creating authentication sessions for your end-users in the SDKs, or send us collected end-user data over the API. When creating the verification sessions in the SDKs or sending us the end-users’ data over the API, use the **API keys and tokens** of the **authentication integration** (you can find these in the Veriff Customer Portal. See [API Documentation and reference](https://devdocs.veriff.com/apidocs) for more info about how to find the keys and tokens.) Make sure to always include the `endUserId`/`vendorData` as we need to see that it matches the end-user’s approved session’s `endUserId`/`vendorData` in the selfie enrollment integration. --- ## Flow overview The flow is a bit different, depending on the method you are using to verify your end-users with Veriff. ### Use via SDK 1. Generate an authentication session using the `API keys` and the `baseURL` of your Biometric Authentication integration (see the [API Documentation and API Reference](https://devdocs.veriff.com/apidocs) how to find these) - Make sure that you include the same `endUserId`/`vendorData` that you used in the enrollment integration session 2. Capture end-user’s face images with [Veriff’s SDKs](/v1/docs/sdk-guide) - Send the end-user through the verification flow to capture the new face image (using the preferred [Veriff SDK](/v1/docs/sdk-guide)) - You need the session URL generated in step 1 to use the SDKs - Session will be submitted automatically once the end-user takes and submits necessary images of their face 3. Receive the results from Veriff via [decision webhook](/v1/docs/decision-webhook) ### Use via API This is applicable once the end-user has an approved session containing a populated `endUserID`/`vendorData`. 1. Generate an authentication session using the `API keys` and the `baseURL` of your Biometric Authentication integration (see the [API Documentation and API Reference](https://devdocs.veriff.com/apidocs) how to find these) - Make sure that you include the same `endUserId`/`vendorData` that you used in the enrollment integration session 2. Use your face-capturing method, or prepare previously collected end-user face images 3. Upload the end-user's face image via the [POST /sessions/{sessionId}/media](https://devdocs.veriff.com/apidocs/v1sessionsidmedia-3) call - Specify [context parameter](/v1/docs/context-types-image-video-1) as `face` 4. Patch session status to submitted status using [PATCH /sessions/{sessionId}](https://devdocs.veriff.com/apidocs/v1sessionsid-2) call 5. Check the decision data and/or session related info from the [decision webhook](/v1/docs/decision-webhook) and/or query the data from the [GET /sessions/{sessionId}/decision](/v1-api/apidocs/v1sessionsiddecision-1) endpoint --- ## From the end-user point of view When the end-user needs to authenticate, they simply take a selfie using their device camera. A new template is created and compared against the stored template from enrollment. If they match within a set accuracy threshold, and the `endUserId`/`vendorData` in the enrollment integration session match that in the authentication integration session, the user is successfully identified. --- ## Find decision and/or session related info You can get the data from three sources: - Receive the decision webhook - Query the results via GET sessions/{sessionId}/decision - View the session in Veriff Customer Portal ### Webhook payload All Biometric Authentication results are returned, inside the `verification.biometricAuthentication` object. > [!NOTE] > The webhook **example below** contains **only the Biometric Authentication-related part of the webhook**. > > The decision webhook is used for many purposes, to find more info about it, see the [decision webhook](/v1/docs/decision-webhook) documentation. #### Sample request ```json {    "status": "success",    "verification": {        ...        "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",        "vendorData": "12345678",        "attemptId": "6cab5b0-c506-47a6-922d-6ae3b72ca172",        "status": "approved",        "code": 9001,        "reason": null,        "reasonCode": null        "biometricAuthentication": {            "matchedSessionId": "d40edb60-6ae6-...",            "matchedSessionEndUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",            "matchedSessionVendorData": "12345678",            "details": {                  ...            }        },        ...    } } ``` #### Request properties explained - `status`: `string` Status of the response - `verification`: `object` Verification request decision object - … - `endUserId`: `UUID v4` | `null` End-user-specific UUID v4 created by the customer to identify the end-user. Returned unmodified in webhooks and public API calls, or as null if not provided - `vendorData`: `string` | `nul`l End-user-specific string created by the customer to identify the end-user. Returned unmodified in webhooks and public API calls, or as null if not provided - `attemptId`: `string` UUID v4 of the attempt which received a status (as shown in `verification.status` field) - `status`: `string` Verification status, one of approved, resubmission_requested, review, declined, expired, abandoned - `code`: `integer` Verification session decision code, one of 9001, 9102, 9103, 9104, 9121. More information about verification session decision codes - `reason`: `string` | `null `Reason of failed verification - `reasonCode`: `string` | `null` Reason code of failed verification - biometricAuthentication: object Object containing data about the biometric authentication - `matchedSessionId`: `string` | `nul`l Refers to the verification session ID which the face matched - `matchedSessionEndUserId`: `string` | `null` Refers to the verification session endUserId which the face matched - `matchedSessionVendorData`: `string` | `null` Refers to the verification session vendorData which the face matched - `details`: `object` Lists the results of different checks that were made to verify the end-user. Log in to the Veriff environment to see the check names in the [detailed request explanation](https://help.veriff.com/en/articles/9638913-biometric-authentication-results-in-decision-webhook)[↗] ### API call Second source is the [GET /sessions/{sessionId}/decision](/v1-api/apidocs/v1sessionsiddecision-1) endpoint, which contains the same data as the decision webhook, but also additional details. > [!NOTE] > Note that the API response payload **example below** contains **only the Biometric Authentication-related part**. > > The [GET /sessions/{sessionId}/decision](/v1-api/apidocs/v1sessionsiddecision-1) endpoint is used for many purposes, to find more info about it, see the documentation. #### Sample response ```json {    "status": "success",    "verification": {        ...        "id": "12df6045-3846-3e45-946a-14fa6136d78b",        "attemptId": "6cab5b0-c506-47a6-922d-6ae3b72ca172",        "code": 9001,        "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",        "vendorData": "null",        "status": "approved",                "reason": null,        "reasonCode": null        "biometricAuthentication": {            "matchedSessionId": "d40edb60-6ae6-...",            "matchedSessionEndUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",            "matchedSessionVendorData": "12345678",            "details": {                  ...            }        },        ...    } } ``` #### Response properties explained - `status`: `string` Status of the response - `verification`: `object` Verification request decision object - … - `id`: `string` UUID v4 which identifies the verification session - `attemptId`: `string` UUID v4 of the attempt which received a status (as shown in `verification.status` field) - `code`: `integer` Verification response code, one of 9001, 9102, 9103, 9104, 9121 - `endUserId`: `UUID v4 | null` End-user-specific UUID v4 created by the customer to identify the end-user. Returned unmodified in webhooks and public API calls, or as `null` if not provided - `vendorData`: `string | null` End-user-specific string created by the customer to identify the end-user. Returned unmodified in webhooks and public API calls, or as `null` if not provided - `status`: `string` Verification status, one of approved, `resubmission_requested`, `review`, `declined`, `expired`, `abandoned` - `code`: `integer` Verification session decision code, one of 9001, 9102, 9103, 9104, 9121 - `reason`: `string | null` Reason of failed verification - `reasonCode`: `string | null` Reason code of failed verification - `biometricAuthentication`: `object` Object containing data about the biometric authentication - `matchedSessionId`: `string | null` Refers to the verification session ID which the face matched - `matchedSessionEndUserId`: `string | null` Refers to the verification session endUserId which the face matched - `matchedSessionVendorData`: `string | null` Refers to the verification session vendorData which the face matched - `details`: `object`* Lists the results of different checks that were made to verify the end-user. If you have been granted access to the Veriff Customer Portal, you can find these in the [detailed request explanation](https://help.veriff.com/en/articles/9638913-biometric-authentication-results-in-decision-webhook)[↗] ### Veriff Customer Portal You can find the verification session related info, including the decision, in the Veriff Customer Portal, under the **Verifications** tab. → *See* [*Review verification in Veriff Customer Portal*](/v1/docs/how-to-review-verification-in-veriff-customer-portal) *about how to view the session info in the Veriff Customer portal* --- ## Status and reason codes These values are available in the decision webhook payload, in `verification.status` and `verification.code` data objects. | `verification.status` | `verification.code` | What does it mean? | | --- | --- | --- | | approved | 9001 | Positive: end-user was verified. The verification process is complete. Accessing the `sessionURL` again will show the end-user that nothing is to be done here. | | declined | 9102 | Negative: end-user has not been verified. The verification process is complete. Either it was a fraud case or some other severe reason that the end-user can not be verified. It could also have been that due to a bad image quality the end-user could not be matched. If you decide to give the end-user another try, you need to create a new session. | | expired | 9104 | Negative: Verification has expired. The verification process is complete. After the session creation, if the end-user has not started the verification in 7 days, the session gets `expired` status. | | abandoned | Negative: Verification has been abandoned. The verification process is complete. After the session creation, if the end-user has started but not completed the verification in 7 days, the session gets `abandoned` status. | If the session was `declined` or `resubmission_requested`, you can find additional information by checking the `verification.status`, `verification.code`, `verification.reason` and `verification.reasonCode` data objects. | `verification.status` | `verification.reasonCode` | `verification.reason` | What does it mean? | | --- | --- | --- | --- | | declined | 105 | Decline - Suspicious behavior | The session contains some suspicious behaviour, for example the face image is shown from a device, screen or print-out. The end-user is declined. | | declined | 106 | Decline - Known fraud | The session contains fraudulent behaviour, for example the photos are streamed. The end-user is `declined`. | | declined | 120 | Decline - Person on the portrait does not appear to match reference photo | The end-user is declined. | | declined | 121 | Decline - user ID missing | The `vendorData` does not match the `vendorData` used during enrollment, the end-user is declined. To avoid this issue, ensure the same `vendorData` is sent. | | declined | 122 | Decline - No reference found | No enrollment face image (reference image) found that would match the `endUserId`/`vendorData`, the end-user is declined. | | declined | 128 | Decline - `endUserId` mismatch | The `endUserId` does not match the `endUserId` used during enrollment, the end-user is declined. To avoid this issue, ensure the same `endUserId` is sent. | | expired | null | null | The end-user did not complete the verification flow. If you want to let them to try again, create a new session for them. | | abandoned | For more info about the codes you are seeing, refer to: - [Verification session status codes (table)](/v1/docs/verification-session-status-codes-table) - [Verification session decision codes (table)](/v1/docs/verification-session-decision-codes-table) - [Granular reason codes (table)](/v1/docs/granular-reason-codes) --- ## FAQ #### Where can I query the data related to the session and the end-user? 📖 session ID | attempt ID | mediaId The following endpoints can be used to query data related to the verification session and the end-user: - [GET /sessions/{sessionId}/attempts](https://devdocs.veriff.com/apidocs/v1sessionsidattempts-1) - allows querying the **id-s of different attempts** done during one verification session, using the `sessionId` - [GET /sessions/{sessionId}/decision](https://devdocs.veriff.com/apidocs/v1sessionsiddecision-1) - allows querying the **verification session decision data**, using the `sessionId` - [GET /sessions/{sessionId}/person](https://devdocs.veriff.com/apidocs/v1sessionsidperson-1) - allows querying the **data related to the person** verified in the session, using the `sessionId` - [GET /sessions/{sessionId}/media](https://devdocs.veriff.com/apidocs/v1sessionsidmedia-2) - allows querying **info about the media** uploaded during the session (using the `sessionId`) - [GET /attempts/{attemptId}/media](https://devdocs.veriff.com/apidocs/v1attemptsidmedia-1) - allows querying **info about the media** uploaded during a certain attempt (using the `attemptId`) - [GET /media/{mediaId}](https://devdocs.veriff.com/apidocs/v1mediaid-1) - allows querying the **media file** using the `mediaId` of a specific media file To find more info about the public API endpoints listed above, see the [API Documentation and API Reference](https://devdocs.veriff.com/apidocs). --- ## Changelog | Date | Description | | --- | --- | | Jun 11, 2026 | [Note about endUserId and vendorData](/v1/docs/biometric-authentication#note-about-enduserid-and-vendordata) section added | | Sep 12, 2025 | Update the `endUserId` and `vendorData` descriptions in [Prerequisites](/v1/docs/biometric-authentication#prerequisites) section | | Mar 12, 2025 | Documentation published | In this integration, the raw biometrics data (e.g., end-user's face image) is processed and converted into a mathematical biometric template. The template is stored so it can be used in the future to verify the end-user during a biometric authentication session. The integration that you will use to create biometric authentication sessions for the end-users. **User of Veriff customer's solution**, the person who goes through the verification flow (aka "end-user flow"). An environment created according to customer's needs to carry out, manage and observe verifications. You can find the list of your integrations in **Veriff Customer Portal** > **All** **Integrations** page (you need to be logged in). A **process where the end-user submits the data** required to get verified. Also referred to as the "end-user flow". This where the end-user is directed to go through the verification flow, and it is **unique for each verification session**. It is a combination of the `base URL` and the `sessionToken`, created as soon as a verification session is created. You can find its value in the response payload of your POST /sessions call, as `verification.url`. Veriff customer back-office, a dashboard where you can see your end-users' verification data. Depending on your setup, you may be required to access the environment via station.veriff.com or hub.veriff.com. Always **check your sign-up email** and make sure that you **log in via correct address**. A **unique identifier of a verification session**. It is automatically created as soon as you create a session. In the **API requests' context**, one verification session comprises many steps (uploading data, uploading images, getting a decision, etc.). You can call several endpoints using the same **session ID**, to get all kinds of different data from that specific session. You can find its value in the **response payload** of your **POST /sessions API request**, in the `verification.id` parameter. An **UUID v4** of a specific **attempt**, found in decision webhook as `attemptId` parameter, or in **GET /sessions/{sessionId}/attempts** response as `verification.id` parameter. An **"attempt" is one step inside a verification session**, e.g., uploading required data and getting a decision. An **"attempt" can be made several times** during a verification session. This means that calling the GET /sessions/{sessionId}/attempts can return several `verification` objects, each one with a unique `id` value. A **unique identifier** of a specific **media file**. To get the `mediaId` of a specific media file, request a list of media via GET attempts/{attemptId}/media or GET sessions/{sessionId}/media. ## Related - [Getting Started](/getting-started.md) - [Integrations](/how-to-create-an-integration.md) - [Create verification session](/how-to-generate-sessions-manually.md) - [Webhooks Guide](/webhooks-guide.md) - [Codes](/codes.md)