Identity Verification API 1.0.0

Server

https://api.yoti.com/idverify/v1

Production Base URL

https://api.yoti.com/sandbox/idverify/v1

Sandbox Base URL

Authentication

apiKey X-Yoti-Auth-Digest

Signed request performed by back-end SDKs that includes a X-Yoti-Auth-Digest.

Generate signed request Yoti API endpoints are authenticated through signed requests. To create a signed request:

Concatenate the following elements using the '&' character:
- HTTP method
- Path
- Query string (enriched with a timestamp and a nonce parameter)
- Base64 encoded request body (if available)
Apply SHA256withRSA to the resulting string, using your PEM private key generated from the Yoti Hub.
Base64 encode the result from step 2.

Example GET request:

GET&/sessions?sdkId=b88ad843-13cc-44ba-a3e0-053f71d89b1f&nonce=b88ad843-13cc-44ba-a3e0-053f71d89b1f&timestamp=1480509893

Example POST request:

POST&/sessions?sdkId=b88ad843-13cc-44ba-a3e0-053f71d89b1f&nonce=b88ad843-13cc-44ba-a3e0-053f71d89b1f&timestamp=1480509893&ew0KImlkIiA6IDEsDQoibmFtZSIgOiBpdGVtDQoNCn0=

Parameters:

SDK ID: UUID generated when producing your Yoti keys
nonce: UUID strings
Timestamp: UNIX timestamps (number of elapsed seconds since Jan 1st 1970)

Fields

Key	In
X-Yoti-Auth-Digest	Header

Backend Endpoints

Endpoints for the Back-End SDK (Relying Business)

/sessions/{sessionId}

DELETE

/sessions/{sessionId}

GET

/sessions/{sessionId}/media/{mediaId}/content

DELETE

/sessions/{sessionId}/media/{mediaId}/content

Get all the supported documents

Auth

Query String

includeNonLatin

boolean

Controls whether or not the documents returned should include non-latin documents

GET /supported-documents

xxxxxxxxxx
 
curl --get \ --url 'https://api.yoti.com/idverify/v1/supported-documents' \ --data includeNonLatin={includeNonLatin}
Copy

Responses

200

object	object
supported_countries	array[object]
code	string
supported_documents	array[object]
type	string
is_strictly_latin	boolean
requirements	object
date_from	string

Response

xxxxxxxxxx
 
{ "supported_countries": [  {   "code": "AGO",   "supported_documents": [    {     "type": "DRIVING_LICENCE",     "is_strictly_latin": true,     "requirements": {      "date_from": "2012-10-31"     }    },    {     "type": "NATIONAL_ID",     "is_strictly_latin": false    },    {     "type": "PASSPORT",     "is_strictly_latin": true    }   ]  } ]}
Copy

Create a new session

Auth

Query String

sdkId	string	Required if using a Signed Request as the authentication scheme
nonce	string	Required if using a Signed Request as the authentication scheme
timestamp	string	Required if using a Signed Request as the authentication scheme

Request Body

