Yoti Age Verification 1.0

To begin using the Age Verification Service, a session must first be created. The session ID from the Yoti session create response will be used to construct the user view URL. Result of the session can then be retrieved from webhook or the Get Session Result API.

Server

https://age.yoti.com

Age Verification Service

Authentication

http BearerAuth

Bearer token authorization using API Key obtained from the Yoti Hub as token

Session Configuration

POST

/api/v1/sessions

GET

/api/v1/sessions/{sessionId}

Session creation

Create a session that can be used by a consumer, when a session is created, a reference ID can be provided to help you identify your customers.

Auth

Headers

Content-Type

string

Define the expected payload content type (always application/json).

Yoti-Sdk-Id

string

SDK ID obtained from the Yoti Hub

pattern: [a-zA-Z0-9\_\-]{14,40}

Request Body

This payload will generate a session configuration object

object	object
type	string	Session type Enum: `AGE`,`OVER`,`UNDER` Default: OVER
age_estimation6 fields	object
allowed	boolean	Flag indicating whether this method is allowed Default: true
threshold	integer	The age of interest multipleOf: 1 maximum: 100 minimum: 6
retry_enabled	boolean	Flag indicating whether retry is allowed for this method Default: false
retry_limit	integer	Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1
level	string	Enum: `PASSIVE` Default: PASSIVE
authenticity	string	Enum: `AUTO` Default: AUTO
digital_id6 fields	object
allowed	boolean	Flag indicating whether this method is allowed Default: true
threshold	integer	Configure the age verification threshold for this check.
age_estimation_allowed	boolean	Allows the Estimated age attribute to be used for the check.
age_estimation_threshold	integer	Configure the age estimation threshold for this check. Must be above the 'threshold' value with an allowed difference between 1 and 20.
retry_enabled	boolean	Flag indicating whether retry is allowed for this method Default: false
retry_limit	integer	Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1
doc_scan9 fields	object
allowed	boolean	Flag indicating whether this method is allowed Default: true
threshold	integer	The age of interest multipleOf: 1 maximum: 100 minimum: 6
retry_enabled	boolean	Flag indicating whether retry is allowed for this method Default: false
retry_limit	integer	Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1
level	string	Enum: `PASSIVE` Default: PASSIVE
authenticity	string	Enum: `AUTO` Default: AUTO
preset_issuing_country	string	default country (ISO code) to use as default country when selecting document issuing country
disable_mobile_hand_off	boolean	set to true, if the user should not be offered a chance to move verification from a desktop to a mobile device.
synchronous_checks	boolean	If set to true, ensures that all methods have a result ready before the user is redirected to the callback URL. Default: false, which primarily affects document checks and credit card checks as these methods are asynchronous. Enum: `true`,`false` Default: false
credit_card	object
allowed	boolean	Flag indicating the verification method is allowed Default: true
mobile	object
allowed	boolean	Flag indicating the verification method is allowed Default: true
yoti_key	object
allowed	boolean	Flag indicating the verification method is allowed Default: true
authentication	boolean	when authentication is set to true, users are required to use their Yoti key before they can complete the session with an age token
electronic_id5 fields	object
allowed	boolean	Flag indicating whether this method is allowed Default: true
threshold	integer	The age of interest multipleOf: 1 maximum: 100 minimum: 6
retry_enabled	boolean	Flag indicating that the verification retry allowed for session Default: true
retry_limit	integer	Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1
sub_methods	array[string]	Enum: `MIT_ID`,`SWEDISH_BANK_ID`,`FTN`
la_wallet4 fields	object
allowed	boolean	Flag indicating whether this method is allowed Default: true
threshold	integer	Configure the age verification threshold for this check.
retry_enabled	boolean	Flag indicating whether retry is allowed for this method Default: false
retry_limit	integer	Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1
social_security_number4 fields	object
allowed	boolean	Flag indicating whether this method is allowed Default: true
threshold	integer	Configure the age verification threshold for this check.
retry_enabled	boolean	Flag indicating whether retry is allowed for this method Default: false
retry_limit	integer	Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1
us_florida_hb34 fields	object
allowed	boolean	Flag indicating whether this method is allowed Default: true
threshold	integer	Configure the age verification threshold for this check.
retry_enabled	boolean	Flag indicating whether retry is allowed for this method Default: false
retry_limit	integer	Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1
email	object
allowed	boolean	Flag indicating the verification method is allowed Default: true
singpass4 fields	object
allowed	boolean	Flag indicating whether this method is allowed Default: true
threshold	integer	Configure the age verification threshold for this check.
retry_enabled	boolean	Flag indicating whether retry is allowed for this method Default: false
retry_limit	integer	Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1
cpf4 fields	object
allowed	boolean	Flag indicating whether this method is allowed Default: true
threshold	integer	Configure the age verification threshold for this check.
retry_enabled	boolean	Flag indicating whether retry is allowed for this method Default: false
retry_limit	integer	Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1
ttl	integer	Define how long the session is valid for. The user will need to complete the session before the ttl expires. multipleOf: 1 maximum: 2592000 minimum: 60
reference_id	string	Reference ID is an optional string. Yoti returns this same string in the session result. We recommend that you do not include any personal information in this string.
callback	object	Callback object to describe where and how a user's experienced should be managed after they have submitted age verification evidence
url	string	The URL to redirect your user to after they complete age verification. The sessionId will be appended as a query parameter.
auto	boolean	Setting auto to true will automatically redirect users after verification.
notification_url	string	A https endpoint to call after a final result has been generated. This will be a post message containing the result and referenced_id pattern: `^https:.*`
block_biometric_consent	boolean	Determine if the UI should block the display of a biometric required flow Default: false
rule_id	string	The id in of the rule the age token must satisfy. Should be a uuid. pattern: `^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`
cancel_url	string	URL where end users get redirected when they decide to cancel current AVS session
privacy_policy	string	URL for privacy policy
terms_and_conditions	string	URL for terms and conditions
retry_enabled	boolean	Ability for the user to retry verifying their age if an attempt fails Default: false
resume_enabled	boolean	Should a user be allowed to retry after a fail / error status Default: false
blocked_locations	array[string]	A list of locations that have been blocked for access
target_origin_url	string	A http url that specifies the i-frame parent in order to dispatch status update event pattern: `^http[s]?:.*`
synchronous_checks	boolean	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. Default: false
account_id	string	An identifier external to age.yoti.com that allows a client to distiniguish between different accounts under the same sdk id maxLength: 100
double_blind	boolean	Apply a secondary anonymisation step using Digital ID/Yoti Key Default: false

