Create a Session

Create an age estimation session with the iDenfy Partner API: authentication, the request and token response, and the error returned when funds are insufficient.

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.

Create a Session

Authenticate with your API key pair — API key as the username, API secret as the password, over HTTP Basic. 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 the request is rejected — see Errors.

Example (Partner API)

Request

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

{
  "min_age": 18,
  "confidence_threshold": 85,
  "buffer": 2,
  "escalation": "DOC",
  "save_photo": true,
  "expiry_minutes": 60,
  "success_redirect": "https://partner.example.com/ok",
  "underage_redirect": "https://partner.example.com/denied",
  "webhook_url": "https://partner.example.com/hooks/age",
  "client_id": "user-42"
}

Response

{
  "token": "b7c1…",
  "session_url": "https://capture.idenfy.example/?token=b7c1…",
  "expires_at": "2026-07-14T12:00:00+00:00",
  "min_age": 18,
  "confidence_threshold": 85.0,
  "buffer": 2,
  "escalation": "DOC",
  "retry_limit": 3,
  "save_photo": true,
  "expiry_minutes": 60,
  "client_id": "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.",
    "missing_limits": [],
    "missing_additional_step_limits": [],
    "missing_funds": null,
    "missing_pool_funds": [
      { "fund_pool": "AGE_ESTIMATION", "missing": 3.0 }
    ],
    "expired_expenses": []
  }
}

When handling this response:

• Read missing_pool_funds to identify which finances are short. The response uses fund_pool naming for what the guides call Age Estimation finances.
• missing_funds 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 session_url, send the end user to it to complete the selfie capture. When the session finishes, the result is delivered via the result webhook — this is the only way to receive it programmatically, so configure one. Past sessions can be listed and inspected by signing in to the dashboard; see Session List.