object	object	Create Session Payload
client_session_token_ttl	integer	Number of seconds for the user to complete the whole flow. Default: 600
session_deadline	string	The point-in-time by which the user must complete the whole flow. Expressed as a date, time and time-zone in RFC3339 format. This field may not be used with a client_session_token_ttl field.
resources_ttl	integer	Retention period for uploaded documents/images in number of seconds. minimum: 86700 Default: 87000
ttl	integer	Retention period for a generated import_token, in seconds
user_tracking_id	string	Allows to track the same user across multiple sessions. Should not contain any personal identifiable information.
block_biometric_consent	boolean	Allows the relying business to block the collection of biometric consent
notifications	object
endpoint	string	POST endpoint required. Update notifications are sent to this endpoint based on the selected subscription topics pattern: `^https://.+$`
topics	array[string]	Enum: `RESOURCE_UPDATE`,`TASK_COMPLETION`,`CHECK_COMPLETION`,`SESSION_COMPLETION`,`NEW_PDF_SUPPLIED`,`INSTRUCTIONS_EMAIL_REQUESTED`,`CLIENT_SESSION_TOKEN_DELETED`,`THANK_YOU_EMAIL_REQUESTED`
auth_token	string	If provided, Yoti will send this as a base64 encoded value for the Authorization header in the notifications
auth_type	string	Determines the type of auth header to include in outbound notifications. Defaults to BASIC Enum: `BASIC`,`BEARER`
requested_checks		Mutually exclusive with identity_profile_requirements
object	object
type	string	Enum: `ID_DOCUMENT_AUTHENTICITY`
config	object
manual_check	string	The values IBV is not permitted, although it is permitted for some other types of check Enum: `NEVER`,`FALLBACK`,`ALWAYS`
issuing_authority_sub_check	object
requested	boolean
filter
object	object
type	string	Enum: `ORTHOGONAL_RESTRICTIONS`
allow_non_latin_documents	boolean
allow_expired_documents	boolean
country_restriction	object
inclusion	string	Acceptable values are (case-insensitive): [INCLUDE, EXCLUDE]. WHITELIST and BLACKLIST are deprecated, but are still accepted and mapped to INCLUDE or EXCLUDE Enum: `INCLUDE`,`EXCLUDE`
country_codes	array[string]
type_restriction	object
inclusion	string	Acceptable values are (case-insensitive): [INCLUDE, EXCLUDE]. WHITELIST and BLACKLIST are deprecated, but are still accepted and mapped to INCLUDE or EXCLUDE Enum: `INCLUDE`,`EXCLUDE`
document_types	array[string]
requested_tasks		Mutually exclusive with identity_profile_requirements
object	object
type	string	Enum: `ID_DOCUMENT_TEXT_DATA_EXTRACTION`
config	object
manual_check	string	Acceptable values vary for each check type, but may be one of: [NEVER, FALLBACK, ALWAYS] Enum: `NEVER`,`FALLBACK`,`ALWAYS`
chip_data	string	Enum: `DESIRED`,`IGNORE`
required_documents		Allows the Relying Business to require multiple documents and filter the list of allowable document countries/types. Mutually exclusive with identity_profile_requirements
object	object
type	string	Enum: `ID_DOCUMENT`
filter		Any filters that results in an empty list of allowed documents will be rejected
object	object
type	string	Enum: `ORTHOGONAL_RESTRICTIONS`
allow_non_latin_documents	boolean
allow_expired_documents	boolean
country_restriction	object
inclusion	string	Acceptable values are (case-insensitive): [INCLUDE, EXCLUDE]. WHITELIST and BLACKLIST are deprecated, but are still accepted and mapped to INCLUDE or EXCLUDE Enum: `INCLUDE`,`EXCLUDE`
country_codes	array[string]
type_restriction	object
inclusion	string	Acceptable values are (case-insensitive): [INCLUDE, EXCLUDE]. WHITELIST and BLACKLIST are deprecated, but are still accepted and mapped to INCLUDE or EXCLUDE Enum: `INCLUDE`,`EXCLUDE`
document_types	array[string]
sdk_config	object
allowed_capture_methods	string	Acceptable values are (case-insensitive): [CAMERA_AND_UPLOAD, CAMERA] Enum: `CAMERA_AND_UPLOAD`,`CAMERA`
primary_colour	string	pattern: `^#([A-Fa-f0-9]{6}\|[A-Fa-f0-9]{3})$`
secondary_colour	string	pattern: `^#([A-Fa-f0-9]{6}\|[A-Fa-f0-9]{3})$`
font_colour	string	pattern: `^#([A-Fa-f0-9]{6}\|[A-Fa-f0-9]{3})$`
locale	string	pattern: `^(?!\s*$).+`
preset_issuing_country	string
success_url	string
error_url	string
privacy_policy_url	string
attempts_configuration	object	Allows the relying business to specify the number of retries allowed for certain scenarios.
ID_DOCUMENT_TEXT_DATA_EXTRACTION	object	Retry configuration for ID document text extraction tasks. This is treated as a map, and so keys are subject to change
*	integer
allow_handoff	boolean	Allows the relying business to enable/disable handoff functionality (normally defaults to false, but some orgs are defaulted to true in the env configs)

Expand

POST /sessions

xxxxxxxxxx
 
curl --request POST \ --url 'https://api.yoti.com/idverify/v1/sessions' \ --header 'X-Yoti-Auth-Digest: {X-Yoti-Auth-Digest}' \ --data sdkId={sdkId} \ --data nonce={nonce} \ --data timestamp={timestamp} \ --data '{  "client_session_token_ttl": 600,  "session_deadline": "2021-08-16T21:33:03.000Z",  "resources_ttl": "{integer}",  "import_token": "{}",  "user_tracking_id": "{string}",  "block_biometric_consent": "{boolean}",  "notifications": {    "endpoint": "https://example.com/idv/notification",    "topics": [      "RESOURCE_UPDATE",      "TASK_COMPLETION",      "CHECK_COMPLETION",      "SESSION_COMPLETION"    ],    "auth_token": "{string}",    "auth_type": "{string}"  },  "requested_checks": [    {      "type": "{string}",      "config": {        "manual_check": "FALLBACK",        "issuing_authority_sub_check": {          "requested": "{boolean}",          "filter": {            "type": "{string}",            "allow_non_latin_documents": "{boolean}",            "allow_expired_documents": "{boolean}",            "country_restriction": {              "inclusion": "INCLUDE",              "country_codes": [                "GBR",                "FRA"              ]            },            "type_restriction": {              "inclusion": "INCLUDE",              "document_types": [                "PASSPORT",                "STATE_ID"              ]            }          }        }      }    }  ],  "requested_tasks": [    {      "type": "{string}",      "config": {        "manual_check": "FALLBACK",        "chip_data": "{string}"      }    }  ],  "required_documents": [    {      "type": "{string}",      "filter": {        "type": "{string}",        "allow_non_latin_documents": "{boolean}",        "allow_expired_documents": "{boolean}",        "country_restriction": {          "inclusion": "INCLUDE",          "country_codes": [            "GBR",            "FRA"          ]        },        "type_restriction": {          "inclusion": "INCLUDE",          "document_types": [            "PASSPORT",            "STATE_ID"          ]        }      }    }  ],  "sdk_config": {    "allowed_capture_methods": "CAMERA_AND_UPLOAD",    "primary_colour": "#2d9fff",    "secondary_colour": "#FFFFFF",    "font_colour": "#FFFFFF",    "locale": "en-US",    "preset_issuing_country": "USA",    "success_url": "https://example.com/idv/success",    "error_url": "https://example.com/idv/error",    "privacy_policy_url": "http://example.com/policy/privacy",    "attempts_configuration": {      "ID_DOCUMENT_TEXT_DATA_EXTRACTION": {        "GENERIC": 3,        "RECLASSIFICATION": 2      }    },    "allow_handoff": "{boolean}"  }}'
Copy

