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
minAge
integer
required

Minimum age the end user must meet.

Required range: 1 <= x <= 120
confidenceThreshold
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 minAge that triggers a step-up instead of an immediate decision. Must not exceed minAge. 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
retryLimit
integer
default:3

Max estimation attempts before the session locks.

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

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

expiryMinutes
integer
default:60

Token validity window in minutes from creation.

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

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

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

Redirect after an UNDERAGE outcome.

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

Redirect after a terminal UNCERTAIN outcome.

Maximum string length: 2048
webhookUrl
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
clientId
string | null

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

Maximum string length: 100

Response

token
string
required
read-only

Opaque session credential used by the capture page.

sessionUrl
string<uri>
required
read-only

URL to send the end user to.

expiresAt
string<date-time>
required
read-only

Absolute UTC expiry.

minAge
integer
required
confidenceThreshold
number<float>
required
buffer
integer
escalation
enum<string>
Available options:
DOC,
NONE
retryLimit
integer
savePhoto
boolean
expiryMinutes
integer
clientId
string | null