Yoti Identity Verification Public API 1.0.0

Server

www.example.com

Authentication

X-Yoti-Auth-Token header containing the client_session_token value obtained via the Session creation endpoint.

Fields

Key	In
X-Yoti-Auth-Token	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

GET /supported-documents

 
curl --get \ --url 'https://www.example.com//supported-documents' \ --header 'X-Yoti-Auth-Token: {X-Yoti-Auth-Token}'
Copy

Responses application/json

200

SupportedDocuments	object
supported_countries2 fields	array[object]
code	string
supported_documents	array[object]
type	string

Response

 
{ "supported_countries": [  {   "code": "AGO",   "supported_documents": [    {     "type": "DRIVING_LICENCE"    },    {     "type": "NATIONAL_ID"    },    {     "type": "PASSPORT"    }   ]  } ]}
Copy

Create a new session

Auth

Headers

X-Yoti-SDK	string	'X-Yoti-SDK' contains the language the SDK is written in
X-Yoti-SDK-Version	string	'X-Yoti-SDK-Version' contains the version of the SDK being used

Query String

sdkId	string
nonce	string
timestamp	string

Request Body application/json

CreateSessionPayload	object	Create Session Payload
client_session_token_ttl	int32	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	int32	Retention period for uploaded documents/images in number of seconds. minimum: 86700 Default: 87000
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
ibv_options	object
support	string	Determines whether resources must be provided in-branch Enum: `MANDATORY`,`NOT_ALLOWED`
guidance_url	string
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`
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	array[object]
requested_tasks	array[object]
required_documents	array[object]	Allows the Relying Business to require multiple documents and filter the list of allowable document countries/types. Read more here
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
*	int32
enable_handoff	boolean	Allows the relying business to enable/disable a handoff session (if omitted this defaults to true) Default: true

POST /sessions

 
curl --request POST \ --url 'https://www.example.com//sessions' \ --header 'X-Yoti-SDK: {X-Yoti-SDK}' \ --header 'X-Yoti-SDK-Version: {X-Yoti-SDK-Version}' \ --header 'X-Yoti-Auth-Token: {X-Yoti-Auth-Token}' \ --data sdkId={sdkId} \ --data nonce={nonce} \ --data timestamp={timestamp} \ --data '{  "client_session_token_ttl": 600,  "session_deadline": "2021-08-16T13:33:03-08:00",  "resources_ttl": 87000,  "user_tracking_id": "{string}",  "block_biometric_consent": false,  "ibv_options": {    "support": "{string}",    "guidance_url": "{string}"  },  "notifications": {    "endpoint": "{string}",    "topics": [      "RESOURCE_UPDATE",      "TASK_COMPLETION",      "CHECK_COMPLETION",      "SESSION_COMPLETION",      "NEW_PDF_SUPPLIED",      "INSTRUCTIONS_EMAIL_REQUESTED"    ],    "auth_token": "{string}",    "auth_type": "{string}"  },  "requested_checks": [    {}  ],  "requested_tasks": [    {}  ],  "required_documents": [    {}  ],  "sdk_config": {    "allowed_capture_methods": "{string}",    "primary_colour": "#2d9fff",    "secondary_colour": "#FFFFFF",    "font_colour": "#FFFFFF",    "locale": "en-US",    "preset_issuing_country": "USA",    "success_url": "{string}",    "error_url": "{string}",    "privacy_policy_url": "{string}",    "attempts_configuration": {      "ID_DOCUMENT_TEXT_DATA_EXTRACTION": {        "GENERIC": 3,        "RECLASSIFICATION": 2      }    },    "enable_handoff": true  }}'
Copy

Responses application/json

201

Session created

CreateSessionResponseBody	object	Create Session Response Body
client_session_token_ttl	int32	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
session_id	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}", "session_id": "{uuid}"}
Copy

Retrieve the entire Session

Auth

Path Params

sessionId string

Query String

sdkId	string
timestamp	string
nonce	string

GET /sessions/{sessionId}

 
curl --get \ --url 'https://www.example.com//sessions/{sessionId}' \ --header 'X-Yoti-Auth-Token: {X-Yoti-Auth-Token}' \ --data sdkId={sdkId} \ --data timestamp={timestamp} \ --data nonce={nonce}
Copy

Responses application/json

200

SessionResponse	object
session_id	uuid
client_session_token_ttl	int32	remaining time the user has to complete the session
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_documents8 fields	array[object]
id	uuid
source	object
type	string	Enum: `END_USER`,`IBV`,`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`
media4 fields	object
created	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`
frames1 field	array[object]	The frames for page media.
media4 fields	object
created	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`
document_fields1 field	object
media4 fields	object
created	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`
document_id_photo1 field	object
media4 fields	object
created	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`
tasks7 fields	array[object]
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`
generated_checks	array[object]
id	uuid
type	string	Enum: `ID_DOCUMENT_TEXT_DATA_CHECK`,`SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK`
type	string	Default: ID_DOCUMENT_TEXT_DATA_EXTRACTION
supplementary_documents8 fields	array[object]
id	uuid
source	object
type	string	Enum: `END_USER`,`IBV`,`RELYING_BUSINESS`
document_type	string
issuing_country	string
file1 field	object
media4 fields	object
created	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`
pages3 fields	array[object]
capture_method	string	Acceptable values are (case-insensitive): [CAMERA, UPLOAD] Enum: `CAMERA`,`UPLOAD`
media4 fields	object
created	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`
frames1 field	array[object]	The frames for page media.
media4 fields	object
created	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`
document_fields1 field	object
media4 fields	object
created	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`
tasks7 fields	array[object]
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`
generated_checks	array[object]
id	uuid
type	string	Enum: `ID_DOCUMENT_TEXT_DATA_CHECK`,`SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK`
type	string	Default: SUPPLEMENTARY_DOCUMENT_TEXT_DATA_EXTRACTION
liveness_capture6 fields	array[object]
id	uuid
source	object
type	string	Enum: `END_USER`,`IBV`,`RELYING_BUSINESS`
liveness_type	string	Default: ZOOM
facemap1 field	object
media4 fields	object
created	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`
frames1 field	array[object]	The first three frames should always have media in a completed zoom liveness resource. Media might be null for frames 4-7
media4 fields	object
created	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`
tasks	array[object]
face_capture4 fields	array[object]
id	uuid
source	object
type	string	Enum: `END_USER`,`IBV`,`RELYING_BUSINESS`
image1 field	object
media4 fields	object
created	date-time	Uses the ISO8601 standard representation of date times
last_updated	date-time	Uses the ISO8601 standard representation of date times
id	uuid
type	string	Enum: `IMAGE`,`JSON`,`BINARY`
tasks	array[object]
checks	array[object]

400

Invalid payload or request missing headers or query params

401

Unauthorised request (wrong key or signature)

404

Session or App not found

Response

 
{ "session_id": "{uuid}", "client_session_token_ttl": 599, "user_tracking_id": "{string}", "biometric_consent": "{date-time}", "state": "{string}", "client_session_token": "{uuid}", "resources": {  "id_documents": [   {    "id": "{uuid}",    "source": {     "type": "{string}"    },    "document_type": "{string}",    "issuing_country": "{string}",    "pages": [     {      "capture_method": "{string}",      "media": {       "created": "2021-06-11T11:39:24Z",       "last_updated": "2021-06-11T11:39:24Z",       "id": "{uuid}",       "type": "{string}"      },      "frames": [       {        "media": {         "created": "2021-06-11T11:39:24Z",         "last_updated": "2021-06-11T11:39:24Z",         "id": "{uuid}",         "type": "{string}"        }       }      ]     }    ],    "document_fields": {     "media": {      "created": "2021-06-11T11:39:24Z",      "last_updated": "2021-06-11T11:39:24Z",      "id": "{uuid}",      "type": "{string}"     }    },    "document_id_photo": {     "media": {      "created": "2021-06-11T11:39:24Z",      "last_updated": "2021-06-11T11:39:24Z",      "id": "{uuid}",      "type": "{string}"     }    },    "tasks": [     {      "id": "{uuid}",      "state": "{string}",      "created": "2021-06-11T11:39:24Z",      "last_updated": "2021-06-11T11:39:24Z",      "generated_media": [       {        "id": "{uuid}",        "type": "{string}"       }      ],      "generated_checks": [       {        "id": "{uuid}",        "type": "{string}"       }      ],      "type": "ID_DOCUMENT_TEXT_DATA_EXTRACTION"     }    ]   }  ],  "supplementary_documents": [   {    "id": "{uuid}",    "source": {     "type": "{string}"    },    "document_type": "{string}",    "issuing_country": "{string}",    "file": {     "media": {      "created": "2021-06-11T11:39:24Z",      "last_updated": "2021-06-11T11:39:24Z",      "id": "{uuid}",      "type": "{string}"     }    },    "pages": [     {      "capture_method": "{string}",      "media": {       "created": "2021-06-11T11:39:24Z",       "last_updated": "2021-06-11T11:39:24Z",       "id": "{uuid}",       "type": "{string}"      },      "frames": [       {        "media": {         "created": "2021-06-11T11:39:24Z",         "last_updated": "2021-06-11T11:39:24Z",         "id": "{uuid}",         "type": "{string}"        }       }      ]     }    ],    "document_fields": {     "media": {      "created": "2021-06-11T11:39:24Z",      "last_updated": "2021-06-11T11:39:24Z",      "id": "{uuid}",      "type": "{string}"     }    },    "tasks": [     {      "id": "{uuid}",      "state": "{string}",      "created": "2021-06-11T11:39:24Z",      "last_updated": "2021-06-11T11:39:24Z",      "generated_media": [       {        "id": "{uuid}",        "type": "{string}"       }      ],      "generated_checks": [       {        "id": "{uuid}",        "type": "{string}"       }      ],      "type": "SUPPLEMENTARY_DOCUMENT_TEXT_DATA_EXTRACTION"     }    ]   }  ],  "liveness_capture": [   {    "id": "{uuid}",    "source": {     "type": "{string}"    },    "liveness_type": "ZOOM",    "facemap": {     "media": {      "created": "2021-06-11T11:39:24Z",      "last_updated": "2021-06-11T11:39:24Z",      "id": "{uuid}",      "type": "{string}"     }    },    "frames": [     {      "media": {       "created": "2021-06-11T11:39:24Z",       "last_updated": "2021-06-11T11:39:24Z",       "id": "{uuid}",       "type": "{string}"      }     }    ],    "tasks": []   }  ],  "face_capture": [   {    "id": "{uuid}",    "source": {     "type": "{string}"    },    "image": {     "media": {      "created": "2021-06-11T11:39:24Z",      "last_updated": "2021-06-11T11:39:24Z",      "id": "{uuid}",      "type": "{string}"     }    },    "tasks": []   }  ] }, "checks": [  {} ]}
Copy

Delete the session and everything associated with it

Auth

Path Params

sessionId string

Query String

sdkId string

DELETE /sessions/{sessionId}

 
curl --request DELETE \ --url 'https://www.example.com//sessions/{sessionId}' \ --header 'X-Yoti-Auth-Token: {X-Yoti-Auth-Token}' \ --data sdkId={sdkId}
Copy

Responses application/json

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
nonce	string
timestamp	string

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

 
curl --get \ --url 'https://www.example.com//sessions/{sessionId}/media/{mediaId}/content' \ --header 'X-Yoti-Device-Meta: {X-Yoti-Device-Meta}' \ --header 'X-Yoti-Auth-Token: {X-Yoti-Auth-Token}' \ --data sdkId={sdkId} \ --data nonce={nonce} \ --data timestamp={timestamp}
Copy

Responses application/json

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
nonce	string
timestamp	string

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

 
curl --request DELETE \ --url 'https://www.example.com//sessions/{sessionId}/media/{mediaId}/content' \ --header 'X-Yoti-Device-Meta: {X-Yoti-Device-Meta}' \ --header 'X-Yoti-Auth-Token: {X-Yoti-Auth-Token}' \ --data sdkId={sdkId} \ --data nonce={nonce} \ --data timestamp={timestamp}
Copy

Responses application/json

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

Client Endpoints

Endpoints for the Web/Native Clients

PUT

/sessions/{sessionId}/resources/face-capture/{resourceId}/image

DELETE

/sessions/{sessionId}/client-session-token

Upload FaceCapture image

Provides image media for FaceCapture resource. This endpoint supports image/jpq & image/png Content-Type values.

Please note that the binary content part of the request payload MUST specify the filename parameter in the Content-Disposition e.g.

Content-Disposition: form-data; name="binary-content"; filename="example.png"

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
resourceId	string

Form Data

binary-content file

PUT /sessions/{sessionId}/resources/face-capture/{resourceId}/image

 
curl --request PUT \ --url 'https://www.example.com//sessions/{sessionId}/resources/face-capture/{resourceId}/image' \ --header 'X-Yoti-Device-Meta: {X-Yoti-Device-Meta}' \ --header 'X-Yoti-Auth-Token: {X-Yoti-Auth-Token}' \ --form 'binary-content=@{binary-content}'
Copy

Responses application/json

200

OK, image updated

No response body

400

Bad Request

401

Unauthorised request (wrong or missing token)

403

Forbidden

404

Session, Resource or Task id not found

409

Token is expired or resource is locked

415

Unsupported content type

422

Unprocessable Media

503

The service is unavailable

Response

 
No response
Copy

Trigger checks

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

DELETE /sessions/{sessionId}/client-session-token

 
curl --request DELETE \ --url 'https://www.example.com//sessions/{sessionId}/client-session-token' \ --header 'X-Yoti-Device-Meta: {X-Yoti-Device-Meta}' \ --header 'X-Yoti-Auth-Token: {X-Yoti-Auth-Token}'
Copy

Responses application/json

204

Success (the client session token is deleted)

No response body

400

Bad Request (missing header value)

401

Unauthorised request (wrong or missing token)

403

Forbidden

404

Session Not Found

409

Token expired or incomplete resources

503

The service is unavailable

Response

 
No response
Copy