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.
Session Configuration
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.
| Content | string | Define the expected payload content type (always application/json). | |
| Yoti | string | SDK ID obtained from the Yoti Hub pattern: |
This payload will generate a session configuration object
| object | object | ||
| type | string | Session type Enum: Default: OVER | |
| age | object | ||
| allowed | boolean | Flag indicating whether this method is allowed Default: true | |
| threshold | integer | Configure the age verification threshold for this check. | |
| retry | boolean | Flag indicating whether retry is allowed for this method Default: false | |
| retry | integer | Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1 | |
| digital | object | ||
| allowed | boolean | Flag indicating whether this method is allowed Default: true | |
| threshold | integer | Configure the age verification threshold for this check. | |
| retry | boolean | Flag indicating whether retry is allowed for this method Default: false | |
| retry | integer | Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1 | |
| doc | object | ||
| allowed | boolean | Flag indicating whether this method is allowed Default: true | |
| threshold | integer | Configure the age verification threshold for this check. | |
| retry | boolean | Flag indicating whether retry is allowed for this method Default: false | |
| retry | integer | Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1 | |
| credit | object | ||
| allowed | boolean | Flag indicating whether this method is allowed Default: true | |
| threshold | integer | Configure the age verification threshold for this check. | |
| retry | boolean | Flag indicating whether retry is allowed for this method Default: false | |
| retry | integer | Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1 | |
| mobile | object | ||
| allowed | boolean | Flag indicating whether this method is allowed Default: true | |
| threshold | integer | Configure the age verification threshold for this check. | |
| retry | boolean | Flag indicating whether retry is allowed for this method Default: false | |
| retry | integer | Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1 | |
| yoti | object | ||
| allowed | boolean | Flag indicating whether this method is allowed Default: true | |
| threshold | integer | Configure the age verification threshold for this check. | |
| retry | boolean | Flag indicating whether retry is allowed for this method Default: false | |
| retry | integer | Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1 | |
| electronic | object | ||
| allowed | boolean | Flag indicating whether this method is allowed Default: true | |
| threshold | integer | Configure the age verification threshold for this check. | |
| retry | boolean | Flag indicating whether retry is allowed for this method Default: false | |
| retry | integer | Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1 | |
| la | object | ||
| allowed | boolean | Flag indicating whether this method is allowed Default: true | |
| threshold | integer | Configure the age verification threshold for this check. | |
| retry | boolean | Flag indicating whether retry is allowed for this method Default: false | |
| retry | integer | Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1 | |
| social | object | ||
| allowed | boolean | Flag indicating whether this method is allowed Default: true | |
| threshold | integer | Configure the age verification threshold for this check. | |
| retry | boolean | Flag indicating whether retry is allowed for this method Default: false | |
| retry | integer | Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1 | |
| us | object | ||
| allowed | boolean | Flag indicating whether this method is allowed Default: true | |
| threshold | integer | Configure the age verification threshold for this check. | |
| retry | boolean | Flag indicating whether retry is allowed for this method Default: false | |
| retry | integer | Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1 | |
| double | object | ||
| allowed | boolean | Flag indicating the verification method is allowed Default: true | |
| threshold | integer | The age of interest multipleOf: 1 maximum: 100 minimum: 6 Default: 18 | |
| object | |||
| data | object | Data to check | |
| verified | string | An email address that has already been verified | |
| country | string | The two-letter ISO 3166-1 alpha-2 country code indicateing where the headless data is expected to be located | |
| ip | string | An IP address that is used as part of the risk assessment of headless data | |
| singpass | object | ||
| allowed | boolean | Flag indicating whether this method is allowed Default: true | |
| threshold | integer | Configure the age verification threshold for this check. | |
| retry | boolean | Flag indicating whether retry is allowed for this method Default: false | |
| retry | integer | Maximum times a user can attempt using this method multipleOf: 1 maximum: 10 minimum: 1 | |
| cpf | object | ||
| allowed | boolean | Flag indicating whether this method is allowed Default: true | |
| threshold | integer | Configure the age verification threshold for this check. | |
| retry | boolean | Flag indicating whether retry is allowed for this method Default: false | |
| retry | 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 | 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 | 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: | |
| block | boolean | Determine if the UI should block the display of a biometric required flow Default: false | |
| rule | string | The id in of the rule the age token must satisfy. Should be a uuid. pattern: | |
| cancel | string | URL where end users get redirected when they decide to cancel current AVS session | |
| privacy | string | URL for privacy policy | |
| terms | string | URL for terms and conditions | |
| retry | boolean | Ability for the user to retry verifying their age if an attempt fails Default: false | |
| resume | boolean | Should a user be allowed to retry after a fail / error status Default: false | |
| blocked | array[string] | A list of locations that have been blocked for access | |
| target | string | A http url that specifies the i-frame parent in order to dispatch status update event pattern: | |
| synchronous | 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 | 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 | boolean | Apply a secondary anonymisation step using Digital ID/Yoti Key Default: false |
curl --request POST \ --url 'https://developers.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 }, "digital_id": { "allowed": true, "threshold": 18, "retry_enabled": false, "retry_limit": 2 }, "doc_scan": { "allowed": true, "threshold": 18, "retry_enabled": false, "retry_limit": 2 }, "credit_card": { "allowed": true, "threshold": 18, "retry_enabled": false, "retry_limit": 2 }, "mobile": { "allowed": true, "threshold": 18, "retry_enabled": false, "retry_limit": 2 }, "yoti_key": { "allowed": true, "threshold": 18, "retry_enabled": false, "retry_limit": 2 }, "electronic_id": { "allowed": true, "threshold": 18, "retry_enabled": false, "retry_limit": 2 }, "la_wallet": { "allowed": true, "threshold": 18, "retry_enabled": false, "retry_limit": 2 }, "social_security_number": { "allowed": true, "threshold": 18, "retry_enabled": false, "retry_limit": 2 }, "us_florida_hb3": { "allowed": true, "threshold": 18, "retry_enabled": false, "retry_limit": 2 }, "double_anonymity": { "allowed": true, "threshold": 18 }, "email": { "data": { "verified_email": "john.doe@yoti.com", "country_code": "GB", "ip_address": "42.0.12.87" } }, "singpass": { "allowed": true, "threshold": 18, "retry_enabled": false, "retry_limit": 2 }, "cpf": { "allowed": true, "threshold": 18, "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}'OK
| object | object | Response from a session creation request | |
| id | string | Auto-generated | |
| expires | date-time | Session expiry time |
Bad request - missing field, spoofing attempt detected, invalid validation methods, need to re-verify
Missing or unknown Yoti-Sdk-Id
Not allowed to use this session
{ "id": "d1234a54-a655-47ed-92d5-ef00dcba0ac3", "expires_at": "2026-05-02T11:53:33Z"}Session retrival
Retrieve the configuration setup for a session.
| Yoti | string | SDK ID obtained from the Yoti Hub pattern: |
| sessionId | string | The consumer's session id, created by the Yoti server. pattern: |
curl --get \ --url 'https://developers.yoti.com/api/v1/sessions/def6fd14-dba9-4610-b6c3-9a7e8909aac0' \ --header 'Yoti-Sdk-Id: e8468a54-a655-47ed-92d5-ef00dcba0ac3' \ --header 'Authorization: Bearer {token}'Session retrieved for client consumption
| object | object | ||
| id | string | Session ID created by Yoti server | |
| sdk | 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: Default: OVER | |
| status | string | only sessions with a status of PENDING and which are not expired are returned at the moment Enum: | |
| expires | date-time | Session expiry time | |
| biometric | boolean | Determine whether the Biometric Consent Screen is enabled Default: true | |
| retry | boolean | Ability for the user to retry verifying their age if an attempt fails Default: false | |
| resume | boolean | This allows the user to resume a session (if the link is re-accessed). Default: false | |
| notification | 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: | |
| cancel | string | URL where end users get redirected when they decide to cancel current AVS session | |
| reference | 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 | date-time | Session creation time | |
| rule | 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: | |
| blocked | array[string] | A list of locations that have been blocked for access | |
| updated | date-time | Session update time | |
| biometric | date-time | The time when the biometric consent was given | |
| target | string | A http url that specifies the i-frame parent in order to dispatch status update event pattern: | |
| synchronous | 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 | boolean | Apply a secondary anonymisation step using Digital ID/Yoti Key Default: false |
Session not found
Session has expired for current check or invalid status
{ "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}Session Results
Get the session result
| Yoti | string | SDK ID obtained from the Yoti Hub pattern: |
| sessionId | string | The consumer's session id, created by the Yoti server. pattern: |
curl --get \ --url 'https://developers.yoti.com/api/v1/sessions/def6fd14-dba9-4610-b6c3-9a7e8909aac0/result' \ --header 'Yoti-Sdk-Id: e8468a54-a655-47ed-92d5-ef00dcba0ac3' \ --header 'Authorization: Bearer {token}'Session retrieved for relying party consumption
| object | object | ||
| id | string | Session ID created by Yoti server | |
| sdk | 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: Default: OVER | |
| status | string | only sessions with a status of PENDING and which are not expired are returned at the moment Enum: | |
| expires | date-time | Session expiry time | |
| biometric | boolean | Determine whether the Biometric Consent Screen is enabled Default: true | |
| retry | boolean | Ability for the user to retry verifying their age if an attempt fails Default: false | |
| resume | boolean | This allows the user to resume a session (if the link is re-accessed). Default: false | |
| notification | 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: | |
| cancel | string | URL where end users get redirected when they decide to cancel current AVS session | |
| reference | 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 | date-time | Session creation time | |
| rule | 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: | |
| blocked | array[string] | A list of locations that have been blocked for access | |
| updated | date-time | Session update time | |
| biometric | date-time | The time when the biometric consent was given | |
| target | string | A http url that specifies the i-frame parent in order to dispatch status update event pattern: | |
| synchronous | 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 | boolean | Apply a secondary anonymisation step using Digital ID/Yoti Key Default: false |
Missing or unknown Yoti-Sdk-Id
Session not found
{ "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}