Veriff API Documentation and API Reference

Veriff Public API v1

There are a few scenarios where you may not wish to use Veriff's native or web SDKs to verify your end-users. For example:

• You wish to completely implement your own front-end

• You plan to collect end-users' media yourself

• You wish to do an offline bulk audit of previously verified end-users

In those cases, you can do the whole process using our API and you will not show any Veriff front-end to your end-users.

Prerequisites

In order to start sending media over the API, make sure that you:

• Created the integration[↗] in the Veriff environment

• Configured the webhooks[↗]

• Have all the necessary API key, API URL and headers at hand

• Make sure you are familiar with Backwards compatible changes and ensure that you systems can handle these

• You are ready to generate a verification session with POST /sessions[↗]

API keys

1. Log in to Veriff Customer Portal via the link in your sign-up email

2. Navigate to All Integrations page via left navigation bar

3. Open the integration you need, the Auth methods tab opens

4. From there you need to take:

• The API key, to use it as the X-AUTH-CLIENT header

• The shared secret key, to create the X-HMAC-SIGNATURE header

Shared secret key rotation

It is possible to manage your shared secret keys in the Veriff environment. You can add and delete keys, and set the master signature key.

The master signature key is used to sign all webhooks sent by Veriff. The API responses will continue to be authenticated with the same key used to initiate the request.

You can have up to 5 shared secret keys.

To manage the keys:

1. Log in to the Veriff Customer Portal

2. Navigate to All Integrations page via left navigation bar

3. Find and open the relevant integration

4. All the keys are displayed on the Auth methods tab, under the shared secret keys field

5. You can add a key using the + Add key button

6. Use the three dots next to the key to promote it to the master signature key, or to delete it

If any of your keys has been compromised, you must delete it. If it is the master signature key, first set another key as the new master key, and then delete the compromised key.

API URL

Example: https://<base-URL>/v1/

To create the API URL:

1. First, find your BaseURL from the Integrations page in Veriff Customer Portal.

2. Next, to create the API URL, add v1 to the Base URL value

Your API calls need to be sent to an URL which consists of the following elements:

• API URL

• path

  • contains one of: {sessionId} / {attemptId} / {mediaId}

• if relevant, any query parameters

Example: https://veriff.me.api/v1/sessions/aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7/decision/curp-registry?version=1.0.0

Check each endpoints’ documentation for exact info.

API headers

The example below shows basic headers. These are often needed to send requests, or are returned in responses:

• x-auth-client: string (required) - Your integration's API key. Required to identify the request or response sender.

• x-hmac-signature: string (required) - HMAC-SHA256 hex encoded keyed hash using your shared secret key. Required to authenticate the response sender.

• vrf-auth-client: string (always sent in responses) - Your integration's API key. Required to identify the request or response sender. Same as x-auth-client header.

• vrf-hmac-sigature: string (always sent in responses) - HMAC-SHA256 hex encoded keyed hash using your shared secret key. Required to authenticate the response sender. Same as x-hmac-signature.

• content-type: string (required for POST/PATCH calls) - Media type of the resource (application/json)

• vrf-integration-id: string (always sent in responses) - an UUID identifying an integration (aka Integration ID

Backwards compatible changes

All the changes listed below are considered to be backwards compatible by Veriff. Make sure to set up your systems in such flexible manner that it is able to handle these changes.

• Adding new properties (e.g., strings, objects, arrays) to existing API responses

• Changing the order* of properties in existing API responses, i.e., the order of strings, objects, arrays

• Adding new API resources, e.g., adding new API endpoints

• Adding new optional request parameters to existing API endpoints

• Changing the length or format of opaque** strings, such as error messages, object IDs, etc.

• Adding new event types to webhooks

• Adding new properties (e.g., strings, objects, arrays) to webhook payloads

• Webhook listener should gracefully handle unfamiliar event types

*As a general note on the order of properties in the responses, keep in mind that the order is not static. This means that the order you see in your API call responses may differ from the order you see in Veriff documentation.

**This means data that your system should be able to just transmit or store, not interpret.

Customers API flow in a nutshell

Create a verification session

The goal here is to create a new object (a verification session) that contains one verification, nested inside the session object in the response. Also, you will receive the session ID, which you need for the next step.

Send end-user's media

Using the session ID, pass the end-user's media (face, document front, document back, etc.) by uploading all images (and video if applicable) one by one using the POST request to POST /sessions/{sessionId}/media[↗] endpoint. The goal here is to upload the required photos and associate them with the verification created in step 1.

Take advantage of the additional collected data

In order to further improve the IDV process, we strongly recommend you collect some additional end-user data and send it to us via POST sessions/{sessionid}/collected-data[↗]. This step is not mandatory, but it is highly recommended.

Submit session for review

Once all the media and additional data has been uploaded, you then submit the verification session by sending the PATCH request to PATCH /sessions/{sessionId}[↗] and marking the verification to submitted status. Make sure that all the media has been submitted prior to triggering the PATCH request.

Wait for Veriff to verify the end-user

After these three steps, you have done your part, and the verification will then be taken care of by us.

Wait for webhook response

Veriff sends different types of webhooks for different event types using the POST method.

For all the solutions, you can choose to configure the optional event webhook [↗] to notify you about the progress of the verification flow (events).

Veriff sends the decision webhook [↗] for the following solutions:

• Identity and Document Verification (doc + selfie and doc-only)

• Biometric Authentication

• Biometric Liveness

• Age Estimation

• AML screening

• UK DIATF

• Mexican INE Biometric Database Verification

It contains a payload with the verification session decision and some additional data, including the verified identity information.

Veriff sends the watchlist-screening webhook [↗] for AML screening without IDV checks

For specific Mexican registry checks Veriff sends:

• INE webhook [↗]

• CURP webhook [↗]

• Combined INE+CURP webhook [↗]

Veriff sends the user-defined statuses webhook [↗] for when user has added a status to an attempt in the Veriff Customer Portal.

Veriff sends the full auto webhook [↗] for Self-Serve Essential plan customers.

Available endpoints and methods

To guide the verification flow

To query decision, media and other data from the verification session

To get registry-specific data

Article versioning