Expand

Responses

201

Session created

object	object	Create Session Response Body
client_session_token_ttl	integer	remaining time the user has to complete the session
client_session_token	uuid	client token to be used for auth of any calls made by client for this session
sessionId	uuid

400

Payload validation error or malformed request

401

Unauthorised request (wrong key or signature)

403

Unauthorised request (app is disabled or has no associated organisation_id)

404

The application for provided sdk id does not exist

503

The service is unavailable

Response

xxxxxxxxxx
 
{ "client_session_token_ttl": 599, "client_session_token": "{uuid}", "sessionId": "{uuid}"}
Copy

Retrieve the entire Session

Auth

Path Params

sessionId string

Query String

sdkId	string	Required if using a Signed Request as the authentication scheme
timestamp	string	Required if using a Signed Request as the authentication scheme
nonce	string	Required if using a Signed Request as the authentication scheme

GET /sessions/{sessionId}

xxxxxxxxxx
 
curl --get \ --url 'https://api.yoti.com/idverify/v1/sessions/%7BsessionId%7D' \ --header 'X-Yoti-Auth-Digest: {X-Yoti-Auth-Digest}' \ --data sdkId={sdkId} \ --data timestamp={timestamp} \ --data nonce={nonce}
Copy

Responses

200

object	object
sessionId	uuid
client_session_token_ttl	integer	remaining time the user has to complete the session
import_token	object
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
failure_reason	string
user_tracking_id	string
biometric_consent	date-time
state	string	The current state of the session Enum: `ONGOING`,`COMPLETED`,`EXPIRED`
client_session_token	uuid	client token to be used for auth of any calls made by client for this session
resources	object
id_documents	array[object]
id	uuid
source	object
type	string	Enum: `END_USER`,`RELYING_BUSINESS`
document_type	string
issuing_country	string
pages	array[object]
capture_method	string	Acceptable values are (case-insensitive): [CAMERA, UPLOAD] Enum: `CAMERA`,`UPLOAD`
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
frames	array[object]	The frames for page media.
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
document_fields	object
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
document_id_photo	object
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
created_at	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
tasks	array
id	uuid
state	string	Enum: `DONE`,`PENDING`,`CREATED`,`FAILED`
created	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
generated_media	array[object]
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
generated_checks	array[object]
id	uuid
type	string	Enum: `ID_DOCUMENT_TEXT_DATA_CHECK`,`SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK`
type	string	Enum: `ID_DOCUMENT_TEXT_DATA_EXTRACTION`
supplementary_documents	array[object]
id	uuid
source	object
type	string	Enum: `END_USER`,`RELYING_BUSINESS`
document_type	string
issuing_country	string
file	object
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
pages	array[object]
capture_method	string	Acceptable values are (case-insensitive): [CAMERA, UPLOAD] Enum: `CAMERA`,`UPLOAD`
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
frames	array[object]	The frames for page media.
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
document_fields	object
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
created_at	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
tasks	array
id	uuid
state	string	Enum: `DONE`,`PENDING`,`CREATED`,`FAILED`
created	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
generated_media	array[object]
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
generated_checks	array[object]
id	uuid
type	string	Enum: `ID_DOCUMENT_TEXT_DATA_CHECK`,`SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK`
type	string	Enum: `SUPPLEMENTARY_DOCUMENT_TEXT_DATA_EXTRACTION`
liveness_capture	array[object]
id	uuid
source	object
type	string	Enum: `END_USER`,`RELYING_BUSINESS`
liveness_type	string	Enum: `STATIC`,`ZOOM`
facemap	object
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
frames	array[object]	The frames (images) for a Zoom liveness capture. first frame should always have media in a completed liveness resource. The first three frames should always have media in a completed zoom liveness resource. Media might be null for frames 4-7
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
created_at	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
tasks	array[object]
image	object
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
face_capture	array[object]
id	uuid
source	object
type	string	Enum: `END_USER`,`RELYING_BUSINESS`
image	object
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
created_at	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
tasks	array[object]
checks
object	object
id	uuid
type	string	Enum: `ID_DOCUMENT_AUTHENTICITY`
state	string	The current state of the Check Enum: `CREATED`,`READY`,`PENDING`,`DONE`,`INTERNAL_ERROR`
resources_used	array[string]
generated_media	array[object]
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
report	object
recommendation	object
value	string	Enum: `APPROVE`,`REJECT`,`NOT_AVAILABLE`,`CONSIDER`
reason	string	must be preset if 'value' is 'REJECT'
recovery_suggestion	string	must be present if 'value' is 'REJECT'
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
created	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times

