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.

Authentication

Please refer to the API Credentials and Authentication page for more detailed information

Table of content

In this page you'll find a 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",
	"journey_definintion_id":"6e84f54f8743-f345-7523-7ed4-342528d8",
	"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}
}

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.
journey_definintion_id	Type: `string`, `not nullable` The identifier of the flow that this journey belongs to
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`) if there has not been manual review done. Otherwise it will contain the `manual_decision` (`Approved`, `Rejected`).
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.

System Decision Enum

Enum Value	Description
`Incomplete`	The journey is not completed yet so a decision cannot be drawn yet.
`Complete`	The journey was successfully completed and passed all configured checks and rules. If the journey status is marked as `Complete`, it should be considered as passed.
`Refer`	The journey was completed but has failed one or more of the configured checks or rules.

Manual Decision Enum

Enum Value	Description
`Approved`	if the journey approved by the reviewer.
`Rejected`	if the journey rejected by the reviewer.

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"
			}
		},
		"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",
		}
	}
}

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

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`.

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
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 is live or not. The liveness is already reflected on `status` element.
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.
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.

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 journey definition. So some of these rules might not apply in your case.
If you need to make adjustments to the rules on your journey definition please contact IDWise support team.

Key	Title	Description
document_validation	Authentic Document	Confirms the authenticity of the submitted documents, likely free of any evidence of manipulation.
same_subject	Same Person	Verifies that all steps in the journey belong to the same person.
no_duplicate_documents	Unique Document	Confirms that the same document is not submitted more than once.
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.
proof_policy	Accepted Document Policy	Confirms that the document provided is of the accepted type for each particular journey step.
expired_document	Expired Document	Confirms that the documents provided are not expired.
under_age	Under Age	Verifies that the applicant is over minimum age (i.e 18 years old).
approved_nationality	Approved Nationality	Verifies whether the nationality of the document holder is in the list of allowed nationalities.

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": {		
		"face_match_results": [
			{
				"is_matched": true,
				"score": 99,
				"images": [
					{
						"image_path": "95602fb54cfa6c15d477a44781f171b8",
						"image_source": "Selfie"
					}, 
					{
						"image_path": "05602fb54cfa6c15d477a44781f171b0",
						"image_source": "AdditionalFace"
					}
				]				
			}
		]
	}
}

In the example provided, the additional_face_db element represents a check where a submitted selfie image is compared to facial features stored in the government database. The additional_face_db element contains the following nested elements:

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:

`additional_face_db` screening check

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`.

Get Journey Result

Usage

Base URL by Region

Authentication

Table of content

Response Model

System Decision Enum

Manual Decision Enum

Document Model

Extracted Field Model

Validation Result Field Model

Face Match Result Field Model

Images Field Model

Selfie Model

Liveness Status Codes

Rule Result Model

Rule Result Details Model

Supported Rules (Checks)

📘
Note

Applicant Field Model

AML Field Model

AML Applicability Enum

AML Match Model

Screening Check Model

`additional_face_db` screening check

`face_match_results` Field Model

Usage

Base URL by Region

Authentication

Table of content

Response Model

System Decision Enum

Manual Decision Enum

Document Model

Extracted Field Model

Validation Result Field Model

Face Match Result Field Model

Images Field Model

Selfie Model

Liveness Status Codes

Rule Result Model

Rule Result Details Model

Supported Rules (Checks)

📘Note

Applicant Field Model

AML Field Model

AML Applicability Enum

AML Match Model

Screening Check Model

additional_face_db screening check

face_match_results Field Model

📘
Note

`additional_face_db` screening check

`face_match_results` Field Model