/v1/sessions/{id}/decision

Get
/v1/sessions/{id}/decision

The session related to the sessionId needs to have one of 9000-code statuses, otherwise you will see Decision not available in the response payload

Note: always ensure that you use the correct API URL to send requests. See the API URL section for more info.


Security
API Key
Header parameter namex-auth-client

Your integration's API key (occasionally referred to the "Token", "API public key" or "Publishable key")

Header parameters
x-hmac-signature
stringRequired

Session id signed with the shared secret key

Path parameters
id
stringRequired

Session id

Responses
200

Decision of the session

Expand All
object
status
string

API request success

Examplesuccess
verification
object | null

Verification request decision object. null if decision is not available yet

id
string (uuid)

UUID v4 which identifies the verification session

Example12df6045-3846-3e45-946a-14fa6136d78b
attemptId
string (uuid)

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

Example6cab5b0-c506-47a6-922d-6ae3b72ca172
acceptanceTime
string (Combined ISO 8601 date and time in UTC, YYYY-MM-DDTHH:MM:SSS+Timezone Offset)

Timestamp of the session generation

Example2024-01-01T00:00:00.000000Z
decisionTime
string (Combined ISO 8601 date and time in UTC, YYYY-MM-DDTHH:MM:SSS+Timezone Offset) | null

Timestamp of the decision.

Example2024-01-01T00:00:00.000000Z
code
number (integer)

Verification response code, one of 9001, 9102, 9103, 9104, 9121

Example9001
vendorData
string | null

The unique identifier that you created for your end-user. It can be max 1,000 characters long and contain only non-semantic data that can not be resolved or used outside your systems or environments. Veriff returns it unmodified in webhooks and API response payloads, or as null if not provided

Example1234567890
endUserId
string (uuid) | null

The UUID that you created for your end-user, that can not be resolved or used outside your systems or environments. Veriff returns it unmodified in webhooks and API response payloads, or as null if not provided.

Examplec1de400b-1877-4284-8494-071d37916197
status
string

Status of the verification session

Exampleresubmission_requested
reason
string | null

Reason of failed verification

ExampleDocument not recognized
reasonCode
number (integer) | null

Reason code of failed verification

Example647
person
object (DecisionPerson)
firstName
string | null

Person's first name

ExampleSARAH
lastName
string | null

Person's last name

ExampleMORGAN
idNumber
string | null

National identification number

Example123456789
gender
string | null

Person's gender

Valid values[ "\"M\"", "\"F\"", "\"`null`\"" ]
ExampleF
citizenship
string | null Deprecated

Always returns null

Examplenull
dateOfBirth
string (YYYY-MM-DD) | null

Person's date of birth

Example2001-01-01
yearOfBirth
string (YYYY-MM-DD) | null

Person's year of birth

Example2001
placeOfBirth
string | null

Person's place of birth

ExampleANYTOWN
nationality
string ( ISO 3166-1 Alpha-2) | null

Person's nationality, as ISO country code

ExampleUS
addresses
Array of object (DecisionAddress) | null

Address data from the document as array of strings

object
fullAddress
string | null

Address as single string

Example123, Main Street, My County, Anytown 12345
parsedAddress
object

Object with parsed fullAddress. Optional, depending on integration

city
string | null

Any human settlement, including cities, towns, villages, hamlets, localities, etc.

ExampleMUMBAI
cityDistrict
string | null

Boroughs or districts within a city that serve some official purpose e.g. "Brooklyn" or "Hackney" or "Bratislava IV"

ExampleAny District
country
string | null

Sovereign nations and their dependent territories, anything with an ISO-3166 code

ExampleIN
countryRegion
string | null

Informal subdivision of a country without any political status

ExampleSample Region
entrance
string | null

Numbered/lettered entrance

ExampleB
house
string | null

Name of the venue or the building

ExampleEXPRESS BUILDING
houseNumber
string | null

External (street-facing) building number

Example9-10
island
string | null

Named islands e.g., "Maui"

ExampleSmall Island
level
string | null

Expressions indicating a floor number e.g., "3rd Floor", "Ground Floor", etc.

