Most of the verification solutions use the decision webhook to post data about the verification decision, verified data and checks, and session info (e.g. session ID, attempt ID, different timestamps).
The payload is sent to Webhook decisions URL
, which you need to set up the webhook in the Veriff Customer Portal.
→ See Webhooks Guide > Set up webhooks sub-section for detailed overview of the setup process
When is decision webhook sent?
In most cases Veriff sends the decision webhook instantly after a decision is made, with an exception to resubmission_requested
status. In case resubmission is required, Veriff allows the end-user to resubmit the session data instantly without the need to exit the flow. If the end-user does not do it within 5 minutes, Veriff sends out a webhook with the resubmission_requested
decision.
Prerequisites
- Make sure you have access to the Veriff Customer Portal
- Set up webhook URL(s) on your side and have them at hand
- Make sure they match the Webhook URL requirements
- Make sure your system is able to handle Webhooks receipt, delivery and resending requirements
- Secure your communication, check the HMAC Authentication and Endpoint Security article
- Make sure your system is able to handle the Backwards compatible changes
5.Proceed to Decision webhook setup section below
Decision webhook setup
Log in to the Veriff Customer Portal
Navigate to the Integrations page via the top menu and open the relevant integration
On the integration's page, select the Settings tab
Under the title Integration settings you see a list of webhooks
Fill in the
Webhook decisions URL
→ See Webhooks Guide > Set up webhooks sub-section for detailed overview of the setup process
Additional notes
Driver's license categories extraction
Contact your Solutions Engineer who can activate the feature for your integration, so it is possible to extract the
validFrom
andvalidUntil
dates from a driver's license.
riskScore
parameterThis is a numerical value representing the overall risk associated with the session. Lower score indicates higher confidence in that the session is genuine.
In the API and webhooks payloads, the range is shown as an integer in the range of 0.0–1.0
In the Veriff Customer Portal, the range is shown as 1–100
pepSanctionMatch
parameterWarning: legacy field, may return incorrect result.
If you are running the AML checks, please see the watchlist-screening webhook for accurate data.
If you are running the UKDIATF M1B checks, accurate data is in the decision webhook payload, in
verification.additionalVerifiedData.UKTFResult.PEP
string.
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",
"addresses": [
{
"fullAddress": "1234 Ridge Road, Indiana, 56789 USA",
"parsedAddress": {
"city": null,
"unit": null,
"state": "Indiana",
"street": "1234 Ridge Road",
"country": "USA",
"postcode": "56789",
"houseNumber": "null"
}
}
],
"fullName": "SARAH MORGAN",
"occupation": "Engineer",
"employer": "Any Company LLC",
"foreignerStatus": "EXTRANJERO",
"extraNames": "NOM D'USAGE",
"title": "DR",
"pepSanctionMatch": null,
"citizenship": null,
},
"document": {
"number": "MORGA753116SM9IJ",
"validFrom": null,
"validUntil": "2022-04-20",
"type": "DRIVERS_LICENSE",
"country": "US",
"state": "NY",
"placeOfIssue": "ALBANY",
"firstIssue": "2015-03-21",
"issueNumber": "01",
"issuedBy": "ISSUER",
"remarks": "WORK PERMITTED",
"nfcValidated": true,
"residencePermitType": "C",
"portraitIsVisible": "true",
"signatureIsVisible": "true",
"specimen": {
"containsContactlessChip": false,
"firstIssuedDate": "2020-01-01",
"lastIssuedDate": "2021-01-02",
"nistVersion": "1.2.3",
"digitalDocument": true,
"nonStandardDrivingLicense": false,
"militaryDocument": false,
"temporaryEmergencyDocument": false,
"asylumRefugeeDocument": false,
"ICAOStandardizedDocument": false,
"notNationalIdCard": true,
"legalStatus": "primary",
"hasSecurityRisk": false
}
},
"additionalVerifiedData": {
"driversLicenseNumber": "1234569",
"driversLicenseCategory": {
"B": true
},
"driversLicenseCategoryFrom": {
"B": "2019-10-06"
},
"driversLicenseCategoryUntil": {
"B": "2025-10-05"
},
"driversLicenseCategories": ["B", "C", "5", "6"],
"estimatedAge": 32,
"estimatedGender": 0.613,
"processNumber": "12345678912 1234",
"cpfValidation": {
"status": "CPF is validated",
"cpfNumber": "123456789",
"name": "SARAH MORGAN",
"dateOfBirth": "1967-03-30",
"yearOfDeath": null
},
"ineBiometricRegistryValidation": {
"faceMatch": true,
"faceMatchPercentage": 89,
"responseStatus": "success"
},
"registryValidation": {
"countryRegistry": "CO",
"registryName": "resigo",
"fullNameSimilarity": 80,
"documentValid": true,
"personIsAlive": true
},
"proofOfAddress": {
"nameMatch": true,
"nameMatchPercentage": 100.00
"documentType": "UTILITY_BILL"
},
"validationResults": [
{
"registryName": "USA - Credit + US Identity Graph (US15)",
"firstName": "MATCH",
"lastName": "MATCH",
"dateOfBirth": "NO_INPUT",
"address": "PARTIAL_MATCH",
"city": "MATCH",
"state": "MATCH",
"zip": "MATCH",
"idNumber": "NO_DATA"
}
]
},
"riskScore": {
"score": 0.12
},
"riskLabels": [
{
"label": "document_integration_...",
"category": "document",
"sessionIds": ["5a2358e7-fd31-4fcb-a23f-4d76651ba68a"]
}],
"biometricAuthentication": {
"matchedSessionId": "d40edb60-6ae6-4475-be72-84b81669cce6",
"matchedSessionEndUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",
"matchedSessionVendorData": "User001",
"details": {
...
}
},
"comments": []
},
"highRisk": false,
"technicalData": {
"ip": "186.153.67.122"
}
}
Request properties explained
*Always sent, irrespective of product or solution used
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 birthaddresses
:array
Optional, depending on the integrationfullAddress
:string | null
Address as single stringparsedAddress
:object
Object with parsedfullAddress
. Optional, depending on the integrationcity
:string | null
Any human settlement, including cities, towns, villages, hamlets, localities, etc.country
:string | null
Sovereign nations and their dependent territories (ISO-3166)houseNumber
:string | null
External (street-facing) building numberpostcode
:string | null
Postal codes used for mail sortingstate
:string | null
A first-level administrative divisionstreet
:string | null
Street nameunit
:string | null
An apartment, unit, office, lot, or other secondary unit designator
fullName
:string | null
Full name of the person. Optional, only for Indian Aadhaar cards registry based verificationoccupation
:string
Occupation data from the document. Optional, depending on the integrationemployer
:string
Employer's name from the document. Optional, depending on the integrationforeignerStatus
:string
Foreigner status field from the document. Optional, depending on the integrationextraNames
:string
Additional name from the document. Optional, depending on the integrationtitle
:string
Person’s title extracted from the document. Optional, depending on the integrationifeIdentifier
:string | null
The voter's card identifier (OCR). Optional, only for Mexican registries verificationineIdentifier
:string | null
The citizen's identifier (Identificador del Ciudadano). Optional, only for Mexican registries verificationpepSanctionMatch
:string | null
Legacy field, may return incorrect result, should be ignoredcitizenship
:null
Deprecated, always returns null
document
:object
* 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
coderemarks
:string
Data extracted from document’s remarks fieldvalidUntil
:string | null
Document is valid until date, represented asYYYY-MM-DD
. Optional, must be configured for your integration by the Solutions EngineervalidFrom
:string | null
Document is valid from date, represented asYYYY-MM-DD
. Optional, must be configured for your integration by the Solutions EngineerplaceOfIssue
:string | null
Place where document was issued. Optional, depending on the integrationfirstIssue
:string | null
Date of document first issue, represented asYYYY-MM-DD
. Optional, depending on the integrationissueNumber
:string | null
Document issue number. Optional, depending on the integrationissuedBy
:string | null
Document issuing authority. Optional, depending on the integrationnfcValidated
:boolean
Indicates if the biometric document data has been successfully decoded. Optional, only when NFC validation has been enabled for the integrationresidencePermitType
:string
Type of the residence permit, as shown on the document. Optional, depending on the integrationportraitIsVisible
:boolean
Indicates that the portrait image is visible in the session and its quality is sufficient to perform verification. Optional, depending on the integrationsignatureIsVisible
:boolean
Indicates that the signature is present on the document and readable to perform the verification. Optional, depending on the integrationspecimen
:object
Contains additional data about the particular document type. Optional, depending on integrationcontainsContactlessChip
:boolean
Indicates if the document contains a contactless chip (NFC)firstIssuedDate
:string
Indicates the first issue date of the identity document template, as YYYY-MM-DDlastIssuedDate
:string
Indicates the last issue date of the identity document template, as YYYY-MM-DDnistVersion
:string
Indicates the version of the US National Institute of Standards and Technology guidelinesdigitalDocument
:boolean
Indicates if the document is a digital template identity documentnonStandardDrivingLicense
:boolean
Indicates if the driving permit is different from the standard driver's licence (e.g. it is a learner's license, temporary driver's license, permit to drive boats)militaryDocument
:boolean
Indicates if the document is issued to a military personnel/staff or personnel's familytemporaryEmergencyDocument
:boolean
Indicates if the document is a temporary identity documentasylumRefugeeDocument
:boolean
Indicates if it is a document that is issued exclusively to asylum seekers or refugeesICAOStandardizedDocument
:boolean
Indicates if the document is under the standards of International Civil Aviation OrganizationnotNationalIdCard
:boolean
Indicates if the identity card is not a national ID card (e.g., social security card, tax ID, electoral ID)legalStatus
:string
|null
Indicates the legal status of the identity document in the country of issuance. One of primary, secondary, tertiary, indicating to what extent the document is accepted as legal proof of identityhasSecurityRisk
:boolean
Indicates if the document has properties that can increase the chance of document tampering
additionalVerifiedData
:object
Data that has been optionally verified for the session. Optional, depending on the integrationdriversLicenseNumber
:string
Number of the driver's license. Optional, depending on the integrationdriversLicenseCategory
:object
Indicates the driver’s licence category/ies. Optional, the presence of this property depends on drivers licence category extraction being enabled for the integration.B
:Boolean | null
driversLicenseCategoryFrom
:object
Date when the driving license category was obtained. Optional, depending on the integrationB
:string | null
Category is valid from date, represented asYYYY-MM-DD
driversLicenseCategoryUntil
:object
Driving license category expiry date. Optional, depending on the integrationB
:string | null
Category is valid until date, represented asYYYY-MM-DD
driversLicenseCategories
:array
List of category types visible on the driver's licenseestimatedAge
:number
Estimated age. Optional, depending on the integrationestimatedGender
:number
Estimated gender, values closer to 0.0 indicate 'male', values closer to 1.0 indicate 'female'. Optional, depending on the integrationUKTFCheckResult
:array
Array of UK DIATF checks results. Optional, only for customers with Veriff UK DIATF solutioncpfValidation
:object | null
Brazilian individual taxpayer registry (CPF) validation check object. Optional, only for customers with Brazilian registry checksstatus
:string | null
Status of the entry in the registry, one ofCPF is validated
,CPF is suspended
,CPF holder is deceased
,CPF is pending regularization
,CPF is cancelled
(was a duplicate),Cancelled craft
(meaning that it was cancelled due to reasons other than being a duplicate)cpfNumber
:string | null
Brazilian individual taxpayer registry (CPF) number of the personname
:string | null
Person's name in the CPFdateOfBirth
:string | null
Person's date of birth in the CPF asYYYY-MM-DD
yearOfDeath
:string | nul
l Person's year of death in the CPF asYYYY-MM-DD
processNumber
:string
Process number (e.g., "Trámite №") from the document. Optional, depending on the integrationineBiometricRegistryValidation
: object INE Biometric Database Verification check object. Optional, available only when the INE Biometric Validation check has been enabled for the integrationfaceMatch
:boolean | null
Indicates if the person's selfie image is a match with their image in the registry. This decision is made based on the value returned infaceMatchPercentage
(see below).null
if the check could not be completedfaceMatchPercentage
:integer | null
Indicates the level of similarity the system thinks the matched images have, in the range of 0-100. Values ≥85 indicate a match; values <85 indicate that images do not match.null
if the check could not be completedresponseStatus
:string | null
Indicates the response received from the service provider. One of success or failure; ornull
if the check could not be completed
registryValidation
:object
Registry validation check object. Optional, available only when the registry validation check has been enabled for the integration (currently available for Colombia registries)countryRegistry
:string
Country of the registryregistryName
:string
Name of the registryfullNameSimilarity
:number
Similarity of the full name in the registry to the full name in the documentdocumentValid
:boolean
Indicates if the document is valid in the registrypersonIsAlive
:boolean
Indicates if the person is alive in the registry
proofOfAddress
:object
Proof of address data. Optional, depending on integration.nameMatch
:boolean
Indicates if the name on the proof of address document matches the name from the initial request data.null
if the check could not be completed.nameMatchPercentage
:float
Indicates the level of similarity the matched names have, in the range of 0.00-100.00.null
if the check could not be completed.documentType
:string
Indicates the type of the proof of address document.null
if the check could not be completed.
validationResults
:array
Data that has been optionally verified for the US Database Verification session, depending on the integration. Empty if no additional data was verified. Optional, depending on integrationregistryName
:string
Name of the registryfirstName
:string
Indicates the match level of person’s first name datalastName
:string
Indicates the match level of person’s last name datadateOfBirth
:string
Indicates the match level of person’s date of birth dataaddress
:string
Indicates the match level of person’s address datacity
:string
Indicates the match level of person’s address data, specifically citystate
:string
Indicates the match level of person’s address data, specifically statezip
:string
Indicates the match level of person’s address data, specifically zip code (post code)idNumber
:string
Indicates the match level of person’s identity number or SNN number data
riskScore
:object
Data about the risk score. Optional, depending on the integrationscore
:number
A float in the range of 0.0–1.0. Numerical value representing the overall risk associated with the session. Lower score indicates more confidence in that the session is genuine. Note: in the Veriff environment, the range is shown as 1–100.
riskLabels
:array
Array of risk labels related to the session. Optional, the presence of this property depends on risk labels being enabled for the integration. Log in to Customer portal to see the Risk Insights and Crosslinks[↗] article in Veriff Knowledge Baselabel
:string
Name of the risk labelcategory
:string
Risk label category, one ofclient_data_mismatch
,crosslinks
,device
,document
,images
,network
,session
,person
sessionIds
:array
Array of verification IDs that are referenced to the particular risk label
biometricAuthentication
object
Biometric Authentication data object. Optional, the presence of this property depends on biometric authentication being enabled for the integrationmatchedSessionId
:string | null
UUID v4 which refers to the verification session ID which face matchedmatchedSessionEndUserId
:string | null
Refers to the verification session endUserId which the face matchedmatchedSessionVendorData
:string | null
UUID v4 which refers to the verification session vendor data or end-user UUID which face matcheddetails
:object
Lists the results of different checks that were made to verify the end-user. Log in to Customer portal to see the Risk Insights and Crosslinks[↗] article in Veriff Knowledge Base
comments
: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
Article versioning
Date | Description |
---|---|
Apr 12, 2025 |
|
Mar 12, 2025 | Documentation published |