Title
Create new category
Edit page index title
Edit category
Edit link
Create a session
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 verification method to be available for the user to use. |
| threshold | integer | e.g. 21 | Age threshold for under/over age limits. We recommend for this threshold to be more than the age you want to set as your barrier to entry. |
| level | string | NONE/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 an 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 | 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 result to be returned. |
| FAIL | The session has been completed, however 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 in post body |
| 401 | Missing or unknown SDK ID |
| 403 | Incorrect API key |
Got a question? Contact us here.