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: `string`, `not_nullable` The unique identifier of the journey. This identifier is used across IDWise systems to refer to the journey and is auto-generated at the first moment the user starts the journey.
customer_id	Type: `string`, `not nullable` The identifier of your account within the system. All journeys within your account share this identifier.
flow_id	Type: `string`, `not nullable` The identifier of the flow that this journey belongs to
reference_number	Type: `string`, `nullable` This is a custom identifier you could attach to the journey when you start it and it will be available as part of the result graph. This is useful for example to link an identifier of the user in your system to the journey or journeys made by this user thus making it easier locate the user in your system after they finish the journey (this used to be called user_id).
start_time	Type: `datetime`, `not nullable` The date time stamp when this journey was initiated. This is formatted as a standard ISO 8601 Date Time string commonly used in JSON.
end_time	Type: `datetime`, `nullable` The date time stamp when this journey was finished. This field can be `null` if the journey is not finished yet. The format of this field is also ISO 8601 Date Time string like in `start_time` field.
system_decision	Type: `string (enum)`, `not nullable` An enum value (encoded as a string) representing the outcome of the journey as evaluated by IDWise system. This decision accounts for the result of steps and the business rules configured on the journey to reach a conclusion on whether the journey passes automatically or needs referral to manual review. Check the following table for more details.
manual_decision	Type: `string (enum)`, `nullable` An enum value (encoded as a string) representing the manual review decision.
final_decision	Type: `string (enum)` Is the latest decision so far. It will contain the `system_decision` (`Complete` or `Refer`, `Rejected`) if there has not been manual review done. Otherwise it will contain the `manual_decision` (`Approved`, `Rejected`, `Resubmission Requested`).
model_version	Type: `string`, `nullable` Represents which version of the result graph this journey follows. Different versions of the graph might have different elements.
documents	Type: `object`, `nullable` The processing results of documents submitted as part of the journey. This is a dictionary (JSON object) where the key represents the `step_id` associated with a given document and the value represents the `document` object itself. See the following sections for details on the format of document elements.
selfie	Type: `object`, `nullable` Represents the processing results of the live selfie taken during the journey. If the journey is configured with no `Selfie` step then this element will be `null`. [See the following sections for details on the format of the `selfie` element](Selfie Model).
rule_results	Type: `object`, `nullable` The business rules that were applied on this journey and their outcomes. These rules can configure the acceptance criteria for a journey to pass. Examples include: Acceptable types of documents to be provided, ensure the documents are non-expired.
applicant	Type: `object`, `nullable` Common data representing the applicant (user) who made the journey. Check the following section for detailed information about the applicant object.
aml	Type: `object`, `nullable` Holds the results of carrying out AML (Anti-Money Laundering) and background checks. If the journey is not configured with AML checks enabled then this element will be `null`. See the following sections for details on the format of the `aml` elements
screening_checks	Type: `object` An object that contains multiple checks performed on provided documents or selfie images against government databases. Each element within `screening_checks` represents a specific type of check. See the following sections for details on the format of the screening_checks elements.
device_intelligence	Type: `object` An object that contains multiple checks performed on the device used during the verification process.

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:: `string`, `nullable` UI specific name of the step for this document it is helpful to distinguish if you have multiple documents (e.g UAE Driving Licence or International Passport).
progress	Type:: `string (enum)`, `not nullable` Reflects the step progress, its value could be one of the following: `Not Started`: Indicates that at least one attempt, including both the front and back sides (if the back side is needed), has not been submitted. `Started`: Indicates that at least one attempt has been submitted. `Completed`: Indicates that all sides of the document have been processed and the step is concluded, meaning the step has either passed or reached the maximum number of retries. `Skipped`: Indicates that the step has been skipped. There are two ways to skip step by complete the journey before submitting any attempts to a step or by calling Process Journey Step with `is_skipped` flag, or from the SDK you can call skipStep method
has_passed_rules	Type:: `boolean`, `not nullable` Reflects the document validation, and rules. Its value could be either `true` or `false`.
document_type	Type:: `string`, `nullable` The type of this document. The most used document type values are: `Passport`, `Driving Licence`, `Visa`, `Identity Card`, `Bank Statement` and `Utility Bill`, there are some other documents supported as well.
document_subtype	Type: `string`, `nullable` The subtype of this document. The are many possible values e.g. `Current Account Statement`, `Water Bill`. When this field is used, it should not be utilised alone but in combination with `document_type` field above to fully qualify the subtype of the document. It might be empty if the document type doesn't have any subtypes.
issuing_country	Type:: `string`, `nullable` The name of the country which issued this document.
issuing_country_code	Type:: `string`, `nullable` The 3-letter ISO country code of the country which issued this document.
extracted_fields	Type:: `dict[str, object]`, `nullable` A dictionary (aka object) containing the data fields that were read from the document. Check the following model that shows the model of each element.
validation_result	Type:: `list[object]`, `nullable` A list of the checks that were run to check the authenticity of the document. Please refer to the Validation Result Field Model for more details
face_match_result	Type:: `object`, `nullable` An object that represents the face match result between the portrait photo on the document with the submitted selfie image. Plese refer to the Face Match Result Field Model page for more details
images	Type:: `object`, `nullable` An object that of image identifiers for both input and output images. Check the images field model
media_files	Type:: `object`, `nullable` An object that of image identifiers for raw input pdf files for front and back step.

