Creates a verification session with the data specified in the request body
When to use this endpoint
- Use this endpoint to initiate a new verification session for an end-user. Every verification flow begins with creating a session.
Request body content
The contents of the request body depends on:
- Whether you are using the SDK or API to capture end-user data
- The type of verification solution the session is created for
Minimum request body:
- Empty
verificationobject
Payload examples:
- Click on the "Show examples" button in "Request" section to see request body examples for specific solutions/products.
Response data
Once you create the verification session, you receive:
- Unique session
id(store this - required for other endpoints) - Unique
sessionToken(legacy purposes, see FAQ) - Session URL in
verification.urlparameter (required for SDK integrations)
Getting session results
After the end-user completes the verification:
- Primary: webhook notifications sent to
webhook URL - Secondary: Poll
GET /v1/sessions/{id}/decisionendpoint - Backup: Use polling if webhook delivery fails
Implementation notes
- Store the returned session
id- it is required for all other session-related endpoints - Always ensure that you use the correct API URL to send requests. See the API URL section for more info.
- See Javascript sample implementation for SDK integration examples
- The order of parameters in the real API response can differ from the order you see in this documentation. This is expected and part of the Backwards compatible changes requirements.
Additional info: end-user flow after session creation
- Create session → Get
session.verification.url - Redirect end-user to
verification.url - End-user completes verification flow
- End-user redirected to your callback URL (if configured)
- Receive webhook notification OR poll for results
Your integration's API key (occasionally referred to as the "Token", "API public key" or "Publishable key"). Required for all API requests.
You can find your API key in the Veriff Customer Portal under Settings > API keys.
Must be set to application/json
Session initialization data
Empty verification object - minimum required to create a session
{
"verification": {}
}Session with person data, document details, and end-user ID
{
"verification": {
"callback": "https://example.com/callback",
"person": {
"firstName": "John",
"lastName": "Smith",
"idNumber": "123456789"
},
"document": {
"number": "B01234567",
"type": "PASSPORT",
"country": "US"
},
"endUserId": "c1de400b-1877-4284-8494-071d37916197"
}
}Session with person data, document details, end-user ID, and consent array
{
"verification": {
"person": {
"firstName": "John",
"lastName": "Smith",
"idNumber": "123456789"
},
"document": {
"number": "B01234567",
"type": "PASSPORT",
"country": "US"
},
"endUserId": "c1de400b-1877-4284-8494-071d37916197",
"consents": [
{
"type": "ine",
"approved": true
}
]
}
}Session for AML/sanctions screening with required person data
{
"verification": {
"person": {
"firstName": "John",
"lastName": "Smith",
"dateOfBirth": "1990-01-01"
}
}
}Session for matching end-user's identity and biometric data against governmental biometric databases. Currently available only for Brazilian CPF Biometric Database.
{
"verification": {
"person": {
"idNumber": 12345678901,
"firstName": "João",
"lastName": "Silva",
"dateOfBirth": "1990-01-15"
},
"vendorData": 12345678,
"endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4"
}
}Session to validate Brazilian users against social benefit registries. See here for full documentation.
{
"verification": {
"person": {
"idNumber": 12345678901,
"dateOfBirth": "1990-01-15"
}
}
}Session to validate users against Brazil's betting exclusion registries. See here for full documentation.
{
"verification": {
"person": {
"idNumber": 12345678901,
"dateOfBirth": "1990-01-15"
}
}
}Session for Mexican CURP database verification using person ID number
{
"verification": {
"person": {
"idNumber": "VISH560427MSRLNL06"
}
}
}Session for Mexican INE database verification using CIC and IFE identifier (OCR code) for card type D
{
"verification": {
"callback": "https://yourwebsite.com/webhook",
"document": {
"number": "123456789M00000000",
"documentNumberIdentifiers": {
"mxIfe": "MEX1234567890123"
}
}
}
}Session for Mexican INE database verification using CIC and INE identifier (Identificador Ciudadano) for card types E, F, G, and H
{
"verification": {
"callback": "https://yourwebsite.com/webhook",
"document": {
"number": "123456789M00000000",
"documentNumberIdentifiers": {
"mxIne": "MEX1234567890123"
}
}
}
}Proof of Address address matching session to compare addresses from two different sources
{
"verification": {
"person": {
"firstName": "John",
"lastName": "Smith"
},
"address": {
"fullAddress": "123, Main Street, Your County, Anytown 12345"
},
"proofOfAddress": {
"acceptableTypes": [
{
"name": "UTILITY_BILL"
},
{
"name": "PHONE_BILL"
},
{
"name": "TAX_DOCUMENT"
}
]
},
"endUserId": "c1de400b-1877-4284-8494-071d37916197"
}
}Can be used for address extraction and address validation solutions. See the full Proof of Address documentation here
{
"verification": {
"proofOfAddress": {
"acceptableTypes": [
{
"name": "UTILITY_BILL"
},
{
"name": "PHONE_BILL"
},
{
"name": "TAX_DOCUMENT"
}
]
},
"endUserId": "c1de400b-1877-4284-8494-071d37916197"
}
}Can be used for address extraction and address validation solutions. See the full Proof of Address documentation here
{
"verification": {
"person": {
"firstName": "John",
"lastName": "Smith"
},
"proofOfAddress": {
"acceptableTypes": [
{
"name": "UTILITY_BILL"
},
{
"name": "PHONE_BILL"
},
{
"name": "TAX_DOCUMENT"
}
]
},
"endUserId": "c1de400b-1877-4284-8494-071d37916197"
}
}Session for Biometric Authentication to verify identity by comparing two selfie images
{
"verification": {
"person": {
"firstName": "John",
"lastName": "Smith"
},
"endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
"vendorData": 12345678
}
}Session for UK DIATF M1B verification with full address
{
"verification": {
"address": {
"fullAddress": "123, Main Street, Your County, Anytown 12345"
}
}
}Session for US Database Verification: Light KYC verification with person details and address
{
"verification": {
"person": {
"firstName": "John",
"lastName": "Smith",
"dateOfBirth": "1990-01-01",
"phoneNumber": "8888888888"
},
"address": {
"fullAddress": "123, Main Street, Your County, Anytown 12345"
}
}
}Session for US Database Verification: SSN check with document number and person data
{
"verification": {
"person": {
"firstName": "John",
"lastName": "Smith",
"dateOfBirth": "1990-01-01"
},
"document": {
"number": "123456789"
}
}
}Verification object
The callback URL to where the end-user is redirected after the verification session is completed.
Default is visible in the Veriff Customer Portal -> Settings. Changing the value in this request body will overwrite the default callback URL, but it will not change the callback URL that is visible in the Customer Portal.
Data about the person being verified.
Person's first name.
Person's last name.
Person's national identification number.
Person's phone number.
Person's gender.
Person's date of birth.
Person's email address.
Person's marital status (mandatory only for some registry checks).
Person's deceased status (mandatory only for some registry checks).
Data about the document of the person being verified.
Document number, [a-zA-Z0-9] characters only.
Document issuing country, in capital letters.
Document type for Document + Selfie verification or Document-only verification
Date of the document's first issue.
Document type for the ID card, [a-zA-z] characters only.
Optional, only required for Colombia identity verification.
Specific document number identifiers.
Optional, currently used only for the Official Database Verification step for INE database verification solution.
Field representing the last 9 digits of the first line of the MRZ of an INE card. Also known as "Identificador del ciudadano".
Field representing the last 13 digits of the first line of the MRZ of an IFE card. Also known as "ocr".
Data about the address of the person being verified.
Full address (mandatory only for UK DIATF M1B profile flow).
Data about the PoA document of the person being verified.
Optional, should be only used in Proof of Address integrations.
Accepted types for proof of address document.
This parameter should be sent only when using the proof of address solution and after the Acceptable document types feature has been configured for your integration.
Name of the accepted proof of address document type.
The unique identifier that you created for your end-user. It can be max 1,000 characters long and contain only non-semantic data that can not be resolved or used outside your systems or environments.
Veriff returns it unmodified in webhooks and API response payloads, or as
null if not provided.
The UUID that you created for your end-user, that can not be
resolved or used outside your systems or environments.
Veriff returns it unmodified in webhooks and API response payloads, or as null if
not provided.
Array of objects listing the type of consent given.
Optional, should be only included for solutions/products that require consent (e.g., MX INE Biometric Database or Indian Aadhaar Database Verification).
Indicates the feature for which the consent is given.
If true, indicates that the consent has been given.
true is mandatory to start the INE Biometric Database Verification. If false or missing,
the session is not created.
Created session
API request status.
Verification object.
Verification session status.
UUID v4 which identifies the verification session.
URL of the verification session. The end-user is redirected here to
go through the flow. It is a combination of the baseUrl and the
sessionToken.
Session-specific token of the verification.
The base url the sessionToken can be used for.
The UUID that you created for your end-user, that can not be
resolved or used outside your systems or environments.
Veriff returns it unmodified in webhooks and API response payloads, or as null if
not provided.
The unique identifier that you created for your end-user. It can be
max 1,000 characters long and contain only non-semantic data that can
not be resolved or used outside your systems or environments.
Veriff returns it unmodified in webhooks and API response payloads, or as
null if not provided.
Bad request
Unauthorized
Too many requests
Internal server error
Changelog
Date | Description |
|---|---|
Mar 9, 2026 | Documentation updated: parent categories rearranged, intro section expanded, request and response examples added |
Jan 6, 2026 | New parameter |
Nov 6, 2025 | "Article Versoning" renamed to "Changelog" |
Oct 30, 2025 |
|
Sep 16, 2025 |
|
Aug 6, 2025 | Response headers added |
Jul 11, 2025 | Improved the note in the intro section about session creation, and about finding request parameters from Product Guides |
Apr 30, 2025 | - New parameters added to request's - New header |
Apr 22, 2025 |
|
Mar 12, 2025 | Documentation published |