Document + Selfie IDV

This is the type of identity verification where Veriff analyses the images of the end-user and of their ID document (selfie + document), verifies the data, and returns the decision and data extracted from the document.

You can add Veriff’s IDV to your systems via native SDKs, web flow (aka web SDKs) and API.

All session-related info is returned via decision webhook and can be queried via different API endpoints. The results of the verification can also be viewed in the Veriff Customer Portal, under the Verification tab.

To balance speed, conversion, and fraud mitigation during the identity verification process, the solution is available in both hybrid and full auto set-ups:

• Hybrid: highly automated AI solution supported by trained verification specialists, designed for businesses that want to balance speed with accuracy, fraud prevention, and risk insights

• Full Auto: fully automated AI solution, great for businesses that require the fastest speed and most cost-effective solution

→ See Veriff Decision Engines: Full Auto & Hybrid in Knowledge Base for more info

Document + selfie IDV solution uses the decision webhook to return decision and session related data.

Do not concern yourself with Full Auto webhook, it is not used for document + selfie IDV solution.

Prerequisites

• You have an integration set up with Veriff

• You have set up the decision webhook to get responses from Veriff (see the how-to in Set up webhooks section)

• If using the API:

  • Veriff strongly recommends you collect and send additional device/session data for improved fraud mitigation

  • Veriff strongly recommends that you create and send us the endUserId or vendorData

Flow overview

The flow is a bit different, depending on the method you are using to verify your end-users with Veriff.

Use via SDKs

1. Generate a verification session using the API keys and the baseURL of your Doc + Selfie IDV integration (see the API Documentation and API Reference[↗] how to find these)

2. Capture end-user’s document and selfie images with Veriff’s SDKs

   1. Send the end-user through the verification flow to capture the images (using the preferred Veriff SDK)

   2. You need the session URL generated in step 1 to use the SDKs (found in response payload as verification.url)

3. Session will be submitted automatically once the end-user takes and submits necessary images

4. Receive the results from Veriff via decision webhook

Use via API

1. Generate a verification session using the a API keys and the baseURL of your Doc + Selfie IDV integration (see the API Documentation and API Reference[↗] how to find these)

   1. Veriff strongly recommends you create and send the endUserId or vendorData

   2. Veriff strongly recommends you collect and send additional  session/device data via POST sessions/{sessionid}/collected-data[↗] for improved fraud detection

2. Use your image-capturing method, or prepare previously collected end-user selfie and document images

3. Upload the end-user's media via POST /sessions/{sessionId}/media[↗] call

   1. Specify the image.context as appropriate for the image (see Context types (image, video) for more info about image context types)

4. Patch session status to submitted status using PATCH /sessions/{sessionId}[↗] call

5. Check the decision data and/or session related info from the decision webhook and/or query the data from the GET sessions/{sessionId}/decision[↗] endpoint

Find decision and/or session related info

You can get the data from three sources:

• Receive the decision webhook

• Query the results via GET sessions/{sessionId}/decision

• View the session in Veriff Customer Portal

Webhook payload

Below are a sample and an explanation of a decision webhook payload for a minimal document + selfie IDV.

Depending on your solution, the payload may contain additional parameters. To find more info about it, see the decision webhook documentation.

Sample request

{
    "status": "success",
    "verification": {
        "id": "12df6045-3846-3e45-946a-14fa6136d78b",
        "attemptId": "6cab5b0-c506-47a6-922d-6ae3b72ca172",
        "vendorData": "12345678",
        "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
        "status": "approved",
        "code": 9001,
        "reason": null,
        "reasonCode": null,
        "decisionTime": "2019-11-06T07:18:36.916Z",
        "acceptanceTime": "2019-11-06T07:15:27.000Z",
        "person": {
            "firstName": "SARAH",
            "lastName": "MORGAN",
            "dateOfBirth": "1967-03-30",
            "gender": null,
            "nationality": null,
            "idNumber": null,
            "yearOfBirth": "1967",
            "placeOfBirth": "MADRID",
            ...
            "pepSanctionMatch": null,
            "citizenship": null,
        },
        "document": {
            "number": "MORGA753116SM9IJ",
            "type": "DRIVERS_LICENSE",            
            "country": "US",
            "state": "NY",
            ...
            }
        },
        "additionalVerifiedData": [],
        "comments": []
    },
        "highRisk": false,
    "technicalData": {
        "ip": "186.153.67.122"
    }
  } 

Request properties explained

*Always sent, irrespective of solution’s configuration

• status: string* Status of the response

• verification: object* Verification request decision object. null if decision is not available yet

  • id: string* UUID v4 which identifies the verification session

  • attemptId: string* UUID v4 of the attempt which received a status (as shown in verification.status field)

  • vendorData: string | null* The unique identifier that you created for your end-user. null if not specified

  • endUserId: string | null* The UUID that you created for your end-user. null if not specified

  • status: string* Verification status, one of approved, declined, resubmission_requested, review, expired, abandoned

  • code: integer* Verification session decision code, one of 9001, 9102, 9103, 9104, 9121. For more info, see the verification session decision codes

  • reason: string | null* Reason why the verification failed

  • reasonCode: integer | null* Reason code of the failed verification. For more info, see the possible codes for a failed verification

  • decisionTime: string | null* Timestamp of the decision, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

  • acceptanceTime: string* Timestamp of the session generation, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

  • person : object* Data about the verified person

    • firstName: string | null* Person's first name as written on the document

    • lastName: string | null* Person's last name as written on the document

    • dateOfBirth: string* Person’s date of birth, represented as YYYY-MM-DD

    • gender: string | null* Person’s gender, represented as M or F, or null if not present

    • nationality: string | null* Person’s nationality, represented as ISO 3166 alpha-2 or alpha-3 number

    • idNumber: string | null* National identification number

    • yearOfBirth: string | null* Person’s year of birth, represented as YYYY

    • placeOfBirth: string | null* Person’s place of birth

    • …

  • document : object* Data about the verified document

    • number: string | null* Document number, [a-zA-Z0-9] characters only

    • type: string | null* Document type, one of PASSPORT, ID_CARD, RESIDENCE_PERMIT, DRIVERS_LICENSE, VISA, OTHER. For more info, see the Supported document types for IDV article

    • country: string | null* Document issuing country, represented as ISO 3166 alpha-2 code

    • state: string | null* Document issuing state, represented as ISO 3166 alpha-2 or alpha-3 code

    • …

  • additionalVerifiedData: array Data that has been optionally verified for the session, depending on the integration. Empty if no additional data was verified

  • comments: array (Deprecated) Always returns empty []

  • highRisk: boolean (Deprecated) Marked if session was considered high risk or not