Example1st floor
near
string | null

Phrases like "in", "near", etc. used after a category phrase to help with parsing queries like "restaurants in Brooklyn"

Examplenull
road
string | null

Name of the street(s)

Example
poBox
string | null

Post office box: typically found in non-physical (mail-only) addresses

Example123452
postcode
string | null

Postal codes used for mail sorting

Example123456
staircase
string | null

Numbered/lettered staircase

ExampleB
sate
string | null

A first-level administrative division. For example, Scotland, Northern Ireland, Wales, and England in the UK are mapped to "state" as well (convention used in OSM, GeoPlanet, etc.)

Examplenull
sateDistrict
string | null

Usually a second-level administrative division or county

Examplenull
suburb
string | null

Usually an unofficial neighbourhood name like "Harlem", "South Bronx", or "Crown Heights"

Examplenull
unit
string | null

An apartment, unit, office, lot, or other secondary unit designator

ExampleBuilding A
worldRegion
string | null

Currently only used for appending “West Indies” after the country name, a pattern frequently used in the English-speaking Caribbean e.g. “Jamaica, West Indies”

Examplenull
fullName
string | null

Full name of the person. Optional, available only for Indian Aadhaar cards registry based verification

ExampleSARAH MORGAN
pepSanctionMatch
string | null

Legacy field, may return incorrect results, should be ignored

Examplepossible match
ineIdentifier
string

INE identification number. When this is returned, the ifeIdentifier is not present

Example000000101
ifeIdentifier
string

IFE identification number. When this is returned, the ineIdentifier is not present

Example000000001
occupation
string | null

Occupation data from the document

ExampleSales Representative
employer
string | null

Employer's name from the document

ExampleAny Company LLC
foreignerStatus
string | null

Foreigner status field from the document

ExampleEXTRANJERO
extraNames
string | null

Additional name from the document

ExampleNOM D'USAGE
document
object (DecisionDocument)
number
string | null

Document number, [a-zA-Z0-9] characters only

ExampleMORGA753116SM9IJ
type
string | null

Document type

Valid values[ "\"PASSPORT\"", "\"ID_CARD\"", "\"RESIDENCE_PERMIT\"", "\"DRIVERS_LICENSE\"", "\"VISA\"", "\"OTHER\"" ]
ExampleDRIVERS_LICENSE
country
string ( ISO 3166-1 Alpha-2 country code) | null

Document country, as ISO country code

ExampleES
remarks
string | null

Data extracted from the document's remarks field

ExampleWORK PERMITTED
state
string ( ISO 3166-1 Alpha-2 or Alpha-3 country code) | null

Document issuing state, as ISO 3166 alpha-2 or alpha-3 code. null when the state data isnot present on the document

ExampleNY
validFrom
string (YYYY-MM-DD) | null

Date from when the document is valid

Example2018-04-20
validUntil
string (YYYY-MM-DD) | null

Date until when the document is valid

Example2028-04-20
specimen
object

Contains additional data about the particular document type. Optional, depending on integration.

containsContactlessChip
boolean

Indicates if the document contains a contactless chip (NFC)

ExampleFalse
firstIssuedDate
string (YYYY-MM-DD)

Indicates the first issue date of the identity document template

Example2020-01-01
lastIssuedDate
string (YYYY-MM-DD)

Indicates the last issue date of the identity document template

Example2021-01-02
nistVersion
string

Indicates the version of the US National Institute of Standards and Technology guidelines

Example1.2.3
digitalDocument
boolean

Indicates if the document is a digital template identity document

ExampleFalse
nonStandardDrivingLicense
string

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)

ExampleFalse
militaryDocument
boolean

Indicates if the document is issued to a military personnel/staff or personnel's family

ExampleFalse
temporaryEmergencyDocument
boolean

Indicates if the document is a temporary identity document

ExampleFalse
asylumRefugeeDocument
boolean

Indicates if it is a document that is issued exclusively to asylum seekers or refugees

ExampleFalse
ICAOStandardizedDocument
boolean

Indicates if the document is under the standards of International Civil Aviation Organization

ExampleFalse
notNationalIdCard
boolean