Expand

400

Invalid payload or request missing headers or query params

401

Unauthorised request (wrong key or signature)

404

Session or App not found

Response

xxxxxxxxxx
 
{
 "sessionId": "{uuid}", "client_session_token_ttl": 599, "import_token": {...},
 "user_tracking_id": "{string}", "biometric_consent": "{date-time}", "state": "{string}", "client_session_token": "{uuid}", "resources": {...},
 "checks": [...]
}
Copy

Delete the session and everything associated with it

Auth

Path Params

sessionId string

Query String

sdkId	string	Required if using a Signed Request as the authentication scheme
timestamp	string	Required if using a Signed Request as the authentication scheme
nonce	string	Required if using a Signed Request as the authentication scheme

DELETE /sessions/{sessionId}

xxxxxxxxxx
 
curl --request DELETE \ --url 'https://api.yoti.com/idverify/v1/sessions/%7BsessionId%7D' \ --header 'X-Yoti-Auth-Digest: {X-Yoti-Auth-Digest}' \ --data sdkId={sdkId} \ --data timestamp={timestamp} \ --data nonce={nonce}
Copy

Responses

204

Session deleted

No response body

400

Invalid payload or request missing headers or query params

401

Unauthorised request (wrong key or signature)

404

App not found

409

The checks are not finished

Response

xxxxxxxxxx
 
No response
Copy

Retrieve media content

Retrieves a specific media

Auth

Headers

X-Yoti-Device-Meta

string

X-Yoti-Device-Meta header containing a base64 encoded JSON with DeviceMetadata (as per the schema)

Path Params

sessionId	string
mediaId	string

Query String

sdkId	string	Required if using a Signed Request as the authentication scheme
nonce	string	Required if using a Signed Request as the authentication scheme
timestamp	string	Required if using a Signed Request as the authentication scheme

GET /sessions/{sessionId}/media/{mediaId}/content

xxxxxxxxxx
 
curl --get \ --url 'https://api.yoti.com/idverify/v1/sessions/%7BsessionId%7D/media/%7BmediaId%7D/content' \ --header 'X-Yoti-Device-Meta: eyJtYW51ZmFjdHVyZV9uYW1lIjoiQXBwbGUiLCJtb2RlbF9uYW1lIjoiSXBob25lWCIsImJyb3dzZXJfbmFtZSI6IkNocm9tZSIsImJyb3dzZXJfdmVyc2lvbiI6IjcyLjAuMzYyNi4xMTkiLCJsb2NhbGUiOiJlbi1HQiIsImNsaWVudF92ZXJzaW9uIjoiMi4xMi4wIiwib3NfbmFtZSI6Ik1hY09zIiwib3NfdmVyc2lvbiI6IjEwLjEzLjE0IiwicHJvZHVjdCI6M30=' \ --header 'X-Yoti-Auth-Digest: {X-Yoti-Auth-Digest}' \ --data sdkId={sdkId} \ --data nonce={nonce} \ --data timestamp={timestamp}
Copy

Responses

200

OK. Response body depends on Content-Type of the media

No response body

204

OK. Regulations prevent us from returning the media content

400

Bad Request

401

Unauthorised request (wrong key or signature)

404

Session, Media or App not found

Response

xxxxxxxxxx
 
No response
Copy

Delete media content

Deletes a specific media content

Auth

Headers

X-Yoti-Device-Meta

string

X-Yoti-Device-Meta header containing a base64 encoded JSON with DeviceMetadata (as per the schema)

Path Params

sessionId	string
mediaId	string

Query String

sdkId	string	Required if using a Signed Request as the authentication scheme
nonce	string	Required if using a Signed Request as the authentication scheme
timestamp	string	Required if using a Signed Request as the authentication scheme

DELETE /sessions/{sessionId}/media/{mediaId}/content

xxxxxxxxxx
 
