Skip to main content
POST
Create session

Authorizations

Authorization
string
header
required

The request must contain basic auth headers where username is API key and password is API secret.
In order for you to start using our API you will need an API key and API secret.
Both can be retrieved by contacting iDenfy's support or iDenfy's sales team.

Body

application/json
min_age
integer
required

Minimum age the end user must meet.

Required range: 1 <= x <= 120
confidence_threshold
number<float>
required

Minimum model confidence to accept an estimate without a step-up.

Required range: 0 <= x <= 100
buffer
integer
default:0

Age band (in years) around min_age that triggers a step-up instead of an immediate decision. Must not exceed min_age. Applies to the AI estimate only, never to a document-derived age.

Required range: 0 <= x <= 20
escalation
enum<string>
default:DOC

Action when the estimate is uncertain. DOC = document step-up; NONE = resolve as UNCERTAIN.

Available options:
DOC,
NONE
retry_limit
integer
default:3

Max estimation attempts before the session locks.

Required range: 1 <= x <= 3
save_photo
boolean
default:true

Whether the analysed selfie is stored for sessions from this token.

expiry_minutes
integer
default:60

Token validity window in minutes from creation.

Required range: 5 <= x <= 1440
success_redirect
string<uri>
default:""

Redirect after a SUCCESS outcome (blank = built-in result screen).

Maximum string length: 2048
underage_redirect
string<uri>
default:""

Redirect after an UNDERAGE outcome.

Maximum string length: 2048
uncertain_redirect
string<uri>
default:""

Redirect after a terminal UNCERTAIN outcome.

Maximum string length: 2048
webhook_url
string<uri>
default:""

Per-session override for where the result notification is sent. Blank = use your account's default Age Estimation webhook notification.

Maximum string length: 2048
client_id
string | null

Your own identifier for the end user; echoed back in the result webhook for correlation.

Maximum string length: 100

Response

201 - application/json
token
string
required
read-only

Opaque session credential used by the capture page.

session_url
string<uri>
required
read-only

URL to send the end user to.

expires_at
string<date-time>
required
read-only

Absolute UTC expiry.

min_age
integer
required
confidence_threshold
number<float>
required
buffer
integer
escalation
enum<string>
Available options:
DOC,
NONE
retry_limit
integer
save_photo
boolean
expiry_minutes
integer
client_id
string | null