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",
  "tenant_id": "T-123628d8-e456-4375-8ff6-6e84f54f8743",
  "environment_name": "live",
  "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",
  "last_update_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},
  "questionnaires": {"step_id": QuestionnaireModel},
  "rule_results": {"rule_id": RuleResultModel},
  "applicant": {ApplicantModel},
  "aml": {AMLModel},
  "screening_checks": {"model_id": ScreeningChecksModel},
  "device_intelligence": DeviceIntelligenceModel,
  "ban_list_matches": BanListMatchesModel,
  "manual_reviews": [ManualReviewModel]
  "journey_details_url": ""
}

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.
tenant_id	Type: `string`, `not nullable` The identifier of your organisation within IDWise. It is the same across all your environments (Live and Sandbox).
environment_name	Type: `string (enum)`, `not nullable` The environment the journey was made in. It can be either `live` or `sandbox`.
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.
last_update_time	Type: `datetime`, `nullable` The date time stamp of the last change to the journey, in ISO 8601 format.
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`, `Incomplete`) if there has not been manual review done. Otherwise it will contain the `manual_decision` (`Approved`, `Rejected`).
manual_reviews	Type: `array [object]`, `not nullable` The history of manual reviews made on the journey, oldest first. It is an empty list when the journey has not been reviewed. Each item has the following sub-elements: `acting_user_email`: the email of the reviewer. Empty when the review was not made by a dashboard user. `manual_decision`: the decision taken. Check the Manual Decision Enum. `action_time`: the date time stamp of the review, in ISO 8601 format. `comment`: the reviewer's comment. Can be null.
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).
questionnaires	Type: `object`, `not nullable` The answers the applicant submitted in the questionnaire steps of the journey. This is a dictionary (JSON object) where the key represents the `step_id` of a questionnaire step and the value represents the `questionnaire` object itself. Every questionnaire step on the applicant's path has an entry, including steps the applicant has not started yet. If the journey has no questionnaire step then this element will be an empty object `{}`. See the following sections for details on the format of questionnaire elements.
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.
ban_list_matches	Type: `object`, `nullable` The ban list result for this journey. See the Ban List Matches Model.
journey_details_url	Type: `string`, `not nullable` A link to the journey details page in the IDWise dashboard.

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": {
	"10": {
                "step_id": 10,
		"step_title": "UAE Passport",
                "step_role": "Identity Document",
		"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",
                                "read_accuracy": "High",
                                "user_confirmation":{
                                    "extracted_value": "Samir",
                                    "match_status": "Matched"
                                }
			}
		},
		"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_image_path": "98682fb54c...............1f181b938",
			"back_image_path": null,
			"front_cropped_image_path": "95602fb54...............81f181b9",
			"back_cropped_image_path": null,
			"portrait_image_path": "98682fb54c...............1bfcf12",
		},
		"media_files":{
			"front_side_pdf_path": "95602fb54...............81f181b9",
                        "back_side_pdf_path": null
		}
	}
}

Property	Description
step_id	Type:: `integer`, `nullable` The identifier of the document step. It is the same as the key of this document in `documents`.
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).
step_role	Type:: `string (enum)`, `nullable` The role of the document step in the flow. It can be one of the following: `Identity Document` `Proof of Address` `DocumentAI` `ArchiveOnly`
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, meaning the journey was completed before any attempt was submitted for this step. `Resubmission Pending`: Indicates that the user was asked to resubmit the document and has not done so yet.
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:: `object`, `nullable` The outcome of the checks that were run to check the authenticity of the document, with the list of those checks. 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. Please 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` The identifiers of the raw PDF files uploaded for the document. It has the following keys: front_side_pdf_path: the identifier of the PDF uploaded for the front side, or `null` if the front side was not uploaded as a PDF. back_side_pdf_path: the identifier of the PDF uploaded for the back side, or `null` if the back side was not uploaded as a PDF.
nfc	Type:: `object`, `nullable` NFC chip reading result. `null` unless NFC reading is part of this 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.
read_accuracy	Type: `string (enum)`, `nullable` The confidence that the field was read correctly. It can be either `High` or `Low`. It is `null` for documents where read accuracy is not assessed, such as Proof of Address documents.
user_confirmation	Type: `object`, `nullable` The result of the user confirming this field, when the step asks the user to confirm the extracted details. It is `null` if the user was not asked to confirm the field. It has the following keys: extracted_value: the value read from the document before the user confirmed it. match_status: `Matched` if the user kept the extracted value, or `Not Matched` if the user changed it.

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

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`

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.
signature_image_path	Type: `string`, `optional` The path of the signature image extracted from the document. This key is returned only when a signature was extracted.
nfc_portrait_image_path	Type: `string`, `nullable` The path of the portrait photo extracted from the document chip via NFC reading. `null` unless NFC reading is part of this step, or the chip didn't return a portrait.

NFC Field Model

Property Description

Property	Description
is_supported_by_device	Type:: `boolean` Whether the applicant's device has NFC chip reading hardware. Always present when `nfc` is not `null`.
read_status	Type:: `string (enum)`, `nullable` The outcome of the chip read. `null` if `is_supported_by_device` is `false`. Possible values include: `Succeeded`: The chip was read successfully. `Failed`: The chip read was attempted but did not complete successfully. `Cancelled`: The user cancelled the NFC reading process.
extracted_fields	Type:: `dict[str, object]` 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.

is_supported_by_device

Type:: boolean
Whether the applicant's device has NFC chip reading hardware. Always present when nfc is not null.

read_status

Type:: string (enum), nullable
The outcome of the chip read. null if is_supported_by_device is false. Possible values include:

Succeeded: The chip was read successfully.
Failed: The chip read was attempted but did not complete successfully.
Cancelled: The user cancelled the NFC reading process.

extracted_fields

Type:: dict[str, object]
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.

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, meaning the journey was completed before any attempt was submitted for this step. `Resubmission Pending`: Indicates that the user was asked to resubmit the document and has not done so yet.
has_passed_rules	Type:: `boolean`, `not nullable` Reflects the selfie checks, 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.

Questionnaire Model

Contains the answers the applicant submitted in a questionnaire step, along with the step's progress and rule outcome.

Here is a sample questionnaire object, check the table below for more detailed information:

"questionnaires": {
  "60": {
    "questionnaire_id": "f6da20e8-9d88-4300-b91e-7cfd180fd0bb",
    "step_id": 60,
    "total_questions_answered": 5,
    "progress": "Completed",
    "has_passed_rules": true,
    "step_title": "Source of Funds",
    "questionnaire_answers": [
      {
        "type": "dropdown",
        "question_ref": "employment_status",
        "question_label": "Employment status",
        "answer_value": "self_employed",
        "answer_label": "Self employed"
      },
      {
        "type": "currency",
        "question_ref": "approximate_annual_income",
        "question_label": "Approximate annual income",
        "answer_value": "200"
      },
      {
        "type": "country",
        "question_ref": "country_of_citizenship",
        "question_label": "Country of citizenship",
        "answer_value": ["ALA", "ALB", "ASM"],
        "answer_label": ["Åland Islands", "Albania", "American Samoa"]
      },
      {
        "type": "single_choice",
        "question_ref": "are_you_a_politically_exposed_person",
        "question_label": "Are you a politically exposed person?",
        "answer_value": "no",
        "answer_label": "No"
      }
    ]
  }
}

Property	Description
*The dictionary key*	Type: `string`, `not nullable` The `step_id` of the questionnaire step.
questionnaire_id	Type: `string`, `not nullable` The identifier of the questionnaire used in this step.
step_title	Type: `string`, `not nullable` The title of the questionnaire step as configured in the flow. If the step has no title, this will be `Questionnaire`.
step_id	Type: `integer`, `not nullable` The identifier of the questionnaire step. It is the same value as the dictionary key.
progress	Type: `string (enum)`, `not nullable` Reflects the step progress, its value could be one of the following: `Not Started`: Indicates that the applicant has not submitted the questionnaire yet. `Started`: Indicates that at least one attempt has been submitted. `Completed`: Indicates that the step is concluded. `Skipped`: Indicates that the step has been skipped.
has_passed_rules	Type: `boolean`, `not nullable` `true` when any of these applies, otherwise `false`: The applicant submitted the questionnaire and no rule failed (for example, they were assessed as low risk). A reviewer approved the step. The step was optional and was skipped.
total_questions_answered	Type: `integer`, `not nullable` The number of questions the applicant answered. Skipped optional questions are not counted.
questionnaire_answers	Type: `array of QuestionnaireAnswerModel`, `not nullable` One entry for each question the applicant answered, in the order they appear in the questionnaire. Skipped questions and questions hidden by branching are not included. This will be an empty array until the questionnaire is submitted. Check the following section for details on the format of each answer.

Questionnaire Answer Model

Property	Description
type	Type: `string (enum)`, `not nullable` The question type. Its value could be one of the following: `single_choice`, `multiple_choice`, `dropdown`, `short_text`, `long_text`, `number`, `currency`, `date`, `country`.
question_ref	Type: `string`, `not nullable` The question's reference as set in the questionnaire builder. It is the same in every language, so use it to identify the question in your system.
question_label	Type: `string`, `not nullable` The question text as it was shown to the applicant, in the language they used.
answer_value	Type: `string`, `number` or `array`, `not nullable` The value the applicant submitted. Its format depends on the question type: `single_choice`, `dropdown`: the value of the selected option. `multiple_choice`: an array of the values of the selected options. `country`: the ISO 3166-1 alpha-3 country code, or an array of codes if the question allows selecting more than one country. `number`: a number. `currency`: the amount as a string, for example `"200"`. `date`: an ISO 8601 date string in `YYYY-MM-DD` format, for example `"2026-10-31"`. `short_text`, `long_text`: the text the applicant entered.
answer_label	Type: `string` or `array`, `optional` The text the applicant saw for their answer, in the language they used: the label of the selected option or options, the country name or names. Use `answer_value` in your logic, because it stays the same in every language, and use `answer_label` for display. For example, `answer_value` `"self_employed"` has `answer_label` `"Self-employed"`. For `multiple_choice` and multi-select `country` questions, it is an array in the same order as `answer_value`. This element is omitted when the answer has no separate display text, such as free text, numbers, dates and currency amounts.

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` `NotPerformed`
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: `array[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` `CouldNotApply` `NotPerformed`.
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: the response block the rule refers to. It can be one of: `documents` `selfie` `aml` `screening_checks` `device_intelligence` `applicant` `questionnaire` `spot_checks` instance_key: the referenced object instance key (for example the document's id). For a questionnaire rule it is the questionnaire's `step_id`, which is also its key in `questionnaires`.

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
questionnaire_risk_level	Questionnaire Risk Level	Checks the risk level calculated from the applicant's questionnaire answers. A Low risk level passes, and a Medium or High risk level fails. On a failure, `result_description` lists the answers that set the risk level. This rule is not returned when the questionnaire has no risk rules configured.	Questionnaire
minimum_document_age	Minimum Document Age	Confirms that the document was issued at least a minimum number of days ago (60 days by default), based on its issue date.	POI, POA
accepted_field_values	Accepted Field Value	Verifies that specific fields on the document have one of the accepted values configured in the flow. The rule fails if a required field is missing from the document.	POI, POA
user_confirmation	Confirmed Data Mismatch	Confirms that the user did not change any of the extracted details when asked to confirm them.	POI, POA
gps_poa	POA GPS Check	Checks that the user's GPS location matches the address they entered. Applies only to Proof of Address completed by GPS.	POA
nfc_chip_reading	NFC Chip Reading	Verifies that the document's NFC chip was read successfully. The rule fails if the chip could not be read or the device does not support NFC.	POI
additional_face_match	Face Match With External Source	Verifies that the face in the additional face image matches the applicant's selfie, or the document photo when the flow has no selfie.	Additional Face
face_spot_check	Face Spot Check	Verifies that the selfie submitted in a spot check matches the selfie from the applicant's onboarding journey.	Selfie
request_integrity_check	Request Integrity Check	Verifies that the requests sent during the journey come from the IDWise SDK and were not tampered with. Applicable for Web SDK and iOS SDK journeys.
behavioural_checks	Behavioural Checks	Checks the applicant's behaviour across journeys, for example other journeys submitted with a different identity or face. It runs after the user completes all steps.
document_cross_match	Document Cross Match	Validates that the fields configured on an AI Document Intelligence step match the corresponding details on the identity documents	AI Document Intelligence
re_kyc_check	Re-KYC Data Consistency	Validates that the details submitted during re-KYC match the details from the onboarding journey. Applicable only to re-KYC submissions.	POI, Selfie
flagged_for_review	Flagged for Review	Fails when the applicant was flagged for review (`flag_for_review: true`) at the start of the journey. This rule is not returned otherwise.

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. Check the following table about the enum values
check_status	Type: `string (enum)`, `nullable` The outcome of the AML search request. It is `Success` when the search ran. Otherwise it gives the reason the search could not run: `Missing Name`, `Invalid Name`, `Invalid Date`, `Invalid Sex`, `Invalid Country`, `Invalid Birth Year`, `Invalid Threshold`, `Invalid Config`, `Request Failed` or `Invalid Response`. It is null when the check is not applicable.
check_failure_reason	Type: `string`, `nullable` A description of why the search failed, or why the check is not applicable. It is null when the search succeeded.
datasets	Type: `array [string]`, `not nullable` The datasets the applicant was screened against, for example `Politically Exposed Person`, `Sanctions` or `Adverse Media`.
search_datetime	Type: `string`, `nullable` The date time stamp of the AML search, in ISO 8601 format.
aml_search_config	Type: `object`, `nullable` The settings used for the AML search. It has the following sub-elements: `search_type`: `FuzzyMatch` or `ExactMatch`. `match_threshold`: the minimum match score, as a percentage. Can be null.
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.
entity_type	Type: `string`, `nullable` The type of the matched entity, for example `Person` or `Company`.
aliases	Type: `array[object]`, `nullable` Other names of the profile
countries	Type: `array[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: `array[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`
dataset_details	Type: `array [object]`, `nullable` The lists the record appears on. Each item has the following sub-elements: `category`: the dataset, for example `Sanctions`. `list_id` and `list_name`: the identifier and name of the list. `url`: a link to the list's source, when available. `items`: `listing_started` and `listing_ended`, the dates the record was added to and removed from the list, in `YYYY-MM-DD` format.
details	Type: `dictionary [string, object]`, `nullable` The details of the record, grouped by section. Each section has the following sub-elements: `title`: the section title. `data`: the record's fields, as key-value pairs. `datasets`: the datasets this section comes from. `datasets_classes`: the detailed dataset names. `media_links`: for adverse media, the related articles, each with `date`, `snippet`, `title` and `url`.
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.
aml_record_version	Type: `integer`, `optional` The ongoing monitoring version in which the record was added or updated. Only returned for records from ongoing monitoring.
ongoing_monitor_update_type	Type: `string (enum)`, `optional` How ongoing monitoring changed the record. It can be `New` or `Updated`. Only returned for records from ongoing monitoring.

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": {
	"government_db_face": AdditionalFaceMatchModel
}

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

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`, `Document` or `AdditionalFace`.

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, Document or AdditionalFace.

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."
      }
    ]
  }

