The integration steps are as follows:
- Create a session
- Enable your methods
- Launch the user view
- Retrieve results
First, you will need to create a session. 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.
Next you will provide which method you would like to enable, the allowed age threshold and your client preferences.
Example code snippet
Below is an example of the top three methods integrators use:
{ "type": "OVER", "ttl": 900, "age_estimation": { "allowed": true, "threshold": 21, "level": "PASSIVE", "retry_limit": 1 //number of total attempts for this method }, "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 }, "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
Here is the detail needed for the parameters for the full create session object.
| 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 the session before the ttl expires. This must be at least 60 seconds (1 minute). And cannot 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 | This allows the user to resume a session (if the link is re-accessed). The user can be resent the link if, for instance, the doc_scan session fails, so that they can retry. |
| rule_id | string | This allows an age token rule ID to be specified. If a user has previously passed a session and did so by meeting the age threshold configured in your rule, the user will automatically redirect to the callback. You will need to enable Reusable checks for this. The login method must be enabled for this to take effect. |
| 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_limit | integer | The total number of tries that a user will be allowed to attempt each method |
User Retry
If, for some reason, the user is on the boundary of an age check threshold, you may want the user to retry.
You can enable retries and give your users another chance to pass an age check. You can set parameters at the session and method levels.
Session Retry
You will need to set:
"retry_enabled": true, "resume_enabled": true, "synchronous_checks": trueMethod Retry
You will need to specify the number of retries that are allowed for each method individually, e.g. 2 attempts for Age Estimation, 1 try for Identity Verification, and 1 try for Digital ID.
"retry_limit": 1 // | 2 | 3...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"}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 useable |
Error Codes
Below are the error codes when creating a session.
| Response code | Description |
|---|---|
| 200 | Success |
| 400 | Missing field in post body |
| 401 | Missing or unknown SDK ID |
| 403 | Incorrect API key |