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 section for info)

*If you have generated the unique end-user identifier in the UUID v4 format, we recommend sending it in the endUserID field.
**If you have the unique end-user identifier in a format that is not UUID v4, you can send it in the vendorData field.


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[↗], 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.

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

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[↗] 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[↗] 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

    • Send the end-user through the verification flow to capture the new face image (using the preferred Veriff SDK)

    • 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

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[↗] 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[↗] call

  4. Patch session status to submitted status using PATCH /sessions/{sessionId}[↗] call

  5. Check the decision data and/or session related info from the decision webhook and/or query the data from the GET sessions/{sessionId}/decision[↗] 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.

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 documentation.

Sample request

{
    "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 | 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

    • 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 | 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. Log in to the Veriff environment to see the check names in the detailed request explanation[↗]

API call

Second source is the GET sessions/{sessionId}/decision[↗] endpoint, which contains the same data as the decision webhook, but also additional details.

Note that the API response payload example below contains only the Biometric Authentication-related part.

The GET sessions/{sessionId}/decision[↗] endpoint is used for many purposes, to find more info about it, see the documentation.

Sample response

{
    "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[↗]

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 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:


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:

To find more info about the public API endpoints listed above, see the API Documentation and API Reference[↗].