Create a session
Welcome to the developer documentation for integrating with Age verification. The integrations steps are as follows:
- Create a session
- Launch the user view
- Retrieve results
To begin using the age verification service a session must first be created. This is done by making a post request to the sessions endpoint.
POST https://age.yoti.com/api/v1/sessions| Header | Description |
|---|---|
| Authorization | API Key to call the Yoti Age API. Should be sent as a '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.
Here you will provide which authentication method you would like, the allowed age threshold and your client preferences.
Full example
{ "type": "OVER", "age_estimation": { "allowed": true, "threshold": 21, "level": "PASSIVE", "retry_limit": 1 }, "digital_id": { "allowed": true, "threshold": 18, "age_estimation_allowed": true, "age_estimation_threshold": 21, "level": "NONE", "retry_limit": 1 }, "doc_scan": { "allowed": true, "threshold": 18, "authenticity": "AUTO", "level": "PASSIVE", "retry_limit": 1 }, "credit_card": { "allowed": false, "threshold": 18, "level": "NONE", "retry_limit": 1 }, "mobile": { "allowed": false, "level": "NONE", "retry_limit": 1 }, "ttl": 900, "reference_id": "over_18_example", "callback": { "auto": true, "url": "https://www.yoti.com" }, "notification_url": "https://yourdomain.example/webhook", "cancel_url": "https://www.yoti.com", "retry_enabled": false, "resume_enabled": false, "synchronous_checks": true}Type parameter
This is where you define what preference you want to set for the age of the user.
| Parameter | Description |
|---|---|
| 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 30. |
| AGE | This will return the estimated AGE of the user e.g if the user is estimated to be 25, we will return 25. |
Configuration parameter
| Parameter | Type / Value | Description |
|---|---|---|
| reference_id | string | Reference ID is an optional string. Yoti returns this same string in the session result. |
| ttl | seconds | How long the session is valid for, the user will need to complete it before the ttl expires. This must be at least 60 seconds (1 minute). And can't be longer than 1 month. |
| callback | object | The URL to redirect your user to after they complete age verification. The Example - { "auto": true, "url": "https://www.example.com" } |
| callback_url | string | Shorthand for specifying the URL where your user is redirected after age verification. By default, Example - https://www.example.com |
| notification_url | https://example.com/updates | The URL where the results of an age verification should be sent. This endpoint must use HTTPS and accept POST requests for notifications. |
| block_biometric_consent | true / false | For several American states (currently Texas, Illinois and Washington US states*), the law mandates that you must collect the user’s specific consent to collect their biometric details for our liveness or face matching feature to be compliant with the US legislation. *and any other countries or states within countries If you choose to only request specific consent in the above "territories" you must provide details of the effective geo location software you use to prevent any individuals located in one of these territories accessing the Yoti service without prior giving specific consent. Setting to true bypasses this screen. We recommend keeping this value to default (false) to enable consent for all users. |
| cancel_url | https://yourdomain.example | You can specify a cancel URL, if the user opens AVS and decides that they don't want to continue then they can be taken to a specific place rather than going back in the browser. If you would like to see how this looks please head over here. |
| retry_enabled | true / false | You can give the user the ability to retry verifying their age if an attempt fails. Webhooks are sent for each age verification attempt, so some could show up as "FAIL" even if the user eventually passes. |
| resume_enabled | true / false | Allows the user to resume a session (if the link is re-accessed). The user can be re sent the link if for instance the IDV session fails, so that they can retry. |
| rule_id | string | Allows an age token rule ID to be specified. If a user has previously passed a Yoti age verification and did so by meeting the age threshold configured in your rule, the user will automatically redirect to the callback. To create an age token rule, see Reusable checks (Yoti keys) The login method must be enabled for this to take affect. |
| synchronous_checks | true / false | If set to true, ensures that all methods have a result ready before the user is redirected to the callback URL. Default is false, this primarily affects document checks and credit card checks as these are async. |
retry_enabled" and/or "resume_enabled" are set as true.
Example 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"}Error Codes
| Response code | Description |
|---|---|
| 200 | Success |
| 400 | Missing field in post body |
| 401 | Missing or unknown SDK ID |
| 403 | Incorrect API key |