The signals_outcome field can be Passed when no signal failed, Failed when at least one signal failed, or Undetermined when no signal result was available.

Device Signal Model

Property	Description
key	Type: `string (enum)` A unique identifier for the specific device signal being checked. Check the Smart Signals list for all supported signals
name	Type: `string` A friendly name for the device signal
result	Type: `string (enum)` the result of the check it can be either `Passed`, `Failed`. or `Not Available`
description	Type: `string` A detailed explanation of the device signal being checked. It describes the purpose of the signal.

Ban List Matches Model

The ban_list_matches object shows whether the ban list flagged this journey.

"ban_list_matches": {
  "is_flagged": false,
  "flagging_trigger": null,
  "events": [
    {
      "event_type": "Matched with Ban Entries",
      "event_time": "2026-09-28T18:30:43.927000+00:00",
      "matched_ban_entries": [
        {
          "ban_entry_id": "327ebce9-afc1-4d78-bedd-2b4d39b3562f",
          "version": 1,
          "comment": "Fraudulent documents",
          "matched_factors": [
            {
              "matched_factor": "Extracted Fields",
              "matched_fields": [
                "Full Name",
                "Birth Date"
              ],
              "face_match_score": null
            }
          ]
        }
      ],
      "comment": null,
      "performed_by": {
        "type": "System",
        "name": null,
        "email": null
      }
    },
    {
      "event_type": "Ban Override Applied",
      "event_time": "2026-09-28T18:34:49.875000+00:00",
      "matched_ban_entries": null,
      "comment": "Different person with the same name and birth date",
      "performed_by": {
        "type": "User",
        "name": "John Smith",
        "email": "[email protected]"
      }
    }
  ]
}

