Usage
Use this API to get the final verification result.
Base URL by Region
The base URL you should use depends on the region where your services are hosted. Below are the available URLs for each region. By default, the EU region URL is used.
- EU (Default):
https://api.idwise.com/
- UAE:
https://api-uae.idwise.com/
- Qatar:
https://api-qat.idwise.com/
Authentication
Please refer to the API Credentials and Authentication page for more detailed information.
Table of Content
In this page, you'll find detailed documentation about the following models:
- Response Model
Response Model
Here is a sample top-level response you'll get from this API:
{
"journey_id": "12d62f80e15c1d50ff23db54",
"customer_id": "123628d8-e456-4375-8ff6-6e84f54f8743",
"flow_id": "6e84f54f8743-f345-7523-7ed4-342528d8",
"reference_number": "abc-123-FE13",
"start_time": "2023-01-26T08:12:00.962462",
"end_time": "2023-01-26T08:13:00.454774",
"system_decision": "Refer",
"manual_decision": null,
"final_decision": "Refer",
"model_version": "3.0",
"documents": {"document_id": DocumentModel},
"selfie": {SelfieModel},
"rule_results": {"rule_id": RuleResultModel},
"applicant": {ApplicantModel},
"aml": {AMLModel},
"screening_checks": {"model_id": ScreeningChecksModel},
"device_intelligence": DeviceIntelligenceModel
}
Property | Description |
---|---|
journey_id |
Type: |
customer_id |
Type: |
flow_id |
Type: |
reference_number |
Type: |
start_time |
Type: |
end_time |
Type: |
Type: |
|
Type: |
|
final_decision |
Type: |
model_version |
Type: |
Type: |
|
Type: |
|
Type: |
|
**Type: ** |
|
**Type: ** |
|
Type: |
|
Type: |
System Decision Enum
Enum Value | Description |
---|---|
Incomplete | The journey has not yet been completed, so no decision can be made. |
Complete | The journey was successfully completed and passed all configured checks and rules. A Complete status indicates the journey is considered passed. |
Refer | The journey was completed but **failed **one or more configured checks or rules |
Rejected | The journey is automatically rejected based on the configured failure action for each check or rule. |
Manual Decision Enum
Enum Value | Description |
---|---|
Approved | if the journey approved by the reviewer. |
Rejected | if the journey rejected by the reviewer. |
Resubmission Requested | The reviewer requests the user to resubmit one or more journey steps with corrected or updated information. |
Document Model
This object represents the set of documents in this journey. Each child element inside documents
contains the results of processed document that was submitted as part of the journey.
Document processing result includes the type of the document, the data extracted from the document and detailed validation check details carried out while processing the document.
This is an example for documents element (with detailed explanation below):
"documents": {
"0": {
"step_title": "UAE Passport",
"progress": "Completed",
"has_passed_rules": true,
"document_type": "Passport",
"document_subtype:"",
"issuing_country": "United Arab Emirates",
"issuing_country_code": "ARE",
"extracted_fields": {
"First Name": {
"value": "Sami",
"type": "string",
"source": "MRZ"
}
},
"validation_result": {
"validation_outcome": "Failed",
"validation_checks": [
{
"name": "Document Classification (Front)",
"description": "Verifies supportability of the type of document and its ability to be fully authenticated.",
"result": "Failed",
"result_description": "The document type could not be determined"
}
]
},
"face_match_result": {
"is_matched": true,
"score": 99,
"images": [
{
"image_path": "625602fb54c...............1f15b957",
"image_source": "Selfie"
}
]
},
"images": {
"front_side_image_path": "98682fb54c...............1f181b938",
"back_side_image_path": null,
"front_side_cropped_image_path": "95602fb54...............81f181b9",
"back_side_cropped_image_path": null,
"portrait_image_path": "98682fb54c...............1bfcf12",
},
"media_files":{
"front_side_pdf_path": "95602fb54...............81f181b9"
}
}
}
Property | Description |
---|---|
step_title |
Type:: |
progress |
Type::
|
has_passed_rules |
Type:: |
document_type |
Type:: |
document_subtype |
Type: |
issuing_country |
Type:: |
issuing_country_code |
Type:: |
Type:: |
|
Type:: |
|
Type:: |
|
images |
Type:: |
media_files |
Type:: |
Extracted Field Model
Property | Description |
---|---|
The dictionary key |
Type: |
type |
Type: |
value |
Type: |
source |
Type: |
Validation Result Field Model
Property | Description |
---|---|
name |
Type: |
description |
Type: |
result |
Type: |
result_description |
Type: |
Face Match Result Field Model
Property | Description |
---|---|
is_matched |
Type: |
score |
Type: |
images |
Type:
|
Images Field Model
The table below lists the image paths for each document step. All images can be retrieved using the Get Image API, which accepts the image path as a parameter and returns the binary image file.
Property | Description |
---|---|
front_image_path |
**Type: ** |
back_image_path |
**Type: ** |
front_cropped_image_path |
**Type: ** |
back_cropped_image_path |
**Type: ** |
portrait_image_path |
**Type: ** |
Selfie Model
Property | Description |
---|---|
progress |
Type::
|
has_passed_rules |
Type:: |
status |
**Type: ** |
is_live |
**Type: ** |
liveness_status_code |
**Type: ** |
image_path |
**Type: ** |
cropped_image_path |
**Type: ** |
video_path |
Type: |
Liveness Status Codes
Code | Description |
---|---|
FACE_TOO_CLOSE | Face is too close to camera. |
FACE_CLOSE_TO_BORDER | Face is too close to the border of the image. |
FACE_CROPPED | Face is cropped, and can be reduce the accuracy of the liveness detection because the face is not complete. |
FACE_IS_OCCLUDED | Part of the face is covered by mask or another objects and it can reduce accuracy of the liveness detection. |
FACE_NOT_FOUND | Failed to detec a face. |
TOO_MANY_FACES | Too many faces detected. |
FACE_TOO_SMALL | The face area is not big enough to do the face liveness analysis. |
BAD_QUALITY_IMAGE | Image quality is too low for accurate analysis, possibly due to low resolution or blurring. |
FACE_ANGLE_TOO_LARGE | The face is tilted or rotated beyond acceptable angles for reliable analysis. |
NOT_LIVE | The ML model determined that the face does not appear to be live. |
Rule Result Model
This object contains the business rule results. business rules are set of checks that can be defined by customers to apply some constraints on the onboarding journeys like what are acceptable document types for each step or prevent a user from submitting expired documents ..etc.
This is an example for the rule result object
"rule_results": {
"proof_policy": {
"name": "Proof Policy",
"result": "Passed",
"description": "Confirms that the document provided is of the accepted types for this journey step",
"information": "The document type and issuing country of the document provided by the user is checked against a list of allowed document types and/or issuing countries configured as accepted on this step. If the step is configured to accept a driving licence only but the user provided another type of document, this check would fail",
"tips": "Check the type of the document provided and the issuing country and confirm if they are accepted for this type of application",
"details": [
RuleResultDetailsModel
]
}
}
Property | Description |
---|---|
The dictionary key |
**Type: ** |
name |
**Type: ** |
result |
**Type: ** |
description |
**Type: ** |
information |
**Type: ** |
tips |
**Type: ** |
details |
**Type: ** |
Rule Result Details Model
Here is a sample object for the rule result details model, check the table below for more detailed information:
{
"title": "Passport - Front",
"result": "Passed",
"result_description": "Document is confirmed to be of one of the accepted types",
"reference_object": {
"object_key": "documents",
"instance_key": "passport_step"
}
}
Property | Description |
---|---|
title |
the title of the check that presents the name of the document and the side to which the rule was applied against. |
result |
the result of the check it can be either |
result_description |
A tailored description massage for each result status. |
reference_object |
Shows the related object for the check. Where it has 2 keys:
|
Supported Rules (Checks)
NoteThe rules you will get depend on the configuration of your flow. So some of these rules might not apply in your case.
Key | Title | Description | Applies to |
---|---|---|---|
document_validation | Authentic Document | Confirms the authenticity of the submitted documents, likely free of any evidence of manipulation. | POI, POA |
same_subject | Same Person | Verifies that all steps in the journey belong to the same person. | POI, Selfie |
no_duplicate_documents | Unique Document | Confirms that the same document is not submitted more than once. | POI, POA |
no_duplicate_applicant | Unique Applicant | Confirms whether the applicant is matched with already existing applicants. | |
no_aml_records | Datasets (e-KYC/AML) | Confirms whether the applicant has records in electronic Know Your Customer (e-KYC) and Anti Money Laundering (AML) databases, screening for Politically Exposed Persons (PEPs) and Sanctions. | |
unrecognized_document | Recognised Document | Verifies the recognition of the submitted documents as a precisely supported document type. | POI, POA |
proof_policy | Accepted Document Policy | Confirms that the document provided is of the accepted type for each particular journey step. | POI, POA |
expired_document | Expired Document | Confirms that the documents provided are not expired. | POI |
under_age | Under Age | Verifies that the applicant is over minimum age (e.g. 18 years old). | POI |
approved_nationality | Approved Nationality | Verifies whether the nationality of the document holder is in the list of allowed nationalities. | POI |
selfie_liveness | Selfie Liveness | Verifies if the selfie step has passed and selfie belongs to Live person. | Selfie |
device_intelligence | Device Intelligence | Verifies the device's integrity throughout the onboarding process. For more details on device intelligence checks, refer to the documentation. | |
document_quality | Document Quality | Assesses the quality of submitted documents to ensure they meet required standards for clarity, and readability. if the document is not readable it will fail. | POI, POA |
mandatory_information_presence | Mandatory Information Presence | Ensures that all required fields are present in the document. this applicable only for Proof of Address documents | POA |
outdated_proof_of_address | Outdated Proof of Address | Ensures that the Proof of Address document is not outdated. | POA |
geolocation | Location Checks | Evaluates the proximity between the user's IP address geo-location and the address on the document, ensuring the two are in sufficient proximity. Applicable for Proof of Address. | POA |
proof_of_address_matched | Proof of Address Matched | Validates that the name extracted from the Proof of Address matches either the name extracted from the Proof of Identity or the full name provided in the applicant details. | POA |
government_check | Government Check | Validates the submitted personal details by comparing it with official government records. | Government DB Check |
applicant_cross_check | Applicant Cross Check | Validates the personal details provided in Applicant Details field at the start of the journey matches the details on this document | POI, POA |
POI: Stands for Proof of Identity.
POA: Stands for Proof of Address.
Applicant Field Model
Contains general information for the applicant.
Property | Description |
---|---|
applicant_id |
**Type: ** |
profile_image_path |
**Type: ** |
full_name |
**Type: ** |
personal_number |
**Type: ** |
birth_date |
**Type: ** |
AML Field Model
Shows the applicant’s records over Anti Money Laundering (AML) databases if exist. Here are the attributes that constitute an aml element:
Property | Description |
---|---|
applicability |
**Type: ** |
matches |
**Type: ** |
AML Applicability Enum
Enum Value | Description |
---|---|
Not Ready Yet | When the journey is not completed. |
Skipped | When the personal information is not extracted properly. |
Disabled | When this check is not enabled. |
Applicable | When all prerequisites for this check are satisfied and the check was performed. if there are matches will be reflected in matches element. |
AML Match Model
Property | Description |
---|---|
name |
**Type: ** |
countries |
**Type: ** |
datesOfBirth |
**Type: ** |
notes |
**Type: ** |
datasets |
**Type: **
|
aliases |
**Type: ** |
addresses |
**Type: ** |
sex |
**Type: ** |
score |
**Type: ** |
resourceId |
Unique Id for individual match. Used for whitelist and match status update. |
Screening Check Model
The screening_checks
object contains all the checks performed on provided documents or selfie images against government databases. Each element within screening_checks
represents a specific type of check.
"screening_checks": {
"additional_face_db": AdditionalFaceMatchModel,
"uae_goverment_db_check": UAEGovernmentDBCheckModel
}
Property | Description |
---|---|
The dictionary key |
**Type: ** |
The dictionary value |
Each screening check has its own model, please check the listed checks below for detailed information. |
Here is a list of the supported screening checks:
1. Additional Face Match Model
This check compares the selfie image against an external face source, such as a government database or a customer's backend storage.
To use this feature, you can:
✅ Add a custom step in the Flow Builder to include external face matching in your flow.
✅ Submit the external face via this API for comparison with the onboarding selfie.
In the provided example, the additional_face_db
element represents the face matching results between the onboarding selfie and the external face.
{
"face_match_results": [
{
"is_matched": true,
"score": 99,
"images": [
{
"image_path": "95602fb54cfa6c15d477a44781f171b8",
"image_source": "Selfie"
},
{
"image_path": "05602fb54cfa6c15d477a44781f171b0",
"image_source": "AdditionalFace"
}
]
}
]
}
This check where a submitted selfie image is compared to facial features stored in the government database.
Property | Description |
---|---|
face_match_results |
**Type: ** |
face_match_results
Field Model
face_match_results
Field ModelProperty | Description |
---|---|
is_matched: |
**Type: ** |
score |
**Type: ** |
images |
**Type: **
|
Device Intelligence
The device_intelligence
object provides insights into the security and integrity of the device used during the verification process. It evaluates various device signals to detect potential risks, such as rooted or jailbroken devices, VPN usage, and other anomalies that could indicate fraudulent activity.
"device_intelligence": {
"signals_outcome": "Passed",
"device_signals": [
{
"key": "rooted",
"name":"Rooted Device",
"result": "Passed",
"description": "Flags if a mobile device has been rooted (Android) or jailbroken (iOS), compromising the system's security controls."
}
]
}
Device Signal Model
Property | Description |
---|---|
key |
Type: |
name |
Type: |
result |
Type: |
description |
Type: |