POST /api/v1/sessions

curl --request POST \

--url 'https://age.yoti.com/api/v1/sessions' \

--header 'Content-Type: application/json' \

--header 'Yoti-Sdk-Id: e8468a54-a655-47ed-92d5-ef00dcba0ac3' \

--header 'Authorization: Bearer {token}' \

--data '{

"type": "{string}",

"age_estimation": {

"allowed": true,

"threshold": 21,

"retry_enabled": false,

"retry_limit": 2,

"level": "PASSIVE",

"authenticity": "AUTO"

"digital_id": {

"allowed": true,

"threshold": 18,

"age_estimation_allowed": true,

"age_estimation_threshold": 21,

"retry_enabled": false,

"retry_limit": 2

"doc_scan": {

"allowed": true,

"threshold": 18,

"retry_enabled": false,

"retry_limit": 2,

"level": "PASSIVE",

"authenticity": "AUTO",

"preset_issuing_country": "GBR",

"disable_mobile_hand_off": false,

"synchronous_checks": false

"credit_card": {

"allowed": true

"mobile": {

"allowed": true

"yoti_key": {

"allowed": true,

"authentication": true

"electronic_id": {

"allowed": true,

"threshold": 18,

"retry_enabled": true,

"retry_limit": 2,

"sub_methods": [

"MIT_ID",

"SWEDISH_BANK_ID",

"FTN"

]

"la_wallet": {

"allowed": true,

"threshold": 21,

"retry_enabled": false,

"retry_limit": 2

"social_security_number": {

"allowed": true,

"threshold": 21,

"retry_enabled": false,

"retry_limit": 2

"us_florida_hb3": {

"allowed": true,

"threshold": 21,

"retry_enabled": false,

"retry_limit": 2

"email": {

"allowed": true

"singpass": {

"allowed": true,

"threshold": 21,

"retry_enabled": false,

"retry_limit": 2

"cpf": {

"allowed": true,

"threshold": 21,

"retry_enabled": false,

"retry_limit": 2

"ttl": 900,

"reference_id": "{string}",

"callback": {

"url": "https://yoti.com/success",

"auto": true

"notification_url": "https://notification-web-hook.yoti.com",

"block_biometric_consent": false,

"rule_id": "d1234a54-a655-47ed-92d5-ef00dcba0ac3",

"cancel_url": "https://yoti.com/cancel",

"privacy_policy": "https://www.yoti.com/privacy/",

"terms_and_conditions": "https://www.yoti.com/terms/",

"retry_enabled": false,

"resume_enabled": false,

"blocked_locations": [

"GBR",

"DEU"

"target_origin_url": "{string}",

"synchronous_checks": false,

"account_id": "{string}",

"double_blind": false

Copy

Responses

200

object	object	Response from a session creation request
id	string	Auto-generated
expires_at	date-time	Session expiry time

400

Bad request - missing field, spoofing attempt detected, invalid validation methods, need to re-verify

401

Missing or unknown Yoti-Sdk-Id

403

Not allowed to use this session

Response

{

"id": "d1234a54-a655-47ed-92d5-ef00dcba0ac3",

"expires_at": "2026-05-02T11:53:33Z"

}

Copy

Session retrieval

Retrieve the configuration setup for a session.

Auth

Headers

Yoti-Sdk-Id

string

SDK ID obtained from the Yoti Hub

pattern: [a-zA-Z0-9\_\-]{14,40}

Path Params

sessionId

string

The consumer's session id, created by the Yoti server.

pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

GET /api/v1/sessions/{sessionId}

curl --get \

--url 'https://age.yoti.com/api/v1/sessions/def6fd14-dba9-4610-b6c3-9a7e8909aac0' \

--header 'Yoti-Sdk-Id: e8468a54-a655-47ed-92d5-ef00dcba0ac3' \

--header 'Authorization: Bearer {token}'

Copy

Responses

200

Session retrieved for client consumption

object	object
id	string	Session ID created by Yoti server
sdk_id	string	SDK ID obtained from the Yoti Hub
callback	object	Callback object to describe how a user's experience should be managed after they have submitted age verification evidence
auto	boolean	Setting auto to true will automatically redirect users after verification.
type	string	Session type Enum: `AGE`,`OVER`,`UNDER` Default: OVER
status	string	only sessions with a status of PENDING and which are not expired are returned at the moment Enum: `PENDING`,`COMPLETE`,`PROCESSING`,`ERROR`,`FAIL`,`CANCELLED`,`IN_PROGRESS`
expires_at	date-time	Session expiry time
biometric_consent_required	boolean	Determine whether the Biometric Consent Screen is enabled Default: true
retry_enabled	boolean	Ability for the user to retry verifying their age if an attempt fails Default: false
resume_enabled	boolean	This allows the user to resume a session (if the link is re-accessed). Default: false
notification_url	string	A https endpoint to call after a final result has been generated. This will be a post message containing the result and reference_id pattern: `^https:.*`
cancel_url	string	URL where end users get redirected when they decide to cancel current AVS session
reference_id	string	Reference ID is an optional string. Yoti returns this same string in the session result. We recommend that you do not include any personal information in this string.
created_at	date-time	Session creation time
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. pattern: `^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`
blocked_locations	array[string]	A list of locations that have been blocked for access
updated_at	date-time	Session update time
biometric_consent_given_at	date-time	The time when the biometric consent was given
target_origin_url	string	A http url that specifies the i-frame parent in order to dispatch status update event pattern: `^http[s]?:.*`
synchronous_checks	boolean	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. Default: false
double_blind	boolean	Apply a secondary anonymisation step using Digital ID/Yoti Key Default: false

404

Session not found

410

Session has expired for current check or invalid status

Response

{

"id": "e3746a54-a655-47ed-92d5-ef00dcba0ac3",

"sdk_id": "d2233a54-a655-47ed-92d5-ef00dcba0ac3",

"callback": {

"auto": true

"type": "OVER",

"status": "PENDING",

"expires_at": "2026-05-02T11:53:33Z",

"biometric_consent_required": true,

"retry_enabled": false,

"resume_enabled": false,

"notification_url": "https://notification-web-hook.yoti.com",

"cancel_url": "https://yoti.com/cancel",

"reference_id": "user001",

"created_at": "2026-05-02T11:53:33Z",

"rule_id": "d1234a54-a655-47ed-92d5-ef00dcba0ac3",

"blocked_locations": [

"GBR",

"DEU"

"updated_at": "2026-05-02T11:53:33Z",

"biometric_consent_given_at": "2026-05-02T11:53:33Z",

"target_origin_url": "{string}",

"synchronous_checks": false,

"double_blind": false

}

Copy

Session Results

GET

/api/v1/sessions/{sessionId}/result

Get the session result

Auth

Headers

Yoti-Sdk-Id

string

SDK ID obtained from the Yoti Hub

pattern: [a-zA-Z0-9\_\-]{14,40}

Path Params

sessionId

string

The consumer's session id, created by the Yoti server.

pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

GET /api/v1/sessions/{sessionId}/result

curl --get \

--url 'https://age.yoti.com/api/v1/sessions/def6fd14-dba9-4610-b6c3-9a7e8909aac0/result' \

--header 'Yoti-Sdk-Id: e8468a54-a655-47ed-92d5-ef00dcba0ac3' \

--header 'Authorization: Bearer {token}'

Copy

Responses

200

Session retrieved for relying party consumption

object	object
id	string	Session ID created by Yoti server
sdk_id	string	SDK ID obtained from the Yoti Hub
callback	object	Callback object to describe how a user's experience should be managed after they have submitted age verification evidence
auto	boolean	Setting auto to true will automatically redirect users after verification.
type	string	Session type Enum: `AGE`,`OVER`,`UNDER` Default: OVER
status	string	only sessions with a status of PENDING and which are not expired are returned at the moment Enum: `PENDING`,`COMPLETE`,`PROCESSING`,`ERROR`,`FAIL`,`CANCELLED`,`IN_PROGRESS`
expires_at	date-time	Session expiry time
biometric_consent_required	boolean	Determine whether the Biometric Consent Screen is enabled Default: true
retry_enabled	boolean	Ability for the user to retry verifying their age if an attempt fails Default: false
resume_enabled	boolean	This allows the user to resume a session (if the link is re-accessed). Default: false
notification_url	string	A https endpoint to call after a final result has been generated. This will be a post message containing the result and reference_id pattern: `^https:.*`
cancel_url	string	URL where end users get redirected when they decide to cancel current AVS session
reference_id	string	Reference ID is an optional string. Yoti returns this same string in the session result. We recommend that you do not include any personal information in this string.
created_at	date-time	Session creation time
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. pattern: `^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`
blocked_locations	array[string]	A list of locations that have been blocked for access
updated_at	date-time	Session update time
biometric_consent_given_at	date-time	The time when the biometric consent was given
target_origin_url	string	A http url that specifies the i-frame parent in order to dispatch status update event pattern: `^http[s]?:.*`
synchronous_checks	boolean	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. Default: false
double_blind	boolean	Apply a secondary anonymisation step using Digital ID/Yoti Key Default: false

401

Missing or unknown Yoti-Sdk-Id

404

Session not found

Response

{

"id": "e3746a54-a655-47ed-92d5-ef00dcba0ac3",

"sdk_id": "d2233a54-a655-47ed-92d5-ef00dcba0ac3",

"callback": {

"auto": true

"type": "OVER",

"status": "PENDING",

"expires_at": "2026-05-02T11:53:33Z",

"biometric_consent_required": true,

"retry_enabled": false,

"resume_enabled": false,

"notification_url": "https://notification-web-hook.yoti.com",

"cancel_url": "https://yoti.com/cancel",

"reference_id": "user001",

"created_at": "2026-05-02T11:53:33Z",

"rule_id": "d1234a54-a655-47ed-92d5-ef00dcba0ac3",

"blocked_locations": [

"GBR",

"DEU"

"updated_at": "2026-05-02T11:53:33Z",

"biometric_consent_given_at": "2026-05-02T11:53:33Z",

"target_origin_url": "{string}",

"synchronous_checks": false,

"double_blind": false

}

Copy