Property	Description
is_flagged	Type: `boolean`, `nullable` Indicates whether the ban list flagged this journey. A value of `true` means the journey was flagged. A value of `false` means it was not. A value of `null` means the ban list check was not applied to this journey. For example, this happens when Ban List is not enabled for your account.
flagging_trigger	Type: `string (enum)`, `nullable` The reason the journey was flagged. This field is used only when `is_flagged` is `true`. In all other cases, its value is `null`. The possible values are: `Explicit Ban`: A reviewer banned this journey. `Matched with Ban Entries`: The automatic check matched this journey with at least one ban list entry.
events	Type: `array[object]`, `not nullable` The current ban list events on this journey. The list has at most one `Matched with Ban Entries` event and the reviewer's latest action. The list is empty when the journey does not match any ban list entry and no reviewer took a ban list action. See the Event Model.

Event Model

Property	Description
event_type	Type: `string (enum)`, `not nullable` Identifies the type of this event. The possible values are: `Matched with Ban Entries`: The journey has been matched with at least one ban list entry. `Added to Ban List`: A reviewer banned this journey. `Ban Override Applied`: A reviewer removed the ban from this journey. The journey is not flagged again unless a reviewer bans it. This event appears only while the journey matches a ban list entry.
event_time	Type: `datetime`, `not nullable` The date and time of the event in UTC. The format is an ISO 8601 Date Time string.
matched_ban_entries	Type: `array[object]`, `nullable` The ban list entries that this journey matched. The list has one item for each entry. This field is used only when `event_type` is `Matched with Ban Entries`. For all other event types, its value is `null`. See the Matched Ban Entry Model.
comment	Type: `string`, `nullable` The comment that the reviewer entered for this action. This field is used only when `event_type` is `Added to Ban List` or `Ban Override Applied`. For `Matched with Ban Entries`, its value is `null`.
performed_by	Type: `object`, `not nullable` The details of who performed this event. See the Performed By Model.