Extracted Field Model

Property	Description
*The dictionary key*	Type: `string`, `not nullable` Check the Fields Extracted by IDWise page
type	Type: `string (enum)`, `nullable` An enum representing the type of the value. Possible values are : string, image.
value	Type: `string` The field value encoded as a string. For all date fields, the value will be encoded in ISO 8601 date format. if the field is of type `image` (e.g Signature field), value will be `null`.
source	Type: `string`,`nullable` Indicates the source of the field value. Possible values include: `VIZ`: Value extracted from the Visual Inspection Zone of the document. `MRZ`: Value extracted from the Machine-Readable Zone. `BARCODE`: Value extracted from a barcode on the document. `NFC`: Value obtained via NFC chip reading. `APPLICANT`: Value provided directly by the applicantValue provided as part of applicant details field when starting the journey. `INFERRED`: Value inferred from other available data.

Validation Result Field Model

Property	Description
name	Type: `string`, `not nullable` The name of the validation check.
description	Type: `string`, `nullable` A user friendly explanation.
result	Type: `string(enum)`, `not nullable` The result of this individual validation check; it can be either `Passed`, `Failed` or `Undetermined` (which means the check couldn’t be carried out, for example if the prerequisites of the check were not present).
result_description	Type: `string`, `nullable` A user-friendly explanation of the result (e.g. why the check failed or passed, or not carried away).

Face Match Result Field Model

Property Description

is_matched

Type: boolean, not nullable
The conclusive face matching decision, it can be either true or false.

score

Type: number, nullable
The matching score between the images.

images

Type: list(object), nullable
an array of the images that are used in face matching. where each element has the following properties:

image_path: Used to download that image using the GetImage endpoint
image_source: The source of the image, can take either Selfie or Document

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: `string`, `nullable` The path of the front image was submitted by the user.
back_image_path	Type: `string`, `nullable` The path of the back image was submitted by the user. if the back image wasn’t submitted the value will be `null`.
front_cropped_image_path	Type: `string`, `nullable` The path of the front cropped image.
back_cropped_image_path	Type: `string`, `nullable` The path of the back cropped image. if the back image wasn’t submitted the value will be null
portrait_image_path	Type: `string`, `nullable` The path of the portrait photo on the id document, if the document is not recognised the path will be null.

Selfie Model

