Proof of Age (PoA) API

This API is documented in OpenAPI v3.1 format. In addition to standard OpenAPI syntax few vendor extensions have been used.

Early Preview - Coming Soon!

NOTICE: This is still a DRAFT API Spec and subject to changes before going live.

Server

https://api.yoti.com

prod

Authentication

apiKey RSA-Signed-Request

The digest is obtained by computing the SHA-256 digest of the request data arranged like so:

{method}&{path}?{query}&nonce=${nonce}&timestamp=${timestamp}&{base64(body)}

If the request doesn't have any one particular element (e.g. no request body) then it is omitted, (including the preceding &).
A request with no query part would be {method}&{path}?nonce=${nonce}&timestamp=${timestamp}&{base64(body)}

Depending on the endpoint, some of the initial path segments must be dropped from the message (see this endpoint RSA Signed Requests note).

The signature is then obtained by signing the digest with the application RSA private key (using PKCS#1 v1.5).

The value of the header is the base64 encoded signature.

Responses

401 Unauthorized

Response Schema: application/json

id	string	The request ID
status	integer <int32>	The HTTP status code
error	string [A-Z_]+	The (application level) error code
message	string	Human-readable error message

The possible error codes and their meaning:

`INVALID_APP_ID`	The application with the specified ID does not exist
`INVALID_DIGEST`	The request signature is not valid
`MISSING_APP_ID`	The application ID was not included in the request
`MISSING_DIGEST`	The `X-Yoti-Auth-Digest` header was not included in the request
`MISSING_NONCE`	The `nonce` query parameter was not included in the request
`MISSING_TIMESTAMP`	The `timestamp` query parameter was not included in the request

403 Forbidden

Response Schema: application/json

id	string	The request ID
status	integer <int32>	The HTTP status code
error	string [A-Z_]+	The (application level) error code
message	string	Human-readable error message

The possible error codes and their meaning:

`DISABLED_APP`	The application is disabled
`SUSPENDED_ORG`	The organisation to which the application belongs is suspended

Fields

Key	In
X-Yoti-Auth-Digest	Header

apiKey App-ID-Query

The SDK (a.k.a App) ID

Fields

Key	In
appId	Query

apiKey App-ID-Header

The SDK (a.k.a App) ID

Fields

Key	In
X-Yoti-Auth-Id	Header

apiKey Bearer-Token

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

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"  ] }}
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	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`
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

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

POST poa-verify-result

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