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)

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.

*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

   • Specify context parameter as face

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.

Status and reason codes

These values are available in the decision webhook payload, in verification.status and verification.code data objects.

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.

For more info about the codes you are seeing, refer to:

• Verification session status codes (table)

• Verification session decision codes (table)

• Granular reason codes (table)

FAQ