curl --request DELETE \ --url 'https://api.yoti.com/idverify/v1/sessions/%7BsessionId%7D/media/%7BmediaId%7D/content' \ --header 'X-Yoti-Device-Meta: eyJtYW51ZmFjdHVyZV9uYW1lIjoiQXBwbGUiLCJtb2RlbF9uYW1lIjoiSXBob25lWCIsImJyb3dzZXJfbmFtZSI6IkNocm9tZSIsImJyb3dzZXJfdmVyc2lvbiI6IjcyLjAuMzYyNi4xMTkiLCJsb2NhbGUiOiJlbi1HQiIsImNsaWVudF92ZXJzaW9uIjoiMi4xMi4wIiwib3NfbmFtZSI6Ik1hY09zIiwib3NfdmVyc2lvbiI6IjEwLjEzLjE0IiwicHJvZHVjdCI6M30=' \ --header 'X-Yoti-Auth-Digest: {X-Yoti-Auth-Digest}' \ --data sdkId={sdkId} \ --data nonce={nonce} \ --data timestamp={timestamp}
Copy

Responses

204

No content

No response body

400

Bad Request

401

Unauthorised request (wrong key or signature)

404

Session, Media or App not found

409

Session is locked (session in progress before triggering checks) or Resource is locked (session in progress with checks triggered)

Response

xxxxxxxxxx
 
No response
Copy

Response Config Endpoints

Endpoints for configuring Sandbox behaviour

GET

/apps/{sdkId}/response-config

PUT

/apps/{sdkId}/response-config

GET

/sessions/{sessionId}/response-config

PUT

/sessions/{sessionId}/response-config

Fetch the configuration for a specified sdk application ID

Auth

Path Params

sdkId string

Query String

sdkId	string	Required if using a Signed Request as the authentication scheme
timestamp	string	Required if using a Signed Request as the authentication scheme
nonce	string	Required if using a Signed Request as the authentication scheme

GET /apps/{sdkId}/response-config

xxxxxxxxxx
 
curl --get \ --url 'https://api.yoti.com/idverify/v1/apps/%7BsdkId%7D/response-config' \ --header 'X-Yoti-Auth-Digest: {X-Yoti-Auth-Digest}' \ --data sdkId={sdkId} \ --data timestamp={timestamp} \ --data nonce={nonce}
Copy

Responses

200

object	object	Configuration Response
task_results	object
ID_DOCUMENT_TEXT_DATA_EXTRACTION	array
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
document_fields	object
detected_country	string	The detected country of origin for the identity document. Must be a 3 letter ISO code in uppercase
recommendation	object	Provide in-session feedback
value	string	Enum: `PROGRESS`,`MUST_TRY_AGAIN`,`SHOULD_TRY_AGAIN`
reason	object	Provide in-session feedback reason
value	string	Enum: `QUALITY`,`USER_ERROR`,`ERROR`
detail	string
SUPPLEMENTARY_DOCUMENT_TEXT_DATA_EXTRACTION	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
document_fields	object
detected_country	string	The detected country of origin for the identity document. Must be a 3 letter ISO code in uppercase
recommendation	object	Provide in-session feedback
value	string	Enum: `PROGRESS`,`MUST_TRY_AGAIN`,`SHOULD_TRY_AGAIN`
reason	object	Provide in-session feedback reason
value	string	Enum: `QUALITY`,`USER_ERROR`,`ERROR`
detail	string
check_reports	object
ID_DOCUMENT_AUTHENTICITY	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_TEXT_DATA_CHECK	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
ID_DOCUMENT_FACE_MATCH	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
LIVENESS	array[object]
liveness_type	string
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_COMPARISON	array[object]
secondary_document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
THIRD_PARTY_IDENTITY	object
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
async_report_delay	integer

Expand

400

Invalid payload or request missing headers or query params

401

Unauthorised request (wrong key or signature)

404

App not found

Response

xxxxxxxxxx
 
{
 "task_results": {...},
 "check_reports": {...}
}
Copy

Update the configuration for a specified sdk application ID

Auth

Path Params

sdkId string

Query String

sdkId	string	Required if using a Signed Request as the authentication scheme
timestamp	string	Required if using a Signed Request as the authentication scheme
nonce	string	Required if using a Signed Request as the authentication scheme

Request Body

object	object	Configuration Payload
task_results	object	Task Results Payload
ID_DOCUMENT_TEXT_DATA_EXTRACTION	array
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
document_fields	object
detected_country	string	The detected country of origin for the identity document. Must be a 3 letter ISO code in uppercase
recommendation	object	Provide in-session feedback
value	string	Enum: `PROGRESS`,`MUST_TRY_AGAIN`,`SHOULD_TRY_AGAIN`
reason	object	Provide in-session feedback reason
value	string	Enum: `QUALITY`,`USER_ERROR`,`ERROR`
detail	string
SUPPLEMENTARY_DOCUMENT_TEXT_DATA_EXTRACTION	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
document_fields	object
detected_country	string	The detected country of origin for the identity document. Must be a 3 letter ISO code in uppercase
recommendation	object	Provide in-session feedback
value	string	Enum: `PROGRESS`,`MUST_TRY_AGAIN`,`SHOULD_TRY_AGAIN`
reason	object	Provide in-session feedback reason
value	string	Enum: `QUALITY`,`USER_ERROR`,`ERROR`
detail	string
check_reports	object
ID_DOCUMENT_AUTHENTICITY	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_TEXT_DATA_CHECK	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
ID_DOCUMENT_FACE_MATCH	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
LIVENESS	array[object]
liveness_type	string
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
THIRD_PARTY_IDENTITY	object
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_COMPARISON	array[object]
secondary_document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
async_report_delay	integer

