A verification session is used to pass end-user data to Veriff and receive verification results from Veriff. Current article explains how to start a verification session.
Create with POST /sessions call
Before you start:
Refer to API prerequisites[↗]
and make sure you have all you need to start sending API requestsMake sure to check out the Backwards compatible changes list, to ensure that you are able to handle any updates that Veriff introduces to the payloads
For API
Make a POST /sessions[↗] call:
Send
verification
object to https://<BaseURL>/v1/sessions (*required)Include the
Content-Type application/json
header (*required)Include the
X-AUTH-CLIENT
header containing your integration's API key (*required)If you are using the flexible API key solution, make sure to pass Integration ID with the
vrf-integration-id header
(optional)Include the end-user's data/media you have collected (refer to the Request properties explained in POST /sessions[↗]) (optional)
Include the
vendorData
/endUserId
parameter (strongly recommended)
Check the response .json and record the unique session ID in verification.id
, required for webhooks and for identifying the session later on.
Minimum sample request
curl -X POST \
--url 'dummyBaseUrl/v1/sessions/' \
-H 'Content-Type: application/json' \
-H 'X-AUTH-CLIENT: API-KEY' \
-d '{
"verification": {},
}
}'
Expanded sample request
curl -X POST \
--url '/v1/sessions/' \
-H 'Content-Type: application/json' \
-H 'X-AUTH-CLIENT: API-KEY' \
-d '{
"verification": {
"callback": "https://veriff.com",
"person": {
"firstName": "John",
"lastName": "Smith",
"idNumber": "123456789"
},
"document": {
"number": "B01234567",
"type": "PASSPORT",
"country": "EE"
},
"address": {
"fullAddress": "Lorem Ipsum 30, 13612 Tallinn, Estonia"
},
"vendorData": "11111111",
"endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f",
"consents": [
{
"type": "ine",
"approved": true
}
]
}
}'
Sample response
{
"status": "success",
"verification": {
"id": "b27afb60-1455-4927-b155-0260ffe0947a",
"url": "https://....",
"vendorData": "2bf528f7-4b9c-44f0-b928-fdc7afc5ca1b",
"endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f",
"host": "https://....veriff.com",
"status": "created",
"sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....."
}
}
For native or web SDK
Make a POST /sessions[↗] call:
Send
verification
object tohttps://<BaseURL>/v1/sessions
Include the Content-Type
application/json
headerInclude the
X-AUTH-CLIENT header
containing your integration's API keyInclude the callback URL in
verification.callback
for Redirect end-users
If you are using the flexible API key solution, make sure to pass Integration ID with the
vrf-integration-id header
Include the
vendorData
parameter
Check the response .json and record:
Unique session ID in
verification.id
, required for webhooks and for identifying the session later onUnique sessionToken in
verification.sessionToken
Unique session URL in
verification.url
, required to bring the end-users to verification flow
→ See the specific SDKs guide in SDK Guides section for more info about how to start the verification session
Minimum sample request
curl -X POST \
--url 'dummyBaseUrl/v1/sessions/' \
-H 'Content-Type: application/json' \
-H 'X-AUTH-CLIENT: API-KEY' \
-d '{
"verification": {
"callback": "https://veriff.com",
"vendorData": "2bf528f7-4b9c-44f0-b928-fdc7afc5ca1b"
},
}
}'
Sample response
{
"status": "success",
"verification": {
"id": "b27afb60-1455-4927-b155-0260ffe0947a",
"url": "https://....",
"vendorData": "2bf528f7-4b9c-44f0-b928-fdc7afc5ca1b",
"endUserId": "fa820aba-019f-455a-ae81-cfca8075bc3f",
"host": "https://....veriff.com",
"status": "created",
"sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....."
}
}
Create with JavaScript SDK
You can use the JavaScript SDK to generate a session URL for your web flow.
→ See sample implementation for Javascript at https://github.com/Veriff/js-integration-demo [↗]
Manually
It is possible to manually generate a verification session in the Veriff Customer Portal. This option can be used to test or debug sessions, or as a manual fallback option.
The manual option creates a link and a QR code that you can share with the end-user.
Go to Veriff Customer Portal
Click on the All verifications on the left hand menu
Click on the Add Verification button
Find and open the relevant integration
Fill in the User first name, User last name
Click Generate Verification
Share the session by copying the link or the QR
Article versioning
Date | Description |
---|---|
Apr 30, 2025 | Flexible API keys info added to For API and For native or web SDK sections |
Mar 12, 2025 | Documentation published |