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
Generate a verification session using the
API keys
and thebaseURL
of your Doc + Selfie IDV integration (see the API Documentation and API Reference[↗] how to find these)Capture end-user’s document and selfie images with Veriff’s SDKs
Send the end-user through the verification flow to capture the images (using the preferred Veriff SDK)
You need the session URL generated in step 1 to use the SDKs (found in response payload as
verification.url
)
Session will be submitted automatically once the end-user takes and submits necessary images
Receive the results from Veriff via decision webhook
Use via API
Generate a verification session using the a
API keys
and thebaseURL
of your Doc + Selfie IDV integration (see the API Documentation and API Reference[↗] how to find these)Veriff strongly recommends you create and send the
endUserId
orvendorData
Veriff strongly recommends you collect and send additional session/device data via POST sessions/{sessionid}/collected-data[↗] for improved fraud detection
Use your image-capturing method, or prepare previously collected end-user selfie and document images
Upload the end-user's media via POST /sessions/{sessionId}/media[↗] call
Specify the
image.context
as appropriate for the image (see Context types (image, video) for more info about image context types)
Patch session status to
submitted
status using PATCH /sessions/{sessionId}[↗] callCheck 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 responseverification
:object
* Verification request decision object.null
if decision is not available yetid
:string
* UUID v4 which identifies the verification sessionattemptId
:string
* UUID v4 of the attempt which received a status (as shown inverification.status
field)vendorData
:string | null
* The unique identifier that you created for your end-user.null
if not specifiedendUserId
:string | null
* TheUUID
that you created for your end-user.null
if not specifiedstatus
:string
* Verification status, one ofapproved
,declined
,resubmission_requested
,review
,expired
,abandoned
code
:integer
* Verification session decision code, one of9001
,9102
,9103
,9104
,9121
. For more info, see the verification session decision codesreason
:string | null
* Reason why the verification failedreasonCode
:integer | null
* Reason code of the failed verification. For more info, see the possible codes for a failed verificationdecisionTime
:string
* Timestamp of the decision, represented asUTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset
(ISO 8601)acceptanceTime
:string
* Timestamp of the session generation, represented asUTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset
(ISO 8601)person
:object
* Data about the verified personfirstName
:string | null
* Person's first name as written on the documentlastName
:string | null
* Person's last name as written on the documentdateOfBirth
:string
* Person’s date of birth, represented asYYYY-MM-DD
gender
:string | null
* Person’s gender, represented as M or F, ornull
if not presentnationality
:string | null
* Person’s nationality, represented as ISO 3166alpha-2
oralpha-3
numberidNumber
:string | null
* National identification numberyearOfBirth
:string | null
* Person’s year of birth, represented asYYYY
placeOfBirth
:string | null
* Person’s place of birth…
document
:object
* Data about the verified documentnumber
:string | null
* Document number,[a-zA-Z0-9]
characters onlytype
:string | null
* Document type, one ofPASSPORT
,ID_CARD
,RESIDENCE_PERMIT
,DRIVERS_LICENSE
,VISA
,OTHER
. For more info, see the Supported document types for IDV articlecountry
:string | null
* Document issuing country, represented as ISO 3166alpha-2
codestate
:string | null
* Document issuing state, represented as ISO 3166alpha-2
oralpha-3
code…
additionalVerifiedData
:array
Data that has been optionally verified for the session, depending on the integration. Empty if no additional data was verifiedcomments
:array
(Deprecated) Always returns empty []highRisk
:boolean
(Deprecated) Marked if session was considered high risk or not
technicalData
:object
* Technical data objectip
: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 responseverification
:object
Verification request decision object.null
if decision is not available yetid
:string
UUID v4 which identifies the verification sessionattemptId
:string
UUID v4 of the attempt which received a status (as shown inverification.status
field)vendorData
:string | null
The unique identifier that you created for your end-user.null
if not specifiedendUserId
:string | null
TheUUID
that you created for your end-user.null
if not specifiedstatus
:string
Verification status, one ofapproved
,declined
,resubmission_requested
,review
,expired
,abandoned
code
:integer
Verification session decision code, one of9001
,9102
,9103
,9104
,9121
. For more info, see the verification session decision codesreason
:string | null
Reason why the verification failedreasonCode
:integer | null
Reason code of the failed verification. For more info, see the possible codes for a failed verificationdecisionTime
:string
Timestamp of the decision, represented asUTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset
(ISO 8601)acceptanceTime
:string
Timestamp of the session generation, represented asUTC YYYY-MM-DDTHH:MM:SS.SSS+Timezone Offset
(ISO 8601)person
:object
Data about the verified personfirstName
:string
|null
Person's first name as written on the documentlastName
:string
|null
Person's last name as written on the documentdateOfBirth
:string
Person’s date of birth, represented asYYYY-MM-DD
gender
:string
|null
Person’s gender, represented as M or F, ornull
if not presentnationality
:string
|null
Person’s nationality, represented as ISO 3166alpha-2
oralpha-3
numberidNumber
:string
|null
National identification numberyearOfBirth
:string
|null
Person’s year of birth, represented asYYYY
placeOfBirth
:string
|null
Person’s place of birth…
document
:object
Data about the verified documentnumber
:string
|null
Document number,[a-zA-Z0-9]
characters onlytype
:string
|null
Document type, one ofPASSPORT
,ID_CARD
,RESIDENCE_PERMIT
,DRIVERS_LICENSE
,VISA
,OTHER
. For more info, see the Supported document types for IDV articlecountry
:string
|null
Document issuing country, represented as ISO 3166alpha-2
codestate
:string
|null
Document issuing state, represented as ISO 3166alpha-2
oralpha-3
code…
additionalVerifiedData
:array
Data that has been optionally verified for the session, depending on the integration. Empty if no additional data was verifiedcomments
:array
(Deprecated) Always returns empty []highRisk
:boolean
(Deprecated) Marked if session was considered high risk or not
technicalData
:object
Technical data objectip
: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.
→ See Review verification in Veriff Customer Portal about how to view the session info in the Veriff Customer portal
Status and reason codes
For an approved
session, see:
verification.code
about verification session decision code, one of9001
,9102
,9103
,9104
,9121
verification.status
about verification status, one ofapproved
,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 failedverification.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:
Session lifecycle flow diagram
FAQ
Where can I query the data related to the session and the end-user?
The following endpoints can be used to query data related to the verification session and the end-user:
GET /sessions/{sessionId}/attempts - allows querying the id-s of different attempts done during one verification session, using the
sessionId
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}/media - allows querying info about the media uploaded during the 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 find more info about the public API endpoints listed above, see the API Documentation and API Reference[↗].
Article versioning
Date | Description |
---|---|
Apr 25, 2025 | Missing link added |
Mar 31, 2025 | Documentation published "Hybrid document + selfie IDV" and "Full Auto IDV" articles have been consolidated into this single article. To improve clarity, the content now focuses on the document + selfie IDV solution's features, setup process, and decision data without distinguishing between hybrid and full auto implementation types. |