Expand

PUT /apps/{sdkId}/response-config

xxxxxxxxxx
 
curl --request PUT \ --url 'https://api.yoti.com/idverify/v1/apps/%7BsdkId%7D/response-config' \ --header 'X-Yoti-Auth-Digest: {X-Yoti-Auth-Digest}' \ --data sdkId={sdkId} \ --data timestamp={timestamp} \ --data nonce={nonce} \ --data '{  "task_results": {    "ID_DOCUMENT_TEXT_DATA_EXTRACTION": [      {        "document_filter": {          "country_codes": [            "ARE",            "GBR"          ],          "document_types": [            "NATIONAL_ID",            "PASSPORT"          ]        },        "result": {          "document_fields": {},          "detected_country": "GBR",          "recommendation": {            "value": "{string}",            "reason": {              "value": "{string}",              "detail": "{string}"            }          }        }      }    ],    "SUPPLEMENTARY_DOCUMENT_TEXT_DATA_EXTRACTION": [      {        "document_filter": {          "country_codes": [            "ARE",            "GBR"          ],          "document_types": [            "NATIONAL_ID",            "PASSPORT"          ]        },        "result": {          "document_fields": {},          "detected_country": "GBR",          "recommendation": {            "value": "{string}",            "reason": {              "value": "{string}",              "detail": "{string}"            }          }        }      }    ]  },  "check_reports": {    "ID_DOCUMENT_AUTHENTICITY": [      {        "document_filter": {          "country_codes": [            "ARE",            "GBR"          ],          "document_types": [            "NATIONAL_ID",            "PASSPORT"          ]        },        "result": {          "report": {            "recommendation": {              "value": "{string}",              "reason": "{string}",              "recovery_suggestion": "{string}"            },            "breakdown": [              {                "sub_check": "{string}",                "result": "{string}",                "details": [                  {}                ]              }            ]          }        }      }    ],    "ID_DOCUMENT_TEXT_DATA_CHECK": [      {        "document_filter": {          "country_codes": [            "ARE",            "GBR"          ],          "document_types": [            "NATIONAL_ID",            "PASSPORT"          ]        },        "result": {          "report": {            "recommendation": {              "value": "{string}",              "reason": "{string}",              "recovery_suggestion": "{string}"            },            "breakdown": [              {                "sub_check": "{string}",                "result": "{string}",                "details": [                  {}                ]              }            ]          },          "document_fields": {}        }      }    ],    "SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK": [      {        "document_filter": {          "country_codes": [            "ARE",            "GBR"          ],          "document_types": [            "NATIONAL_ID",            "PASSPORT"          ]        },        "result": {          "report": {            "recommendation": {              "value": "{string}",              "reason": "{string}",              "recovery_suggestion": "{string}"            },            "breakdown": [              {                "sub_check": "{string}",                "result": "{string}",                "details": [                  {}                ]              }            ]          },          "document_fields": {}        }      }    ],    "ID_DOCUMENT_FACE_MATCH": [      {        "document_filter": {          "country_codes": [            "ARE",            "GBR"          ],          "document_types": [            "NATIONAL_ID",            "PASSPORT"          ]        },        "result": {          "report": {            "recommendation": {              "value": "{string}",              "reason": "{string}",              "recovery_suggestion": "{string}"            },            "breakdown": [              {                "sub_check": "{string}",                "result": "{string}",                "details": [                  {}                ]              }            ]          }        }      }    ],    "LIVENESS": [      {        "liveness_type": "{string}",        "result": {          "report": {            "recommendation": {              "value": "{string}",              "reason": "{string}",              "recovery_suggestion": "{string}"            },            "breakdown": [              {                "sub_check": "{string}",                "result": "{string}",                "details": [                  {}                ]              }            ]          }        }      }    ],    "THIRD_PARTY_IDENTITY": {      "result": {        "report": {          "recommendation": {            "value": "{string}",            "reason": "{string}",            "recovery_suggestion": "{string}"          },          "breakdown": [            {              "sub_check": "{string}",              "result": "{string}",              "details": [                {}              ]            }          ]        }      }    },    "ID_DOCUMENT_COMPARISON": [      {        "secondary_document_filter": {          "country_codes": [            "ARE",            "GBR"          ],          "document_types": [            "NATIONAL_ID",            "PASSPORT"          ]        },        "result": {          "report": {            "recommendation": {              "value": "{string}",              "reason": "{string}",              "recovery_suggestion": "{string}"            },            "breakdown": [              {                "sub_check": "{string}",                "result": "{string}",                "details": [                  {}                ]              }            ]          }        }      }    ],    "async_report_delay": "{integer}"  }}'
Copy