• technicalData: object* Technical data object

  • ip: string | null IP of the device from which the verification was made

API call

You can use the GET sessions/{sessionId}/decision[↗] endpoint to get the decision data.

Below are a sample and an explanation of a API call payload for a minimal document + selfie IDV.

Depending on your solution, the payload may contain additional parameters. To find more info about it, see the GET sessions/{sessionId}/decision[↗] documentation.

Sample response

{
    "status": "success",
    "verification": {
        "id": "12df6045-3846-3e45-946a-14fa6136d78b",
        "attemptId": "6cab5b0-c506-47a6-922d-6ae3b72ca172",
        "vendorData": "12345678",
        "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
        "status": "approved",
        "code": 9001,
        "reason": null,
        "reasonCode": null,
        "decisionTime": "2019-11-06T07:18:36.916Z",
        "acceptanceTime": "2019-11-06T07:15:27.000Z",
        "person": {
            "firstName": "SARAH",
            "lastName": "MORGAN",
            "dateOfBirth": "1967-03-30",
            "gender": null,
            "nationality": null,
            "idNumber": null,
            "yearOfBirth": "1967",
            "placeOfBirth": "MADRID",
            ...
            "pepSanctionMatch": null,
            "citizenship": null,
        },
        "document": {
            "number": "MORGA753116SM9IJ",
            "type": "DRIVERS_LICENSE",            
            "country": "US",
            "state": "NY",
            ...
            }
        },
        "additionalVerifiedData": [],
        "comments": []
    },
        "highRisk": false,
    "technicalData": {
        "ip": "186.153.67.122"
    }
  } 

Response properties explained

• status: string Status of the response

• verification: object Verification request decision object. null if decision is not available yet

  • id: string UUID v4 which identifies the verification session

  • attemptId: string UUID v4 of the attempt which received a status (as shown in verification.status field)

  • vendorData: string | null The unique identifier that you created for your end-user. null if not specified

  • endUserId: string | null The UUID that you created for your end-user. null if not specified

  • status: string Verification status, one of approved, declined, resubmission_requested, review, expired, abandoned

  • code: integer Verification session decision code, one of 9001, 9102, 9103, 9104, 9121. For more info, see the verification session decision codes

  • reason: string | null Reason why the verification failed

  • reasonCode: integer | null Reason code of the failed verification. For more info, see the possible codes for a failed verification

  • decisionTime: string Timestamp of the decision, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

  • acceptanceTime: string Timestamp of the session generation, represented as UTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset (ISO 8601)

  • person : object Data about the verified person

    • firstName: string | null Person's first name as written on the document

    • lastName: string | null Person's last name as written on the document

    • dateOfBirth: string Person’s date of birth, represented as YYYY-MM-DD

    • gender: string | null Person’s gender, represented as M or F, or null if not present

    • nationality: string | null Person’s nationality, represented as ISO 3166 alpha-2 or alpha-3 number

    • idNumber: string | null National identification number

    • yearOfBirth: string | null Person’s year of birth, represented as YYYY

    • placeOfBirth: string | null Person’s place of birth

    • …

  • document : object Data about the verified document

    • number: string | null Document number, [a-zA-Z0-9] characters only

    • type: string | null Document type, one of PASSPORT, ID_CARD, RESIDENCE_PERMIT, DRIVERS_LICENSE, VISA, OTHER. For more info, see the Supported document types for IDV article

    • country: string | null Document issuing country, represented as ISO 3166 alpha-2 code

    • state: string | null Document issuing state, represented as ISO 3166 alpha-2 or alpha-3 code

    • …

  • additionalVerifiedData: array Data that has been optionally verified for the session, depending on the integration. Empty if no additional data was verified

  • comments: array (Deprecated) Always returns empty []

  • highRisk: boolean (Deprecated) Marked if session was considered high risk or not

• technicalData: object Technical data object

  • ip: string | null IP of the device from which the verification was made

Veriff Customer Portal

You can find the verification session related info, including the decision, in the Veriff Customer Portal, under the Verifications tab.

Status and reason codes

For an approved session, see:

• verification.code about verification session decision code, one of 9001, 9102, 9103, 9104, 9121

• verification.status about verification status, one of approved, declined, resubmission_requested, review, expired, abandoned

If the session was declined or resubmission_requested, you can find additional information by checking:

• verification.reason for the reason why the verification failed

• verification.reasonCode for reason code of the failed verification and cross-reference it with Granular reason codes (table)

The review status

Not available by default

You need to make an agreement with Veriff to enable this option for you and you agree to perform the review on your side. Meaning that if Veriff’s system is unable to reach a conclusive decision, the session is set to review and sent to your decision-making flow.

For more info about the codes you are seeing, refer to:

• Verification session status codes (table)

• Verification session decision codes (table)

• Granular reason codes (table)

Session lifecycle flow diagram

FAQ

Changelog