Connect API Documentation

This API is documented in OpenAPI v3.1 format and displayed with ReDoc.

In addition to standard OpenAPI syntax few vendor extensions have been used.

Server

https://api.yoti.com

prod

Authentication

The system uses API tokens which may either be acquired through an OAuth-compatible endpoint (using a JWT signed by the application's private key), or manually provisioned through Hub or Backoffice.

A simplified example of a request would look like:

POST /path/to/resource HTTP/2.0
Host: api.yoti.com
Authorisation: Bearer yta_UJCxUATErS890kAUaOMI7QA_IdESeScy2WKH

{ ... JSON request data here ... }

Fields

Key	In
Authorization	Header

Poa-v1

Endpoints for Proof of Age (PoA)

Verify Proof of Age

Auth

Request Body

Proof of Age Query	object
qr	object	Information/Metadata linked to the scanned QR code
value	string	The value of the scanned QR code
scanned_at	date-time	When the QR code was scanned by the reader
terminal	object	Information/Metadata linked to the terminal that scanned the QR code
id	string	An identifier for the terminal that is used to scan the QR code
store_id	string	An identifier for the location/unit to which the `id` is registered or is operating under
notification	object	Define where to send the proof of age verification result notificatio for use-cases where the workflow is not synchronous (i.e. response status code is 202 Accepted)
url	string	Where to send the notification
method	string	The HTTP method to use when sending the notification Enum: `GET`,`POST` Default: POST
verifyTls	boolean	Whether to verify the TLS certificate of the server exposing the `url` Default: true
headers	object	Pre-defined set of HTTP headers to include with the notification
*	string	Each key/value entry is an HTTP header name and it's corresponding value

POST /poa/v1/verify

xxxxxxxxxx
 
curl --request POST \ --url 'https://api.yoti.com/poa/v1/verify' \ --header 'Authorization: {Authorization}' \ --data '{  "qr": {    "value": "mDL:VGhlIGRldmljZSBlbmdhZ2VtZW50IGRhdGEgc3RydWN0dXJl",    "scanned_at": "2025-07-16T16:55:12Z"  },  "terminal": {    "id": "pos-1234957"  }}'
Copy

Responses

200

Proof of Age (Sync) Result	object
id	string	The identifier for the result (and query that originated it)
status	string	Whether the proof of age was done successfuly (`SUCCESS`) or not (`FAILURE`). If successful the validation info will be available under `result`. If proof of age failed, `failure` will include info as to why. Enum: `SUCCESS`,`FAILURE`
timestamp	date-time	When the `result` (or `failure`) was determined
provider	string	The name/identifier of the provider used to validate the proof of age Enum: `YOTI`,`GOV_UK`
result	object	Contains the result of the proof of age check (only present in case of a `SUCCESS` status)
age_over	int32	The highest age value that is below the user's age (e.g. a value of 21 means the user is 21+, a value of 15 means the user's age is 15+) minimum: 0
valid_for_alcohol	boolean	Whether the proof of age check complies with GPG45 requirements necessary for alcohol purchases
checks	array[string]	Enum: `PROVIDER_ON_DVS_REGISTER`,`SIGNATURE_VERIFIED`
failure	object	Contains data/info related to a failure
reason	string	Enum: `UNABLE_TO_VERIFY_SIGNATURE`,`PRESENTATION_EXPIRED`,`PRESENTATION_ALREADY_USED`,`UNSUPPORTED_PAYLOAD`,`EXCLUDED_PROVIDER`,`UNKNOWN_PROVIDER`,`USER_DID_NOT_CONSENT`

Expand

202

Accepted

400

Bad Request

422

Unprocessable Entry

500

Server Error

Response

xxxxxxxxxx
 
{ "id": "Yzt0sbVOSauDWPwMQvumjQ", "status": "SUCCESS", "timestamp": "2025-07-16T15:47:22Z", "provider": "GOV_UK", "result": {  "age_over": 21,  "valid_for_alcohol": true,  "checks": [   "SIGNATURE_VERIFIED",   "PROVIDER_ON_DVS_REGISTER"  ] }}
Copy

Verify Proof of Age Result

Auth

Path Params

string

The identifier for a proof of age verification query

GET /poa/v1/verify/{id}

xxxxxxxxxx
 
curl --get \ --url 'https://api.yoti.com/poa/v1/verify/%7Bid%7D' \ --header 'Authorization: {Authorization}'
Copy

Responses

200

Proof of Age Result	object
id	string	The identifier for the result (and the query that originated it)
status	string	Whether the proof of age was done successfuly (`SUCCESS`), is still pending (`PENDING`) or failed (`FAILURE`). If successful the validation info is available in `result`. If proof of age failed, `error` will include info as to why. Enum: `SUCCESS`,`FAILURE`,`PENDING`
timestamp	date-time	When the `result` (or `failure`) was determined.
provider	string	The name/identifier of the provider used to validate the proof of age Enum: `YOTI`,`GOV_UK`
result	object	Contains the result of the proof of age check (only present in case of a `SUCCESS` status)
age_over	int32	The highest age value that is below the user's age (e.g. a value of 21 means the user is 21+, but under 25, a value of 0 means the user's age is under 15) minimum: 0
valid_for_alcohol	boolean	Whether the proof of age check complies with GPG45 requirements necessary for alcohol purchases
checks	array[string]	Enum: `PROVIDER_ON_DVS_REGISTER`,`SIGNATURE_VERIFIED`
waiting_on	string	A code for the action/activity that needs to be completed for the proof of age process to progress Enum: `USER_CONSENT`
failure	object	Contains data/info related to a failure
reason	string	Enum: `UNABLE_TO_VERIFY_SIGNATURE`,`PRESENTATION_EXPIRED`,`PRESENTATION_ALREADY_USED`,`UNSUPPORTED_PAYLOAD`,`EXCLUDED_PROVIDER`,`UNKNOWN_PROVIDER`,`USER_DID_NOT_CONSENT`

Expand

404

Not Found

500

Server Error

Response

xxxxxxxxxx
 
{ "id": "Yzt0sbVOSauDWPwMQvumjQ", "status": "PENDING", "provider": "YOTI", "waiting_on": "USER_CONSENT"}
Copy