Expand

Responses

200

Updated configuration successfully

No response body

400

Invalid payload or request missing headers or query params

401

Unauthorised request (wrong key or signature)

403

Unauthorised request (app is disabled or has no associated organisation_id)

404

App not found

503

The service is unavailable

Response

xxxxxxxxxx
 
No response
Copy

Get the configured config for a specified session ID

Auth

Path Params

sessionId string

Query String

sdkId	string	Required if using a Signed Request as the authentication scheme
timestamp	string	Required if using a Signed Request as the authentication scheme
nonce	string	Required if using a Signed Request as the authentication scheme

GET /sessions/{sessionId}/response-config

xxxxxxxxxx
 
curl --get \ --url 'https://api.yoti.com/idverify/v1/sessions/%7BsessionId%7D/response-config' \ --header 'X-Yoti-Auth-Digest: {X-Yoti-Auth-Digest}' \ --data sdkId={sdkId} \ --data timestamp={timestamp} \ --data nonce={nonce}
Copy

Responses

200

object	object	Configuration Response
task_results	object
ID_DOCUMENT_TEXT_DATA_EXTRACTION	array
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
document_fields	object
detected_country	string	The detected country of origin for the identity document. Must be a 3 letter ISO code in uppercase
recommendation	object	Provide in-session feedback
value	string	Enum: `PROGRESS`,`MUST_TRY_AGAIN`,`SHOULD_TRY_AGAIN`
reason	object	Provide in-session feedback reason
value	string	Enum: `QUALITY`,`USER_ERROR`,`ERROR`
detail	string
SUPPLEMENTARY_DOCUMENT_TEXT_DATA_EXTRACTION	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
document_fields	object
detected_country	string	The detected country of origin for the identity document. Must be a 3 letter ISO code in uppercase
recommendation	object	Provide in-session feedback
value	string	Enum: `PROGRESS`,`MUST_TRY_AGAIN`,`SHOULD_TRY_AGAIN`
reason	object	Provide in-session feedback reason
value	string	Enum: `QUALITY`,`USER_ERROR`,`ERROR`
detail	string
check_reports	object
ID_DOCUMENT_AUTHENTICITY	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_TEXT_DATA_CHECK	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
ID_DOCUMENT_FACE_MATCH	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
LIVENESS	array[object]
liveness_type	string
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_COMPARISON	array[object]
secondary_document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
THIRD_PARTY_IDENTITY	object
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
async_report_delay	integer

Expand

400

Invalid payload or request missing headers or query params

401

Unauthorised request (wrong key or signature)

404

Session or App not found

Response

xxxxxxxxxx
 
{
 "task_results": {...},
 "check_reports": {...}
}
Copy

Update the configuration for a specified session ID

Auth

Path Params

sessionId string

Query String

sdkId	string	Required if using a Signed Request as the authentication scheme
timestamp	string	Required if using a Signed Request as the authentication scheme
nonce	string	Required if using a Signed Request as the authentication scheme

Request Body

object	object	Configuration Payload
task_results	object	Task Results Payload
ID_DOCUMENT_TEXT_DATA_EXTRACTION	array
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
document_fields	object
detected_country	string	The detected country of origin for the identity document. Must be a 3 letter ISO code in uppercase
recommendation	object	Provide in-session feedback
value	string	Enum: `PROGRESS`,`MUST_TRY_AGAIN`,`SHOULD_TRY_AGAIN`
reason	object	Provide in-session feedback reason
value	string	Enum: `QUALITY`,`USER_ERROR`,`ERROR`
detail	string
SUPPLEMENTARY_DOCUMENT_TEXT_DATA_EXTRACTION	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
document_fields	object
detected_country	string	The detected country of origin for the identity document. Must be a 3 letter ISO code in uppercase
recommendation	object	Provide in-session feedback
value	string	Enum: `PROGRESS`,`MUST_TRY_AGAIN`,`SHOULD_TRY_AGAIN`
reason	object	Provide in-session feedback reason
value	string	Enum: `QUALITY`,`USER_ERROR`,`ERROR`
detail	string
check_reports	object
ID_DOCUMENT_AUTHENTICITY	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_TEXT_DATA_CHECK	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
ID_DOCUMENT_FACE_MATCH	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
LIVENESS	array[object]
liveness_type	string
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
THIRD_PARTY_IDENTITY	object
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_COMPARISON	array[object]
secondary_document_filter	object
country_codes	array[string]
document_types	array[string]
result	object
report	object
recommendation	object
value	string
reason	string
recovery_suggestion	string
breakdown	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
async_report_delay	integer

Expand

PUT /sessions/{sessionId}/response-config

