Intro to the API

See API Documentation and API Reference[↗] for detailed info about Veriff APIs

Opt for using the Application Programming Interface (API) solution if you want to collect the end-user's data and/or media yourself via your own solution, and then use Veriff's API endpoints to pass us relevant data for verification.

Note that collecting end-user's data beforehand or during the flow is optional, as Veriff can extract this data from the media sent to us.

Quick overview of the steps

  1. Create an integration

  2. Set up webhooks

  3. Create a verification session to get the session ID

    1. Veriff strongly recommends you send the vendorData/endUserId (see below)

  4. Using the session ID, pass end-user's media via POST /sessions/{sessionId}/media[↗]

  5. Patch the session to submitted using PATCH /sessions/{sessionId}[↗]

  6. Wait for Veriff to verify the end-user

  7. Veriff returns the decision via a webhook

vendorData parameter 

Veriff strongly recommends (and on occasions require) you create a unique identifier for your end-user, store it and send it to Veriff. You can use the vendorData parameter to send an identifier that is max 1,000 characters long and contains 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. It is used to tie together a specific end-user and their session(s). Veriff returns it unmodified in webhooks and API response payloads, or as null if not provided.

vendorData is mandatory for Cross Links check and Velocity Abuse check (Fraud solutions); and an alternative to the endUserId parameter in Biometric Authentication solution, if you are using some non-UUID format to create unique identifiers.

endUserId parameter

Veriff strongly recommends (and on occasions require) you create a unique identifier for your end-user, store it and send it to Veriff. If you are using the UUID format to create and store the identifiers, you should use the endUserId parameter to send it to Veriff. 

This identifier is used to tie together a specific end-user and their session(s). Veriff returns it unmodified in webhooks and API response payloads, or as null if not provided.

The endUserId parameter is a good alternative to the vendorData parameter in Biometric Authentication solution.

API session lifecycle diagram

When verifying via API:

  • Customer decides wether to collect end-user’s data and media before or after creating the session

  • Session ID aka verification.id is the unique identifier of the session that needs to be included in all the API calls that are done for that session

Flowchart illustrating the flow of data between the end-user, customer, and Veriff during a verification process.

The diagram above illustrates an end-to-end integration verification process between three entities: end-user, customer, and Veriff.

Step

End-User

Customer

Veriff

1

Starts verification process and provides document and selfie images

Collects images of end-user's document and selfie (if relevant)

2

Creates session by sending POST request to "/sessions"

3

Returns session ID in verification.id parameter

4a

Uploads media via POST to "sessions/{sessionId}/media"

4b

Updates session status to "submitted" via PATCH to "/sessions/{sessionId}"

5

Session is verified (internal process)

6a

Receives decision

Sends decision to customer via webhook

6b

Optionally uses GET request to "/sessions/{sessionId}/decision" to query more detailed data

Provides detailed verification data when requested

The diagram uses dashed vertical lines to represent the timeline for each entity and horizontal arrows to show the direction of communication between them. Green horizontal bars represent the end-user providing documents/selfie in step 1 and Veriff verifying the session in step 5.


Article versioning

Date

Mar 31, 2025

Session flow diagram updated

Alt text updated

Mar 12, 2025

Documentation published