Create verification session

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 requests

• Make 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 to https://<BaseURL>/v1/sessions

• Include the Content-Type application/json header

• Include the X-AUTH-CLIENT header containing your integration's API key

  • Include 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 on

• Unique 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.

1. Go to Veriff Customer Portal

2. Click on the All verifications on the left hand menu

3. Click on the Add Verification button

4. Find and open the relevant integration

5. Fill in the User first name, User last name

6. Click Generate Verification

7. Share the session by copying the link or the QR

Cap on the session creation rate

Note that there is a maximum limit to how many sessions you can create in an integration:

• Enterprise customer: 600 sessions per minute

• Self-Serve customer: 30 sessions per minute

Verification session statuses

The session status indicates the progress of the verification session, signalling the stage where the end-user’s verification process currently is.

→ See the Verification session status codes (table) article for technical info about how Veriff notifies you about the status change and how different session statuses can affect the flow

→ See the Meanings of various verification statuses and decisions[↗] article in Veriff Knowledge Base for additional info (you need to log in to Veriff Customer Portal to access the article)

About verification session expiry

All verification sessions expire after 7 days.

• Sessions in created status will move to expired

• Sessions in started status will move to abandoned

Changelog