Create a session

Authorization

API Key to call the Yoti Age API. Should be sent as a Bearer {{API_KEY}}.

Content-Type

application/json

Yoti-SDK-Id

Your unique Yoti-Sdk-Id (UUID), obtained from the Yoti Hub

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.)

reference_id

string

(optional) Reference ID is a string. Yoti returns this same string in the session result.

Note: We recommend that you do not include any personal information in this string.

✅ (optional)

ttl

seconds

(required) The time 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.

✅ (required)

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"}``

Enabling the synchronous_checks parameter will hold the user in the Yoti AVS flow and only redirect once results have finished processing. The Session ID will be appended as a query parameter.

✅ (Only required if not configured in the template)

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

✅ (Only required if not configured in the template)

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.

✅ (Only required if not configured in the template)

block_biometric_consent

true/false

In several US states (currently Texas, Illinois, and Washington), the law mandates that you obtain the user’s specific consent to collect their biometric details for our liveness or face-matching feature to be compliant with US legislation.

For any other countries or states within countries. If you choose only to 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 from accessing the Yoti service without prior giving specific consent.

Setting to true bypasses this screen. We recommend keeping this value to the 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.

✅ (Only required if not configured in the template)

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 attempts a user is allowed in each method.

template_id

string

A template ID (UUID) obtained by a previous template creation. If provided, only the checked parameters in the next column are required.

✅ (required)

id

Session ID (UUID). Please share this session ID with us if you raise a support request regarding session issues.

expires_at

The time at which the session will expire.

status

Status of the session. PENDING will be returned upon successful session creation.

200

Success

400

Missing field in post body

401

Missing or unknown SDK ID

403

Incorrect API key