> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.idenfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  **Requirements:**

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

For how the feature works, what each outcome means, and how billing works, see the [Age Estimation Overview](/guides/dashboard/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.

<Info>
  For the full request and response schemas, every field's constraints and defaults, and an interactive playground, see the [**API Reference**](/api-reference/age-estimation/create-session) page for this endpoint.
</Info>

Creating a session pre-checks your [Age Estimation finances](/guides/dashboard/age-estimation/billing); if they can't cover the session the request is rejected -- see [Errors](#errors).

### Example (Partner API)

<Tabs>
  <Tab title="Request">
    ```http theme={"system"}
    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"
    }
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={"system"}
    {
      "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"
    }
    ```
  </Tab>
</Tabs>

***

## 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:

```json theme={"system"}
{
  "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.

<Note>
  Insufficient funds return **`402`**, not `403`. This matches iDenfy's other token-creation endpoints -- see [ID Error Messages](/kyc/id-error-messages#post-apiv2token-errors). `403` is reserved for an account that lacks access to the endpoint or feature.
</Note>

***

## 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](/age-estimation/webhooks) — 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](/guides/dashboard/age-estimation/dashboard#session-list).


## Related topics

- [Create session](/api-reference/age-estimation/create-session.md)
- [Creating a KYB Session](/guides/dashboard/kyb/creating-session.md)
- [Identity Verification API (KYC)](/kyc/overview.md)
- [Sole Proprietorship Workflow Step](/guides/dashboard/kyb/step-sole-proprietorship.md)
- [Create Verification Session](/kyc/generate-token.md)