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

Default: false

GET /supported-documents

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

Responses

200

object	object
supported_countries2 fields	array[object]
code	string
supported_documents3 fields	array[object]
type	string
is_strictly_latin	boolean
requirements	object
date_from	string

Response

 
{ "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 Default: false
notifications4 fields	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`
config2 fields	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_config11 fields	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) Default: false

POST /sessions

 
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

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

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

 
curl --get \ --url 'https://api.yoti.com/idverify/v1/sessions/{sessionId}' \ --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_token2 fields	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
resources4 fields	object
id_documents10 fields	array[object]
id	uuid
source	object
type	string	Enum: `END_USER`,`RELYING_BUSINESS`
document_type	string
issuing_country	string
pages3 fields	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`
frames1 field	array[object]	The frames for page media.
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
document_fields1 field	object
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
document_id_photo1 field	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_documents10 fields	array[object]
id	uuid
source	object
type	string	Enum: `END_USER`,`RELYING_BUSINESS`
document_type	string
issuing_country	string
file1 field	object
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
pages3 fields	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`
frames1 field	array[object]	The frames for page media.
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
document_fields1 field	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_capture9 fields	array[object]
id	uuid
source	object
type	string	Enum: `END_USER`,`RELYING_BUSINESS`
liveness_type	string	Enum: `STATIC`,`ZOOM`
facemap1 field	object
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
frames1 field	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]
image1 field	object
media	object
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`,`PDF`
face_capture6 fields	array[object]
id	uuid
source	object
type	string	Enum: `END_USER`,`RELYING_BUSINESS`
image1 field	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`
report2 fields	object
recommendation3 fields	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'
breakdown3 fields	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

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}

 
curl --request DELETE \ --url 'https://api.yoti.com/idverify/v1/sessions/{sessionId}' \ --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

 
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

 
curl --get \ --url 'https://api.yoti.com/idverify/v1/sessions/{sessionId}/media/{mediaId}/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

 
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

 
curl --request DELETE \ --url 'https://api.yoti.com/idverify/v1/sessions/{sessionId}/media/{mediaId}/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

 
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

 
curl --get \ --url 'https://api.yoti.com/idverify/v1/apps/{sdkId}/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_results2 fields	object
ID_DOCUMENT_TEXT_DATA_EXTRACTION1 field	array
document_filter	object
country_codes	array[string]
document_types	array[string]
result3 fields	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
recommendation2 fields	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_EXTRACTION2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result3 fields	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
recommendation2 fields	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_reports8 fields	object
ID_DOCUMENT_AUTHENTICITY2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_TEXT_DATA_CHECK2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result2 fields	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result2 fields	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
ID_DOCUMENT_FACE_MATCH2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
LIVENESS2 fields	array[object]
liveness_type	string
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_COMPARISON2 fields	array[object]
secondary_document_filter	object
country_codes	array[string]
document_types	array[string]
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
THIRD_PARTY_IDENTITY1 field	object
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
async_report_delay	integer

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_results2 fields	object	Task Results Payload
ID_DOCUMENT_TEXT_DATA_EXTRACTION1 field	array
document_filter	object
country_codes	array[string]
document_types	array[string]
result3 fields	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
recommendation2 fields	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_EXTRACTION2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result3 fields	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
recommendation2 fields	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_reports8 fields	object
ID_DOCUMENT_AUTHENTICITY2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_TEXT_DATA_CHECK2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result2 fields	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result2 fields	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
ID_DOCUMENT_FACE_MATCH2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
LIVENESS2 fields	array[object]
liveness_type	string
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
THIRD_PARTY_IDENTITY1 field	object
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_COMPARISON2 fields	array[object]
secondary_document_filter	object
country_codes	array[string]
document_types	array[string]
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
async_report_delay	integer

PUT /apps/{sdkId}/response-config

 
curl --request PUT \ --url 'https://api.yoti.com/idverify/v1/apps/{sdkId}/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

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

 
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

 
curl --get \ --url 'https://api.yoti.com/idverify/v1/sessions/{sessionId}/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_results2 fields	object
ID_DOCUMENT_TEXT_DATA_EXTRACTION1 field	array
document_filter	object
country_codes	array[string]
document_types	array[string]
result3 fields	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
recommendation2 fields	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_EXTRACTION2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result3 fields	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
recommendation2 fields	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_reports8 fields	object
ID_DOCUMENT_AUTHENTICITY2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_TEXT_DATA_CHECK2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result2 fields	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result2 fields	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
ID_DOCUMENT_FACE_MATCH2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
LIVENESS2 fields	array[object]
liveness_type	string
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_COMPARISON2 fields	array[object]
secondary_document_filter	object
country_codes	array[string]
document_types	array[string]
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
THIRD_PARTY_IDENTITY1 field	object
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
async_report_delay	integer

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_results2 fields	object	Task Results Payload
ID_DOCUMENT_TEXT_DATA_EXTRACTION1 field	array
document_filter	object
country_codes	array[string]
document_types	array[string]
result3 fields	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
recommendation2 fields	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_EXTRACTION2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result3 fields	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
recommendation2 fields	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_reports8 fields	object
ID_DOCUMENT_AUTHENTICITY2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_TEXT_DATA_CHECK2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result2 fields	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result2 fields	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
document_fields	object
ID_DOCUMENT_FACE_MATCH2 fields	array[object]
document_filter	object
country_codes	array[string]
document_types	array[string]
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
LIVENESS2 fields	array[object]
liveness_type	string
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
THIRD_PARTY_IDENTITY1 field	object
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
ID_DOCUMENT_COMPARISON2 fields	array[object]
secondary_document_filter	object
country_codes	array[string]
document_types	array[string]
result1 field	object
report2 fields	object
recommendation3 fields	object
value	string
reason	string
recovery_suggestion	string
breakdown3 fields	array[object]
sub_check	string
result	string	Enum: `PASS`,`FAIL`
details	array[object]
async_report_delay	integer

PUT /sessions/{sessionId}/response-config

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