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
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
Integration’s API key
Log in to Veriff Customer Portal via the link in your sign-up email
Click on the Workspace dropdown menu on the left navigation bar
Open the All Integrations page
Open the integration you need and navigate to the the API keys tab
New page opens, displaying the Integration ID, BaseURL, Webhook signature and API key sections
To make API calls, you need the following:
The API key, to use it as the
X-AUTH-CLIENT header
The shared secret key, to create the
X-HMAC-SIGNATURE header
. To find it, click on the API key name or navigate to the API keys page via left navigation bar. New page opens, displaying the shared secret keyIf you are using the flexible API keys solution, copy the Integration ID to use as
vrf-integration-id header
when creating sessions
Flexible API keys
The solution is rolled out gradually, so you may not have access to it by default. Contact your Solutions Engineer or Veriff Customer Support for info.
It is possible to use the same API key for different integrations. To set them up or to view them, follow the steps below.
Log in to Veriff Customer Portal via the link in your sign-up email
Click on the Workspace dropdown menu
Open the API keys page
A page with available API keys is displayed, showing API key name, the shared secret key (used for signing) and associated integration(s)
Use the Add to integration button to tie the specific API key to additional integrations. Use the scissors icon in the Integrations table to untie the API key from the integration. You can untie only the API keys that are not assigned to provide their share secret key for Webhook signing.
API URL
Example: https://<base-URL>/v1/
To create the API URL:
First, find your BaseURL from the Integrations page in Veriff Customer Portal.
Next, to create the
API URL
, addv1
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
Basic headers
These are often needed to send requests, or are returned in responses:
X-AUTH-CLIENT
:string
(required) is the same as your integration’s API keyX-HMAC-SIGNATURE
:string
(required) is an HMAC-SHA256 hex encoded keyed hash using your shared secret keyCONTENT-TYPE
:string
(required for POST/PATCH calls) indicates the media type of the resource (application/json or a media format)
Flexible API keys header
vrf-integration-id
: string
(optional) an UUID that indicates the integration the shared API key is used for.
The value of vrf-integration-id
is the Integration ID that you can find in Veriff Customer Portal > All Integrations > integration name > API keys tab.
You need to include the header:
when one API key (the same that is used for the
X-AUTH-CLIENT
header) is tied to several integrations, andin session creation calls (i.e. in POST /sessions[↗], POST sync-api.veriff.me/v1/validate-registry[↗] and POST /validate-registry[↗])
Webhook signing
On the integrations page, under the API keys tab > Webhook signature section, you can also see the key that is used to sign webhook requests for that particular integration.
The webhook signature key is used to sign the webhooks sent by Veriff for the particular integration. The API responses will continue to be authenticated with the same key used to initiate the request.
In this section you can manage which API key and its corresponding shared secret key are used to sign the webhooks. You can use the Edit button to change the selection, meaning that a new API key + shared secret key pair is used to sign webhooks.
The API key and its corresponding shared secret key always go in pairs, they cannot be used separately.
If any of your keys has been compromised, you must delete it. If it is the key used to sign webhooks, first set another key as the new webhook signing key, and then delete the compromised key.
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 responsesChanging 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 payloadsWebhook 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)
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 [↗]
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
POST /sessions - starts a verification session
POST /sessions/{sessionId}/collected-data - allows uploading the data collected by you, using the sessionId
POST /sessions/{sessionId}/media - allows uploading media for the session, using the sessionId
PATCH /sessions/{sessionId} - allows updating the session status to “submitted” to pass the session on to verification process, using the sessionId
POST /sessions/validate-registry - creates a session and validates a national ID number with provided data
DELETE /sessions/{sessionId} - allows deleting the session, useful when testing, using the sessionId
. Not available by default.
To query decision, media and other data from the verification session
GET /sessions/{sessionId}/decision - allows querying the verification session decision data, using the sessionId
GET /sessions/{sessionId}/person - allows querying the data related to the person verified in the session, using the sessionId
GET /sessions/{sessionId}/watchlist-screening - returns a list of data objects from PEP and Sanctions services
GET /sessions/{sessionId}/media - allows querying info about the media uploaded during the session (using the sessionId
)
GET /sessions/{sessionId}/attempts - allows querying the id-s of different attempts done during one verification session, using the sessionId
GET /attempts/{attemptId}/media - allows querying info about the media uploaded during a certain attempt (using the attemptId
)
GET /media/{mediaId} - allows querying the media file using the mediaId
of a specific media file
To get registry-specific data
GET /sessions/{sessionId}/decision/ine-registry - allows querying verification data from Mexican INE registry, using the sessionId
GET /sessions/{sessionId}/decision/curp-registry - allows querying verification data from Mexican CURP registry, using the sessionId
GET /sessions/{sessionId}/decision/combined-ine-curp-registry - allows querying verification data from the combined Mexican registries check, using sessionId
To guide one-time password flow
POST /sessions/{sessionId}/mfa/generate - allows the generation (or retriggering) of one-time password for an Aadhaar Database Verification Check, using the sessionId
POST /sessions/{sessionId}/mfa/verify - used to submit the one-time password (OTP) for the Aadhaar Database Verification Check
Article versioning
Date | Description |
---|---|
April 30, 2025 | Flexible API keys info added: API keys and API headers sections updated, Webhook signing section added |
Apr 7, 2025 | List of solutions in “Wait for webhook response” updated |
Mar 12, 2025 | Documentation published |