Usage

This API is designed to retrieve the spot check 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 lease refer to the API Credentials and Authentication page for more detailed information

API Response Description

The response has the following structure.

{
	"journey_id": "",	
	"tenant_id": "",
	"environment_name": "",
	"start_time": "",
	"end_time": "",
	"system_decision": null,
	"reference_number": "",
	"model_version": null,
	"selfie": {SelfieModel},
	"applicant": {ApplicantModel},
	"rule_results": {"rule_id": RuleResultModel},	
	"spot_checks": {SpotchecksModel}
}

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.
tenant_id	Type: `string`, `not nullable` The identifier of your account within the system. All journeys within your account share this identifier.
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.
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).
environment_name	Type: `string This is the environment, available values (`live`,`sandbox`)
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.
model_version	Type: `string`, `nullable` Represents which version of the result graph this journey follows. Different versions of the graph might have different 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.
spot_checks	Type: `object`, `nullable`

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.

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.
`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 rules will be run part of the spot check, this object contains only one rule for selfie liveness.

"rule_results": {  
	"selfie_liveness": {  
		"name": "Selfie Liveness",  
		"result": "Passed",  
		"description": "Verifies that the selfie photo supplied in the onboarding journey is live.",  
		"information": "This check verifies that the selfie photo captured in the selfie step of the onboarding journey is live and of an applicant that is physically present during the verification process.",  
		"tips": "If this check fails, check the selfie photo provided by the applicant.",  
		"details": [
      RuleResultDetailsModel
		]  
	}  
}

Property	Description
selfie_liveness	Type: `string`, `not nullable` Represents the rule's key.
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": "Selfie",
  "result": "Passed",
  "result_description": "Selfie photo appears to be live.",
  "reference_object": {
    "object_key": "selfie",
    "instance_key": "0"
  }
}

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: `selfie`) - instance_key: the referenced object instance key (for example the document's id)

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.

Spot Checks Model

Contains the results of the face match check between the onboarding journey and the current spot check journey.

{
		"applicant_selfie_face_match": {
			"is_matched": false,
			"score": 0,
			"images": [
				{
					"image_path": "1b7194bcf77d8be7541ddb6978e93f35",
					"image_source": "Selfie"
				},
				{
					"image_path": "55dd308d6b50905de04c19a8f1414d20",
					"image_source": "Applicant"
				}
			]
		}

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.
image_path	Type: `string`, `nullable`, the path to the selfie image, you can use this API to download the image.
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 `Applicant`