Indicates if the identity card is not a national ID card (e.g., it is a social security card, tax ID, electoral ID)

ExampleTrue
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 identity

Exampleprimary
hasSecurityRisk
boolean

Indicates if the document has properties that can increase the chance of document tampering

ExampleFalse
placeOfIssue
string | null

Place where document was issued. Optional, depending on integration

ExampleMADRID
firstIssue
string (YYYY-MM-DD) | null

Date of document first issue. Optional, depending on integration

Example2018-04-20
issueNumber
string | null

Document issue number. Optional, depending on integration

Example01
issuedBy
string | null

Document issuing authority. Optional, depending on integration

ExampleISSUER
nfcValidated
boolean

Biometric document data has been successfully decoded. Optional, depending on integration

ExampleTrue
residencePermitType
string | null

Type of the residence permit type from the document. Optional, depending on integration

ExampleC
portraitIsVisible
boolean

Indicates that the portrait image is visible in the session and its quality is sufficient to perform verification. Optional, depending on the integration

ExampleTrue
signatureIsVisible
boolean

Indicates that the signature is present on the document and readable to perform the verification. Optional, depending on the integration

ExampleTrue
additionalVerifiedData
Array of object (DecisionVerificationAdditionalVerifiedData)

Data which has been optionally verified for session

object
driversLicenseCategory
object

Indicates whether the driver's license has the appropriate category.Optional, depending on integration

B
boolean
ExampleTrue
driversLicenseCategoryFrom
object

Date when the driving license category was obtained. Optional, depending on integration

B
string (YYYY-MM-DD)
Example2019-10-06
driversLicenseCategoryUntil
object

Driving license category expiry date.Optional, depending on integration

B
string (YYYY-MM-DD)
Example2015-10-05
driversLicenseNumber
string

Number of the driver's license.Optional, depending on integration

estimatedAge
number (integer)

An integer representing the estimated age. Optional, depending on integration

Example28
estimatedGender
number (float)

A float representing the estimated gender. Values closer to 0.0 indicate 'male', values closer to 1.0 indicate 'female'. Optional, depending on integration

Example0.9
processNumber
string

Process number (e.g., "Trámite №") from the document

Example00005
cpfValidation
object

Brazilian individual taxpayer registry (CPF) validation check object. Optional, depending on integration

status
string | null

Status of the entry in the registry. One of CPF 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))

ExampleCPF is validated
cpfNumber
string | null

Brazilian individual taxpayer registry (CPF) number of the person

Example1234569
name
string | null

Person's name in the CPF

ExampleSARAH MORGAN
dateOfBirth
string (YYYY-DD-MM)

Person's date of birth in the CPF

Example1967-03-30
dateOfDeath
string (YYYY-DD-MM) | null

Person's date of death in the CPF

Example
ineBiometricValidation
object

INE Biometric Database Verification check object. Optional, available only when the INE Biometric Validation check has been enabled for the integration

faceMatch
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 in faceMatchPercentage (see below). null if the check could not be completed

