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
Create a verification session to get the session ID
Veriff strongly recommends you send the
vendorData
/endUserId
(see below)
Using the session ID, pass end-user's media via POST /sessions/{sessionId}/media[↗]
Patch the session to
submitted
using PATCH /sessions/{sessionId}[↗]Wait for Veriff to verify the end-user
Veriff returns the decision via a webhook
vendorData
parameterVeriff 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 asnull
if not provided.
vendorData
is mandatory for Cross Links check and Velocity Abuse check (Fraud solutions); and an alternative to theendUserId
parameter in Biometric Authentication solution, if you are using some non-UUID format to create unique identifiers.
endUserId
parameterVeriff 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 thevendorData
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
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 | ||
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 |