Property	Description
progress	Type:: `string (enum)`, `not nullable` Reflects the step progress, its value could be one of the following: `Not Started`: Indicates that at least one attempt has not been submitted. `Started`: Indicates that at least one attempt has been submitted. `Completed`: Indicates that the step is concluded, meaning the step has either passed or reached the maximum number of retries. `Skipped`: Indicates that the step has been skipped. There are two ways to skip step by complete the journey before submitting any attempts to a step or by calling Process Journey Step with `is_skipped` flag, or from the SDK you can call skipStep method
has_passed_rules	Type:: `boolean`, `not nullable` Reflects the document validation, and rules. Its value could be either `true` or `false`.
status	Type: `string (enum)`, `not nullable` The conclusive status of the selfie step value could be `Complete`, `Refer`, and `Not Started`. This element is the main element to be used to confirm whether the selfie passed or not.
is_live	Type: `boolean`, `nullable` Indicates whether the submitted selfie image was captured live. A value of `true` means the image is live, `false` means it is not. If the value is `null`, the liveness check has been disabled.
liveness_status_code	Type: `string (enum)`, `nullable` The error code that indicates the cause of the liveness check failure. Please refer to the list of all possible error codes available for your reference.
image_path	Type: `string`, `nullable`, the path to the selfie image, you can use this API to download the image.
cropped_image_path	Type: `string`, `nullable`, the path to the cropped selfie image, you can use this API to download the image.
video_path	Type: `string`, `nullable` the path for the video recording for the selfie step. you can use this API to download the video

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: `string`, `not nullable` Represents the rule's key. You may check the following table for a list of the rules.
name	Type: `string`, `not nullable` The rule name.
result	Type: `string (enum)`, `not nullable` An enum value (encoded as a string) summaries the result of applied rules on each document, It can be either `Passed` or `Failed`., `CouldNotApply`
description	Type: `string`, `nullable` The description of the applied rule.
information	Type: `string`, `nullable` The information on the applied rule.
tips	Type: `string`, `nullable` An advice for the user on how to handle the result of this rule.
details	Type: `object of RuleResultDetailsModel` Provides a list of the checks that were run on different provided documents and data.

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 `Passed` or `Failed`.
result_description	A tailored description massage for each result status.
reference_object	Shows the related object for the check. Where it has 2 keys: object_key: represents the referenced object type (for example: `document`) instance_key: the referenced object instance key (for example the document's id)

Supported Rules (Checks)

📘
Note
The 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: `string`, `not nullable` This represents the identifier of the applicant (not the journey), this can be the same for different journeys.
profile_image_path	Type: `string`, `nullable` The path of the profile image.
full_name	Type: `string`, `nullable` The full name of the applicant.
personal_number	Type: `string`, `nullable` The personal number of the applicant.
birth_date	Type: `string - ISO Format`, `nullable` (e.g. 1980-01-01) The birth date of the applicant.

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: `string (enum)`, `not nullable` Shows the applicability of this check for the journey and it can be. Check the following table about the enum values
matches	Type: `array [object]`, `nullable` Presents the list of matched records in the datasets for the applicant, each record of matches has the following sub-elements Check the AML Match Model for detailed information.

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: `string`, `not nullable` The name of the profile found in the associated database entry.
countries	Type: `string`, `nullable` The list of countries from the addresses and nationalities of this profile. It has the format of 2-letter ISO country code.
datesOfBirth	Type: `string`, `nullable` Date in either `YYYY-MM-DD` or `YYYY-MM` or `YYYY` ISO format.
notes	Type: `string`, `nullable` Notes.
datasets	Type: `array[string]`, `nullable` The name of databases in which this match was found. This could be one of the following values: `Politically Exposed Person` -`Sanctions` -`Adverse Media` -`Regulatory Enforcement List` -`People of Interest` -`Disqualified Director` -`Insolvency` -`Fitness Probity`
aliases	Type: `array[object]`, `nullable` Other names of the profile
addresses	Type: `array[object]`, `nullable` The list of addresses.
sex	Type: `string`, `nullable` The gender of the person.
score	Type: `float`, `not nullable` The search results are ranked based on a score included in the metadata. This score does not represent an absolute ranking of the matches but rather serves to order the search results and provide a relative indication of their relevance.
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: `string`, `not nullable` Represents the applied screening check id
*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: `array of objects` This element is an array of objects that contains the results of the facial recognition check. In the example provided, there is only one object in the array.

`face_match_results` Field Model

Property Description

is_matched:

**Type: ** boolean
Indicates whether the submitted selfie image matches the facial features stored in the government database.

score

**Type: ** integer
Indicates the confidence level of the facial recognition check. The higher the value, the higher the confidence level.

images

**Type: ** array of objects
Contains information on the images that used in the face matching. each object contains the following elements:

image_path: This element is a string value that serves as the image identifier. It can be used to retrieve the image through the Image Retrieval API.
image_source: This element is a string value that indicates the source of the submitted image. In the example provided, the source is Selfie or AdditionalFaces.

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: `string` A unique identifier for the specific device signal being checked..
name	Type: `string` A friendly name for the device signal
result	Type: `boolean` the result of the check it can be either `Passed` or `Failed`.
description	Type: `string` A detailed explanation of the device signal being checked. It describes the purpose of the signal.

200200

202202

400400

401401

403403

404404

500500