ExampleTrue
faceMatchPercentage
number (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 completed

Example89
responseStatus
string | null

Indicates the response received from the service provider. One of success or failure; or null if the check could not be completed

Examplesuccess
validationResults
Array of object (ValidationResults)

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 integration

object
registryName
string

Name of the registry

ExampleUSA - Credit + US Identity Graph (US15)
firstName
string

Indicates the match level of person's first name data

Valid values[ "\"MATCH\"", "\"NO_MATCH\"", "\"PARTIAL_MATCH\"", "\"INVALID\"", "\"NO_INPUT\"", "\"NO_DATA\"" ]
ExampleMATCH
lastName
string

Indicates the match level of person's last name data

Valid values[ "\"MATCH\"", "\"NO_MATCH\"", "\"PARTIAL_MATCH\"", "\"INVALID\"", "\"NO_INPUT\"", "\"NO_DATA\"" ]
ExampleMATCH
dateOfBirth
string

Indicates the match level of person's date of birth data

Valid values[ "\"MATCH\"", "\"NO_MATCH\"", "\"PARTIAL_MATCH\"", "\"INVALID\"", "\"NO_INPUT\"", "\"NO_DATA\"" ]
ExampleNO_INPUT
address
string

Indicates the match level of person's address data

Valid values[ "\"MATCH\"", "\"NO_MATCH\"", "\"PARTIAL_MATCH\"", "\"INVALID\"", "\"NO_INPUT\"", "\"NO_DATA\"" ]
ExamplePARTIAL_MATCH
city
string

Indicates the match level of person's address data, specifically the city

Valid values[ "\"MATCH\"", "\"NO_MATCH\"", "\"PARTIAL_MATCH\"", "\"INVALID\"", "\"NO_INPUT\"", "\"NO_DATA\"" ]
ExampleMATCH
state
string

Indicates the match level of person's address data, specifically the state

Valid values[ "\"MATCH\"", "\"NO_MATCH\"", "\"PARTIAL_MATCH\"", "\"INVALID\"", "\"NO_INPUT\"", "\"NO_DATA\"" ]
ExampleMATCH
zip
string

Indicates the match level of person's address data, specifically the zip code (post code)

Valid values[ "\"MATCH\"", "\"NO_MATCH\"", "\"PARTIAL_MATCH\"", "\"INVALID\"", "\"NO_INPUT\"", "\"NO_DATA\"" ]
ExampleMATCH
idNumber
string

Indicates the match level of person's identity number or SNN number data

Valid values[ "\"MATCH\"", "\"NO_MATCH\"", "\"PARTIAL_MATCH\"", "\"INVALID\"", "\"NO_INPUT\"", "\"NO_DATA\"" ]
ExampleNO_DATA
riskScore
object (DecisionRiskScore)
score
number (float)

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 Customer Portal, the range is shown as 1–100.

Example0.01
riskLabels
Array of object (DecisionRiskLabel)
object
label
string

Name of the risk label

Examplesession_face_crosslinked_with_multiple_sessions
category
string

Category of the risk label

Valid values[ "\"`client_data_mismatch`\"", "\" `cross-links`\"", "\"`device`\"", "\"`document`\"", "\"`images`\"", "\"`network`\"", "\"`session`\"", "\"`person`\"" ]
Examplecrosslinks
sessionIds
Array of string

Array of verification IDs that are referenced to the particular risk label

Example[ "123e4567-e89b-12d3-a456-426614174000" ]
string (array of strings)
biometricAuthentication
object

Object containing data about the biometric authentication. Optional, available only when using the Biometric Authentication solution

matchedSessionId
string (uuid) | null

Refers to the verification session ID which face matched

Exampled40edb60-6ae6-4475-be72-84b81669cce6
matchedSessionVendorData
string | null

Refers to the verification session vendorData which the face matched

Example12345678
matchedSessionEndUserId
string | null

Refers to the verification session endUserId which the face matched

Examplea1b2c35d-eš8f7-6d5e-3cd2-a1b2c35db3d4
details
object

Lists the results of different checks that were made to verify the end-user. Data is shown as key-value pairs. The key represents the check name and the value represents the check result

Example{}
comments
Array of string Deprecated

Always returns empty array

Example[]
string
technicalData
object

Technical data object

ip
string | null

IP of the device from which the verification was made

Example192.158.1.38
400

Bad request

object
status
string
Valid values[ "\"fail\"" ]
Examplefail
code
string
Example1101
message
string
ExampleValidation failed
401

Unauthorized

object
status
string
Valid values[ "\"fail\"" ]
Examplefail
code
string
Example1101
message
string
ExampleMandatory X-AUTH-CLIENT header containing the API key is missing from the request.
404

Session not found

object
status
string
Valid values[ "\"fail\"" ]
Examplefail
code
string
Example1101
message
string
ExampleResource not found
500

Internal server error

object
status
string
Valid values[ "\"fail\"" ]
Examplefail
code
string
Example1101
message
string
ExampleSomething went wrong



Document Versioning

Article Versioning

Date

Description

May 2, 2025

validationResults array added to support US Database Verification solution

Aprl 7, 2025

attemptId parameter added

Description of person.pepSanctionMatch updated

Mar 12, 2025

Documentation published