xxxxxxxxxx
 
curl --request PUT \ --url 'https://api.yoti.com/idverify/v1/sessions/%7BsessionId%7D/response-config' \ --header 'X-Yoti-Auth-Digest: {X-Yoti-Auth-Digest}' \ --data sdkId={sdkId} \ --data timestamp={timestamp} \ --data nonce={nonce} \ --data '{  "task_results": {    "ID_DOCUMENT_TEXT_DATA_EXTRACTION": [      {        "document_filter": {          "country_codes": [            "ARE",            "GBR"          ],          "document_types": [            "NATIONAL_ID",            "PASSPORT"          ]        },        "result": {          "document_fields": {},          "detected_country": "GBR",          "recommendation": {            "value": "{string}",            "reason": {              "value": "{string}",              "detail": "{string}"            }          }        }      }    ],    "SUPPLEMENTARY_DOCUMENT_TEXT_DATA_EXTRACTION": [      {        "document_filter": {          "country_codes": [            "ARE",            "GBR"          ],          "document_types": [            "NATIONAL_ID",            "PASSPORT"          ]        },        "result": {          "document_fields": {},          "detected_country": "GBR",          "recommendation": {            "value": "{string}",            "reason": {              "value": "{string}",              "detail": "{string}"            }          }        }      }    ]  },  "check_reports": {    "ID_DOCUMENT_AUTHENTICITY": [      {        "document_filter": {          "country_codes": [            "ARE",            "GBR"          ],          "document_types": [            "NATIONAL_ID",            "PASSPORT"          ]        },        "result": {          "report": {            "recommendation": {              "value": "{string}",              "reason": "{string}",              "recovery_suggestion": "{string}"            },            "breakdown": [              {                "sub_check": "{string}",                "result": "{string}",                "details": [                  {}                ]              }            ]          }        }      }    ],    "ID_DOCUMENT_TEXT_DATA_CHECK": [      {        "document_filter": {          "country_codes": [            "ARE",            "GBR"          ],          "document_types": [            "NATIONAL_ID",            "PASSPORT"          ]        },        "result": {          "report": {            "recommendation": {              "value": "{string}",              "reason": "{string}",              "recovery_suggestion": "{string}"            },            "breakdown": [              {                "sub_check": "{string}",                "result": "{string}",                "details": [                  {}                ]              }            ]          },          "document_fields": {}        }      }    ],    "SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK": [      {        "document_filter": {          "country_codes": [            "ARE",            "GBR"          ],          "document_types": [            "NATIONAL_ID",            "PASSPORT"          ]        },        "result": {          "report": {            "recommendation": {              "value": "{string}",              "reason": "{string}",              "recovery_suggestion": "{string}"            },            "breakdown": [              {                "sub_check": "{string}",                "result": "{string}",                "details": [                  {}                ]              }            ]          },          "document_fields": {}        }      }    ],    "ID_DOCUMENT_FACE_MATCH": [      {        "document_filter": {          "country_codes": [            "ARE",            "GBR"          ],          "document_types": [            "NATIONAL_ID",            "PASSPORT"          ]        },        "result": {          "report": {            "recommendation": {              "value": "{string}",              "reason": "{string}",              "recovery_suggestion": "{string}"            },            "breakdown": [              {                "sub_check": "{string}",                "result": "{string}",                "details": [                  {}                ]              }            ]          }        }      }    ],    "LIVENESS": [      {        "liveness_type": "{string}",        "result": {          "report": {            "recommendation": {              "value": "{string}",              "reason": "{string}",              "recovery_suggestion": "{string}"            },            "breakdown": [              {                "sub_check": "{string}",                "result": "{string}",                "details": [                  {}                ]              }            ]          }        }      }    ],    "THIRD_PARTY_IDENTITY": {      "result": {        "report": {          "recommendation": {            "value": "{string}",            "reason": "{string}",            "recovery_suggestion": "{string}"          },          "breakdown": [            {              "sub_check": "{string}",              "result": "{string}",              "details": [                {}              ]            }          ]        }      }    },    "ID_DOCUMENT_COMPARISON": [      {        "secondary_document_filter": {          "country_codes": [            "ARE",            "GBR"          ],          "document_types": [            "NATIONAL_ID",            "PASSPORT"          ]        },        "result": {          "report": {            "recommendation": {              "value": "{string}",              "reason": "{string}",              "recovery_suggestion": "{string}"            },            "breakdown": [              {                "sub_check": "{string}",                "result": "{string}",                "details": [                  {}                ]              }            ]          }        }      }    ],    "async_report_delay": "{integer}"  }}'
Copy

Expand

Responses

200

Updated configuration successfully

No response body

400

Invalid payload or request missing headers or query params

401

Unauthorised request (wrong key or signature)

403

Unauthorised request (app is disabled or has no associated organisation_id)

404

App not found

503

The service is unavailable

Response

xxxxxxxxxx
 
No response
Copy