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.
Sessions API endpoints
Session Configuration
Session creation
A session represents one end-to-end request of the age verification service. The session identifier is in the create session request's response. Every time a user elects a method of age verification on your relying business app or website, you will need to create a session with Yoti to perform the checks.
| Content | string | Define the expected payload content type (always application/json). | |
| Yoti | string | Relying party's SDK ID generated from the Yoti hub pattern: |
This payload will generate a session configuration object
| object | object | ||
| type | string | Enum: Default: OVER | |
| age | object | Configuration object for age estimation | |
| allowed | boolean | Enable the verification method to be available for the user to use. Default: true | |
| threshold | integer | Age threshold for under/over age limits. We recommend for this threshold to be more than the age you want to set as your barrier to entry. | |
| level | string | The level of anti-spoofing for each age verification method. PASSIVE enables a passive liveness test for age estimation. Enum: Default: NONE | |
| retry | integer | Maximum times a user can try this method in a give session Default: 3 | |
| doc | object | Configuration object for doc scan | |
| allowed | boolean | To enable/disable the method Default: ture | |
| threshold | integer | Age threshold for under/over age limits. Default: 18 | |
| level | string | The level of anti-spoofing for each age verification method. PASSIVE enables a passive liveness test and face match for IDV. Enum: Default: NONE | |
| authenticity | string | Verification of the ID Document authenticity. Enum: Default: AUTO | |
| digital | object | Configuration object for digital id | |
| threshold | integer | Age threshold for under/over age limits. We recommend this to be the exact age of the threshold you want to cover. Default: 18 | |
| age | boolean | Allows the Estimated age attribute to be used for the check. Default: true | |
| age | integer | The difference between this value and the above threshold must be between 1 and 20 away. Anything else will return an error on session creation Default: 21 | |
| credit | object | Base configration object for verification methods | |
| allowed | boolean | Enable the verification method to be available for the user to use. Default: true | |
| retry | integer | Maximum times a user can try this method in a session | |
| mobile | object | Verify your user is over 18 using their mobile provider details. | |
| allowed | boolean | Enable the verification method to be available for the user to use. Default: ture | |
| retry | integer | No of times that a user can retry using this method. Default: 3 | |
| electronic | object | Use Swedish Bank ID (Sweden), Mit ID (Denmark) and Finnish Trust Network (Finland) in order to verify a user's age. | |
| threshold | integer | Age threshold for verification. Default: 18 | |
| sub | array[string] | The different electronic ID options available to a user. Enum: | |
| la | object | Configuration object for LA Wallet support | |
| allowed | boolean | Enable the verification method to be available for the user to use. Default: true | |
| retry | integer | Maximum times a user can try this method in a give session Default: 3 | |
| threshold | integer | Age threshold for under/over age limits. We recommend this to be the exact age of the threshold you want to cover. | |
| age | object | Configuration object for Yoti keys | |
| allowed | boolean | Enable the verification method to be available for the user to use. Default: true | |
| authentication | boolean | False: When the Yoti user interface is launched we immediately check if the user has a token that matches the requirements set in the rule. If it matches, the user is immediately directed to the callback url. True: When users finish any of the Yoti age verification methods, they have the option to create a passkey. They can then use this yoti key to quickly pass any future age verification sessions that they need to undergo. If authentication is set to true, The Yoti user interface will be shown, the user can then select the yoti_key method to verify their age, or they can use another method in the UI. Default: true | |
| object | Configration object for email | ||
| data | object | Data to check | |
| verified | string | An email address that has already been verified | |
| country | string | The country code indicateing where the headless data is expected to be located | |
| ttl | integer | This is a value in seconds which is used to determine the expiry time of this session maximum: 2592000 minimum: 60 | |
| reference | string | This is a value that can be passed as a means of reconcilliation of a result | |
| 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 | The URL where the results of an age verification should be sent. This endpoint must use HTTPS and accept POST requests for notifications. pattern: | |
| block | boolean | 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. Default: false | |
| rule | 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. pattern: | |
| cancel | string | 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. | |
| retry | boolean | 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. Default: false | |
| resume | boolean | 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. Default: false | |
| synchronous | boolean | If set to true, ensures that all methods have a result ready before the user is redirected to the callback URL. 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 |
curl --request POST \ --url 'https://age.yoti.com/api/v1/sessions' \ --header 'Content-Type: application/json' \ --header 'Yoti-Sdk-Id: {Yoti-Sdk-Id}' \ --header 'Authorization: Bearer {token}' \ --data '{ "type": "OVER", "age_estimation": { "allowed": true, "threshold": 21, "level": "PASSIVE", "retry_limit": 3 }, "doc_scan": { "allowed": true, "threshold": 18, "level": "PASSIVE", "authenticity": "AUTO", "preset_issuing_country": "GBR", "retry_limit": 3 }, "digital_id": { "allowed": true, "threshold": 18, "age_estimation_allowed": true, "age_estimation_threshold": 21, "retry_limit": 3 }, "credit_card": { "allowed": true, "retry_limit": 3 }, "mobile": { "allowed": true, "retry_limit": 3 }, "electronic_id": { "allowed": true, "threshold": 18, "sub_methods": [ "MIT_ID", "SWEDISH_BANK_ID", "FTN" ], "retry_limit": 3 }, "la_wallet": { "allowed": true, "retry_limit": 3, "threshold": 18 }, "age_key": { "allowed": true, "authentication": true }, "email": { "data": { "verified_email": "melissa.peterson@yoti.com", "country_code": "gb" } }, "ttl": 900, "reference_id": "YOUR_REFERENCE_ID", "callback": { "url": "https://www.yoti.com/callback", "auto": true }, "notification_url": "https://www.yoti.com/notification", "block_biometric_consent": false, "rule_id": "9974cf35-7340-4e91-9073-76171cb66e29", "cancel_url": "https://www.yoti.com/cancel", "retry_enabled": true, "resume_enabled": false, "synchronous_checks": true, "double_blind": false}'OK
| object | object | Response from a session creation request | |
| id | string | Auto-generated session ID (UUID) for age verification | |
| status | string | Current status of the age verification session | |
| 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": "(uuid)", "status": "PENDING", "expires_at": "2025-08-08T23:41:39.000Z"}Session retrieval
Retrieve the configuration setup for a session. This will only include the information required by a UI to display the allowable flows and methods.
| Yoti | string | Relying party's SDK ID generated from the Yoti hub pattern: | |
| Accept | string | Accept-Language string |
| sessionId | string | The consumer's session id, created by the relying party server. pattern: |
curl --get \ --url 'https://age.yoti.com/api/v1/sessions/def6fd14-dba9-4610-b6c3-9a7e8909aac0' \ --header 'Yoti-Sdk-Id: {Yoti-Sdk-Id}' \ --header 'Accept-Language: {Accept-Language}' \ --header 'Authorization: Bearer {token}'Session retrieved for client consumption
| object | object | Shared session object properties | |
| id | string | Session ID | |
| sdk | string | SDK ID | |
| callback | object | Callback object to describe how a user's experience should be managed after they have submitted age verification evidence | |
| auto | boolean | The flag that indicate whether users will be automatically redirected after verification. | |
| type | string | Enum: Default: OVER | |
| status | string | Current status of the age verification session Enum: | |
| expires | date-time | Session expiry time | |
| biometric | boolean | Determine if the UI should display a biometric required flow Default: true | |
| cancel | boolean | Flag to indicate whether cancelling the session is allowed Default: false | |
| retry | boolean | Flag to indicate whether the user has the ability to retry verifying their age if an attempt fails. Default: false | |
| resume | boolean | Flag to indicate whether a user is allowed to retry after a fail / error status Default: false | |
| notification | string | The URL where the results of an age verification should be sent. | |
| cancel | string | The URL for redirection upon user cancelling the session | |
| reference | string | A string for your internal reference. Yoti does not use it, but returns this same string in the session result. | |
| created | date-time | Session creation date and time | |
| evidence | string | An ID related to a specific age verification attempt | |
| rule | string | Rule ID for using Age Token | |
| age | integer | Exact age of the user if the session TYPE is configured to "AGE" else it will return as the threshold value | |
| updated | date-time | Session last update time | |
| biometric | date-time | The time the user gives consent on biometric permission | |
| synchronous | boolean | Should toggle the UI processing wait screen for asynchronous checks Default: false | |
| double | boolean | If this session should be run in double blind mode. Default: false |
Session not found
Session has expired for current check or invalid status
{ "id": "def6fd14-dba9-4610-b6c3-9a7e8909aac0", "sdk_id": {}, "callback": { "auto": true }, "type": "OVER", "status": "PENDING", "expires_at": "2025-08-08T23:41:39.000Z", "biometric_consent_required": true, "cancel_session_allowed": false, "retry_enabled": false, "resume_enabled": false, "notification_url": "https://www.yoti.com/notification", "cancel_url": "https://www.yoti.com/cancel", "reference_id": "YOUR_REFERENCE_ID", "created_at": "2025-08-08T22:43:39.000Z", "evidence_id": "7340dc90-7340-4e54-2346-76981cz68e31", "rule_id": "9974cf35-7340-4e91-9073-76171cb66e29", "age": 18, "updated_at": "2025-08-08T22:45:12.000Z", "biometric_consent_given_at": "2025-08-08T22:45:12.000Z", "synchronous_checks": false, "double_blind": false}Session Results
Get the session result
Retrieve session results for an Age verification session
| Yoti | string | Relying party's SDK ID generated from the Yoti hub pattern: |
| sessionId | string | The consumer's session id, created by the relying party server. pattern: |
curl --get \ --url 'https://age.yoti.com/api/v1/sessions/def6fd14-dba9-4610-b6c3-9a7e8909aac0/result' \ --header 'Yoti-Sdk-Id: {Yoti-Sdk-Id}' \ --header 'Authorization: Bearer {token}'Session retrieved for relying party consumption
| object | object | Shared session object properties | |
| id | string | Session ID | |
| sdk | string | SDK ID | |
| callback | object | Callback object to describe how a user's experience should be managed after they have submitted age verification evidence | |
| auto | boolean | The flag that indicate whether users will be automatically redirected after verification. | |
| type | string | Enum: Default: OVER | |
| status | string | Current status of the age verification session Enum: | |
| expires | date-time | Session expiry time | |
| biometric | boolean | Determine if the UI should display a biometric required flow Default: true | |
| cancel | boolean | Flag to indicate whether cancelling the session is allowed Default: false | |
| retry | boolean | Flag to indicate whether the user has the ability to retry verifying their age if an attempt fails. Default: false | |
| resume | boolean | Flag to indicate whether a user is allowed to retry after a fail / error status Default: false | |
| notification | string | The URL where the results of an age verification should be sent. | |
| cancel | string | The URL for redirection upon user cancelling the session | |
| reference | string | A string for your internal reference. Yoti does not use it, but returns this same string in the session result. | |
| created | date-time | Session creation date and time | |
| evidence | string | An ID related to a specific age verification attempt | |
| rule | string | Rule ID for using Age Token | |
| age | integer | Exact age of the user if the session TYPE is configured to "AGE" else it will return as the threshold value | |
| updated | date-time | Session last update time | |
| biometric | date-time | The time the user gives consent on biometric permission | |
| synchronous | boolean | Should toggle the UI processing wait screen for asynchronous checks Default: false | |
| double | boolean | If this session should be run in double blind mode. Default: false |
Missing or unknown Yoti-Sdk-Id
Session not found
{ "id": "def6fd14-dba9-4610-b6c3-9a7e8909aac0", "sdk_id": {}, "callback": { "auto": true }, "type": "OVER", "status": "PENDING", "expires_at": "2025-08-08T23:41:39.000Z", "biometric_consent_required": true, "cancel_session_allowed": false, "retry_enabled": false, "resume_enabled": false, "notification_url": "https://www.yoti.com/notification", "cancel_url": "https://www.yoti.com/cancel", "reference_id": "YOUR_REFERENCE_ID", "created_at": "2025-08-08T22:43:39.000Z", "evidence_id": "7340dc90-7340-4e54-2346-76981cz68e31", "rule_id": "9974cf35-7340-4e91-9073-76171cb66e29", "age": 18, "updated_at": "2025-08-08T22:45:12.000Z", "biometric_consent_given_at": "2025-08-08T22:45:12.000Z", "synchronous_checks": false, "double_blind": false}