Create a session

AI Tools

To use Age estimation with Headless Age verification service (AVS), you will first need to create a session with age_estimation method enabled.

POST https://age.yoti.com/api/v1/sessions

Header	Description
Authorization	API Key for the Yoti Age Verification API. Should be sent as `Bearer {{API_TOKEN}}` .
Content-Type	application/json
Yoti-SDK-Id	Your unique Yoti-Sdk-Id (uuid)

The age verification API uses an HTTP authentication scheme called ‘bearer authentication’. This involves security tokens called ‘bearer tokens’. They are the predominant type of access token used with OAuth 2.0. A resource should interpret a bearer token as "Give the bearer of this token access". The client must send this token in the Authorization header when making requests to protected resources.

It is important that your API Key remains strictly confidential. It must be stored securely. We advise that you never commit any code containing your API Key, and never share it beyond the authorised party.

If you believe your API key has been compromised, please generate new API keys in the hub asap.

Request Body

{ "type": "OVER", "age_estimation": { "allowed": true, "threshold": 21, "level": "PASSIVE" }, "ttl": 900, "reference_id": "over_21_example", "notification_url": "https://yourdomain.example/webhook", "callback": { "auto": false, "url": "https://www.example.com" } }

Parameter	Type	Value	Description
allowed	boolean	`TRUE`/ `FALSE`	Enable the age estimation method for the user to use.
threshold	integer	e.g. `21`	Age threshold for under/over age limits. We recommend that this threshold be more than the age you want to set as your barrier to entry.
level	string	`PASSIVE`	The level of anti-spoofing for each age verification method. `PASSIVE` enables a passive liveness test for age estimation.
type	type	`OVER`/ `UNDER`/`AGE`	`OVER` - If the user is OVER the age threshold (e.g., over 21). `UNDER` - If the user is UNDER an age threshold (e.g., under 21). `AGE` - This will return the estimated AGE of the user (e.g, if the user is estimated to be 25, we will return 25).
ttl	string (in seconds)	e.g. 900	Configure how long the session is valid for. The user will need to complete this before the `ttl` expires. Minimum value: `60` (1 minute) Maximum value: `2592000` (1 month)

Response

If the request is successful and a session is generated, the API will send a response in the form:

{ "id": "uuid", "status": "PENDING", "expires_at": "2025-08-08T23:41:39Z" }

Below are the different statuses Yoti returns:

Status	Explanation
PENDING	User has not started any checks.
IN_PROGRESS	Checks have begun on the session, awaiting the result to be returned.
FAIL	The session has been completed, and the user has failed to meet the age threshold. FAIL will be returned only for `OVER` and `UNDER` attempts.
COMPLETE	The session has been completed, the user has passed the required threshold, or an age has been returned. Always `COMPLETE` if AGE type is configured.
ERROR	We could not provide an age result or calculate the threshold. This may be because the face was not recognised during age estimation, or if the ID document was processed via Doc Scan, but we do not believe that it is a genuine document.
CANCELLED	The user no longer wishes to prove their age and aborts the session.
EXPIRED	The session has expired and is no longer usable.

Error Codes

Error code	Description
201	Success
400	Missing field(s) in the request body
401	Missing or unknown SDK ID
403	Incorrect API key
409	Verification check already in progress
410	Session has already expired for the current check

Last updated on

Was this page helpful?