Create a Session

Requirements:

API key pair (API key + secret)
Age Estimation feature enabled on your contract (contact iDenfy to activate)
Finances available for Age Estimation

For how the feature works, what each outcome means, and how billing works, see the Age Estimation Overview guide. This documentation focuses on the API integration.

Authenticate with your API key pair over HTTP Basic. Use the API key as the username and the API secret as the password. Sessions are scoped to your partner account, so you only ever see your own.

For the full request and response schemas, every field’s constraints and defaults, and an interactive playground, see the API Reference page for this endpoint.

Creating a session pre-checks your Age Estimation finances; if they can’t cover the session, iDenfy rejects the request. See Errors.

Example (Partner API)

Request
Response

POST /age-estimation/token/
Authorization: Basic {API_KEY}:{API_SECRET}
Content-Type: application/json

{
  "minAge": 18,
  "confidenceThreshold": 85,
  "buffer": 2,
  "escalation": "DOC",
  "savePhoto": true,
  "expiryMinutes": 60,
  "successRedirect": "https://partner.example.com/ok",
  "underageRedirect": "https://partner.example.com/denied",
  "webhookUrl": "https://partner.example.com/hooks/age",
  "clientId": "user-42"
}

{
  "token": "b7c1…",
  "sessionUrl": "https://capture.idenfy.example/?token=b7c1…",
  "expiresAt": "2026-07-14T12:00:00+00:00",
  "minAge": 18,
  "confidenceThreshold": 85.0,
  "buffer": 2,
  "escalation": "DOC",
  "retryLimit": 3,
  "savePhoto": true,
  "expiryMinutes": 60,
  "clientId": "user-42"
}

Errors

Status	Message	When
`402`	`"Action not allowed due to lack of funds or exceeded limit."`	Age Estimation finances cannot cover the session

The response body identifies which finances are short:

{
  "message": "Action not allowed due to lack of funds or exceeded limit.",
  "code": "insufficient_finances",
  "detail": {
    "detail": "Action not allowed due to lack of funds or exceeded limit.",
    "missingLimits": [],
    "missingAdditionalStepLimits": [],
    "missingFunds": null,
    "missingPoolFunds": [
      { "fundPool": "AGE_ESTIMATION", "missing": 3.0 }
    ],
    "expiredExpenses": []
  }
}

When handling this response:

Read missingPoolFunds to identify which finances are short. The response uses fundPool naming for what the guides call Age Estimation finances.
missingFunds stays null. It covers general funds only, so do not read it to detect exhausted Age Estimation finances.
missing is the shortfall in your account currency, and 0 when no Age Estimation finances are configured.

Insufficient funds return 402, not 403. This matches iDenfy’s other token-creation endpoints. See ID Error Messages. 403 is reserved for an account that lacks access to the endpoint or feature.

What’s Next

Once you have a sessionUrl, send the end user to it to complete the selfie capture. When the session finishes, iDenfy delivers the result via the result webhook. This is the only way to receive it programmatically, so configure one. To list and inspect past sessions, sign in to the dashboard. See Session List.

Start Here

ID Verification (KYC)

Business Verification (KYB)

AML Screening

Face Authentication

Age Estimation

Bank Card Verification

Fraud Prevention

Bank Verification

Social Screening

Going Live

Reference

Create a Session

Create a Session

Example (Partner API)

Errors

What’s Next

​Create a Session

​Example (Partner API)

​Errors

​What’s Next

Create a Session

Example (Partner API)

Errors

What’s Next