Matched Ban Entry Model

Each item describes one ban list entry that this journey matched.

Property	Description
ban_entry_id	Type: `string`, `not nullable` The unique identifier of the ban list entry that this journey matched.
version	Type: `number`, `not nullable` The version of the ban list entry at the time of the match.
comment	Type: `string`, `nullable` The comment saved on the ban list entry. The value is `null` when the entry has no comment.
matched_factors	Type: `array[object]`, `not nullable` The factors on which this journey matched the entry. The list has one item for each factor. See the Matched Factor Model.

Note: Each item shows the ban list entry as it was at the time of the match.

Matched Factor Model

Property	Description
matched_factor	Type: `string (enum)`, `not nullable` Identifies the factor on which this journey matched the entry. The possible values are: `Extracted Fields`: Data extracted from the document in this journey matched the entry. `Facial Biometrics`: The face in this journey matched a face in your ban list. `Device Fingerprint`: The device used in this journey matched a banned device.
matched_fields	Type: `array[string]`, `nullable` The names of the fields that matched the entry. This field is used only when `matched_factor` is `Extracted Fields`. For all other factors, its value is `null`. The possible values are `Full Name`, `Birth Date`, `Document Number`, `Personal Number`, `Nationality Code` and `Document Type`.
face_match_score	Type: `integer`, `nullable` The match score between the face in this journey and the face in the ban list entry, from 0 to 100. This field is used only when `matched_factor` is `Facial Biometrics`. For all other factors, its value is `null`.

Performed By Model

Property	Description
type	Type: `string (enum)`, `not nullable` Identifies who performed this event. The possible values are: `System`: The automatic ban list check. `User`: A dashboard user in your account.
name	Type: `string`, `nullable` The name of the dashboard user. The value is `null` when `type` is `System`.
email	Type: `string`, `nullable` The email of the dashboard user. The value is `null` when `type` is `System`.

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

NFC Field Model

Selfie Model

Liveness Status Codes

Questionnaire Model

Questionnaire Answer Model

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

1. Additional Face Match Model

face_match_results Field Model

Device Intelligence

Device Signal Model

Ban List Matches Model

Event Model

Matched Ban Entry Model

Matched Factor Model

Performed By Model

200200

202202

400400

401401

403403

404404

500500

`face_match_results` Field Model