Create a session

Before you start

You will need to have completed Onboarding and generated API keys.

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.

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

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

JSON
    
 
{    "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}
Copy

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.

Note: If the type parameter AGE is used, Yoti will return the detected Age value without doing a comparison against the threshold. It allows the integrator to utilise this value to perform comparison on their side against multiple thresholds.

Configuration parameter

Parameter	Type / Value	Description
reference_id	string	Reference ID is an optional string for your internal reference. Yoti does not use it, but returns this same string in the session result.
ttl	seconds	Required field for 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 cannot be longer than 1 month.
callback	object	The URL to redirect your user to after they complete age verification. The `sessionId` will be appended as a query parameter. Setting `auto` to `true` will automatically redirect users after verification. 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, `auto` is `false`, so users are not automatically redirected. 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_limit	integer	The total number of tries that a user will be allowed to attempt each method

Important We will charge for each individual verification check performed, this will apply to the retry attempts if "retry_enabled" and/or "resume_enabled" are set as true.

Allow users to try again

Some users look younger than their real age, e.g. an 18-year-old who looks 17 or a 20-year-old who looks 18. These users might fail the age estimation check even though they meet the legal age.

You can enable retries and give your users another chance to pass an age check. You will need to set some parameters at the session and method levels.

At the session level

You will need to set:

JSON
    
 
"retry_enabled": true,    "resume_enabled": true,    "synchronous_checks": true
Copy

At the method level

You will need to specify how many tries are allowed for each check individually, e.g. 2 tries for Age Estimation, 1 try for Identity Verification, and 1 try for Digital ID.

JSON
    
 
"retry_limit": 1 // | 2 | 3...
Copy

Example response

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

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

Error Codes

Response code	Description
200	Success
400	Missing field in post body
401	Missing or unknown SDK ID
403	Incorrect API key

Last updated on

Was this page helpful?