Error responses
Overview
The identity verification process will attempt to exhaust all available options with a user before eventually terminating the verification process. This will happen as early as possible, if there's a strong evidence suggesting that the user will not achieve the relevant identity checking requirements for the requested scheme.
In the event that a combination scheme is requested (DBS & RTW), the identity verification flow will continue as long as one scheme could still be met.
Failures may include:
- 'Aborted' identity checks: Aborted identity checks are the result of a complete 'dead end' in the journey, meaning an identity profile will not be returned
- Requirements not met: Occurs when an identity profile can be returned, however scheme compliance couldn't be met
- Requirements not met details: Additional information around the failure, explaining which checks were involved, and why they may have failed
When Right to Work is solely requested for a check. The result will only be requirements_met: true, or ABORTED.
A DBS only scheme may return requirements_met: false, in the event the candidate identity was verified, but the current address could not be verified. In this scenario scheme compliance has not been reached, as DBS scheme compliance is made up of Identity & Verified Current Address.
For combination scenarios (DBS & RTW), an individual result is returned for each scheme. However it's important to note that:
ABORTEDwill be returned when the identity verification fails for both DBS & RTW. In this case a reason code is shared for the failure- Passing one scheme does not guarantee a pass in both. For example a user may complete the DBS scheme but not meet the RTW requirements if a UK or Irish Passport/Passport Card was not used in the journey. For such reason, RTW can return requirements not met and a reason code in the combo journey, even if the identity was verified, as opposed to fully aborting the check.
- It is entirely possible to receive an identity profile report but have a
requirements_met:falsefor each scheme.
Reason Codes
When a journey is aborted, either entirely or due to not reaching scheme compliance, a reason code will be returned to explain the failure.
These tables list the reason codes, a description of why they may occur, and the integration type in which they may be returned.
Since some failures can be triggered for multiple reasons, there is a priority for which overall reason code will be used. Details of all failed checks would be available in the failure details.
The priority is as follows:
FRAUD_DETECTEDUNABLE_TO_VALIDATE_DOCUMENTFACE_MATCH_HIGHER_THRESHOLD_VERIFICATION_FAILEDFACE_MATCH_VERIFICATION_FAILEDMANDATORY_DOCUMENT_NOT_PROVIDED
Requirements not met info
| Reason | Description | Digital ID | Embedded IDV |
|---|---|---|---|
| MANDATORY_DOCUMENT_NOT_PROVIDED* | The user does not have sufficient documents to reach the target level of identity verification. *This may be returned as an aborted reason, or a requirements not met reason. | ✅ | ✅ |
| LEVEL_OF_ASSURANCE_NOT_SUFFICIENT* | Level of assurance for the scheme has not been reached. This is specific to combination routes and would occur if the identity has reached a Medium LoC, but not a High if requesting a Standard or Enhanced identity check. *This will only be returned as a requirements not met reason. | ✅ | ✅ |
| UNABLE_TO_VERIFY_ADDRESS* | Identity profile has been generated but candidates address was not verified. *This will only be returned as a requirements not met reason. | ✅ | ✅ |
Aborted
| Reason | Description | Digital ID | Embedded IDV |
|---|---|---|---|
| MANDATORY_DOCUMENT_NOT_PROVIDED* | The user does not have sufficient documents to reach the target level of identity verification. *This may be returned as an aborted reason, or a requirements not met reason. | ✅ | ✅ |
| FRAUD_DETECTED | Suspected fraud for the given identity therefore unable to reach the required identity profile. This should be reviewed. | ✅ | ✅ |
| UNABLE_TO_VALIDATE_DOCUMENT | We have not been able to successfully validate a required document (for reasons other than suspected fraud, e.g. capture error) | ✅ | ✅ |
| MISSING_LIVENESS | Returned if the session does not have a passed liveness check. | ❌ | ✅ |
| IDENTITY_CHECK_FAILED | Additional checks on a user’s identity, required to meet the level of confidence, have not been successful. | ✅ | ✅ |
| UNABLE_TO_COMPLETE_CHECKS | Required checks could not be completed. | ✅ | ✅ |
| COULD_NOT_VERIFY_ADDRESS | Could occur if the address was not verified for any reason after the applicant leaves the session. | ❌ | ✅ |
| FACE_MATCH_VERIFICATION_FAILED | The face match check could not be performed. | ✅ | ✅ |
| FACE_MATCH_HIGHER_THRESHOLD_ VERIFICATION_FAILED | In some circumstances, a higher level of confidence in the face match is required, such as if the presented identity is at higher risk of identity fraud. This reason code is returned if such a higher threshold could not be met. | ✅ | ✅ |
| ACTIVITY_HISTORY_SCORE_INSUFFICIENT | The profile has not reached the required activity history score for the specified scheme. | ❌ | ✅ |
| IDENTITY_FRAUD_SCORE_INSUFFICIENT | The profile has not reached the identity fraud score for the specified scheme. | ❌ | ✅ |
| IDENTITY_FRAUD_AND_ACTIVITY_ HISTORY_SCORES_INSUFFICIENT | The profile has not reached both the identity fraud activity history scores for the specified scheme. | ❌ | ✅ |
| MISSING_FRAUD_LIST_CHECK | This error can arise if a technical problem occurs while checking the identity against a fraud list. | ❌ | ✅ |
| ABANDONED | Expired sessions will eventually be set to ABANDONED, there is approximately a two hour delay between this aborted reason appearing from expiry. | ❌ | ✅ |
Requirements not met details
The requirements not met details structure is a list of objects which contains information to supplement the overall returned reason code. This surfaces information around the specific check, or multiple checks, which may have led to the failure.
The following fields are returned per each object in the structure:
failure_typedocument_typedocument_country_iso_codeaudit_iddetails
| Failure Type | Associated Reason Code(s) |
|---|---|
| ID_DOCUMENT_EXTRACTION | MANDATORY_DOCUMENT_NOT_PROVIDED |
| ID_DOCUMENT_AUTHENTICITY | UNABLE_TO_VALIDATE_DOCUMENT MISSING_FRAUD_LIST_CHECK FRAUD_DETECTED The failure reason details will be populated with the check report recommendation. The list can be found here |
| ID_DOCUMENT_COUNTRY | MANDATORY_DOCUMENT_NOT_PROVIDED |
| ID_DOCUMENT_FACE_MATCH | FACE_MATCH_VERIFICATION_FAILED FACE_MATCH_VERIFICATION_HIGHER_THRESHOLD_FAILED FRAUD_DETECTED The failure reason details will be populated with the check report recommendation. The list can be found here |
| ID_DOCUMENT_ADDRESS_VERIFICATION | See ID Check table below |
| IDENTITY_CHECK | See ID Check table below |
| LIVENESS | MISSING_LIVENESS |
| UNLINKED_DOCUMENT_EVIDENCE | MANDATORY_DOCUMENT_NOT_PROVIDED Documentary evidence may be 'unlinked' if either the name, dob, or both do not match to additional document evidence in the requested scheme. |
ID Check
This table lists the failure details codes that can be returned alongside the failure type of IDENTITY_CHECK.
| Provider | Details | Reason code | Description |
|---|---|---|---|
| Third party identity | ERROR_WHEN_PERFORMING_CHECK | UNABLE_TO_COMPLETE_CHECKS | Something went wrong when calling the third party identity check server |
| Third party identity | SUSPECTED_FRAUD | FRAUD_DETECTED | The third party identity check returns a suspected fraudulent check on the provided identity details |
| Synectics | SYNECTICS_INDICATED_FRAUD | FRAUD_DETECTED | Synectics scored user 0 in identity fraud |
| Synectics | FAILED_TO_REACH_REQUIRED_ IDENTITY_FRAUD_SCORE_2 | IDENTITY_FRAUD_SCORE_ INSUFFICIENT IDENTITY_FRAUD_AND_ ACTIVITY_HISTORY_SCORES_ INSUFFICIENT | When attempting H2A, we failed to obtain an identity fraud score of at least 2 |
| Synectics | FAILED_TO_REACH_REQUIRED_ ACTIVITY_HISTORY_SCORE_3 | IDENTITY_FRAUD_SCORE_ INSUFFICIENT IDENTITY_FRAUD_AND_ ACTIVITY_HISTORY_SCORES_ INSUFFICIENT | When attempting H2A, we failed to obtain an activity history score of at least 3 |
| CRA | ERROR_WHEN_PERFORMING_CHECK | UNABLE_TO_COMPLETE_CHECKS | Something when wrong when calling the TransUnion server |
| CRA | PEP_WARNING | IDENTITY_CHECK_FAILED | CRA check flagged the user as PEP or the check was not performed (i.e. the user's current address is claimed to be outside of the UK). If flagged as PEP, additional verification checks failed. |
| CRA | DECEASED_WARNING | IDENTITY_CHECK_FAILED | CRA check flagged the user as deceased or the check was not performed (i.e. the user's current address is claimed to be outside of the UK) |
| CRA | UNABLE_TO_VERIFY_ADDRESS | For DBS basic: When the address could not be verified | |
| CRA | UNABLE_TO_VERIFY_ADDRESS | IDENTITY_CHECK_FAILED | For DBS standard/enhanced: When the address could not be verified |
| CRA | UNABLE_TO_VERIFY_IDENTITY | IDENTITY_CHECK_FAILED | When the CRA check failed to find a match for the name or DOB |
ID Doc Extraction
This table lists the failure details codes that can be returned alongside the failure type of ID_DOCUMENT_EXTRACTION.
| Details | Description |
|---|---|
| POOR_FOCUS | The image is too blurry to read the document details |
| POOR_LIGHT | The provided document image was not taken in adequate light |
| TOO_LIGHT | The provided document image has too much light or glare |
| POOR_DOC | The image is too blurry to read the document details |
| PARTIAL_SIDE_DOC | Parts of the document are missing from the image (i.e. missing side) |
| PARTIAL_PHOTO | Parts of the document side are missing from the image |
| DOCUMENT_COPY | The document has not been presented in its original form |
| BLACK_AND_WHITE_IMAGE | The document image provided is not in colour |
| NO_DOCUMENT | We could not detect a document in the captured image |
| TEMPLATE | All parts of the document template could not be detected |
| USER_DOES_NOT_HAVE_REQUESTED_DOCUMENTS | If the user did not provide all, or any of the documents required for the scheme, and there is no other failure reason |
Examples
The below shows an example structure for the whole error object.
"identity_profile": { "result": "ABORTED", "failure_reason": { "reason_code": "UNABLE_TO_VALIDATE_DOCUMENT", "requirements_not_met_details": [ { "failure_type": "ID_DOCUMENT_FACE_MATCH", "document_type": "PASSPORT", "document_country_iso_code": "GBR", "audit_id": "", "details": "PARTIAL_PHOTO" }, { "failure_type": "ID_DOCUMENT_AUTHENTICITY", "document_type": "PASSPORT", "document_country_iso_code": "GBR", "audit_id": "", "details": "OBJECT_OBSTRUCTION" } ] }}