Proof of Age (PoA) API

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.

NOTICE: This is still a DRAFT and can be subject to changes before going live.

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.

A simplified example of a request would look like:

POST /path/to/resource HTTP/2.0
Host: api.yoti.com
Authorization: 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
providers	object	Restrict the providers that can be used to perform the check
filter	string	Whether the list of providers lists alllowed or disallowed providers that can be used to do the check Enum: `ALLOWED`,`DISALLOWED`
names	array[string]	Enum: `YOTI`,`GOV_UK`,`A_PROVIDER_NAME`
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

Expand

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`,`A_PROVIDER_NAME`
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
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`

202

Accepted

400

Bad Request

500

Server Error

Response

xxxxxxxxxx
 
{ "id": "Yzt0sbVOSauDWPwMQvumjQ", "status": "SUCCESS", "timestamp": "2025-07-16T15:47:22Z", "provider": "GOV_UK", "result": {  "age_over": 21,  "checks": [   "SIGNATURE_VERIFIED"  ] }}
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 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`,`A_PROVIDER_NAME`
result	object	Contains the result of the proof of age check (only present in case of a `SUCCESS` status)
age_over	int32	minimum: 0
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`

404

Not Found

500

Server Error

Response

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

Webhooks

POST

poa-verify-result

Verify Proof of Age Result Notification

This notification will be triggered when the result for Verify Proof of Age is available and the original request included a notification config

Request Body

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`,`A_PROVIDER_NAME`
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
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`

POST poa-verify-result

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

Responses

204

No Content

Your server implementation should return this HTTP status code if the data was received successfully (although any 2xx code will do)

No response body

Response

xxxxxxxxxx
 
No response
Copy