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

# Age Estimation

> Estimate an end user's age from a live selfie using iDenfy's AI model, with an optional document-based step-up for uncertain cases.

Age Estimation checks whether an end user meets a minimum age requirement using a single selfie -- no document scan required in the common case. It's suited for age-gating use cases (e.g. alcohol, gambling, adult content) where you need a fast yes/no decision without putting every user through a full identity verification.

When the AI model isn't confident enough to decide on its own, the session can automatically step up to a document check, which reads an exact date of birth from the ID.

<Info>
  Looking for **Age Verification** instead? That's a different, simpler feature -- a min/max age restriction applied during a full [KYC verification](/guides/dashboard/kyc/age-verification), based on the scanned document's date of birth. Age Estimation is a standalone, selfie-first product with its own session, billing, and webhook.
</Info>

## How a Session Flows

<Steps>
  <Step title="Create">
    You create a token with the desired settings. The response includes `token`, `session_url`, and `expires_at`.
  </Step>

  <Step title="Capture">
    You send the end user to `session_url`; they complete the selfie on the hosted capture page.
  </Step>

  <Step title="Estimate">
    The AI produces an age estimate:

    * Confident and above threshold → `SUCCESS`.
    * Confident and below the minimum → `UNDERAGE`.
    * Not confident (within the buffer band) → **step-up** per `escalation`:
      * `DOC` → a document check is created; the age is read from the ID's date of birth (see [Step-Up Outcomes](#step-up-outcomes)).
      * `NONE` → the session resolves as `UNCERTAIN`.
  </Step>

  <Step title="Result">
    When the session finishes, iDenfy sends a result notification to your `webhook_url` (if set), redirects the user to the matching redirect URL (if configured), and exposes the outcome through the API.
  </Step>
</Steps>

## Step-Up Outcomes

A `DOC` step-up ends in one of the following ways. Note that the document's date of birth is an **exact** age, so it is compared directly against `min_age` -- the `buffer` band applies only to the fuzzy AI estimate and is not used here.

| Document check result                                | What happens                                                                                                                                                                                                                                            |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Document accepted**                                | The date of birth is read and the ID portrait is compared against the capture selfie. On a match the session resolves as `SUCCESS` (age ≥ `min_age`) or `UNDERAGE`.                                                                                     |
| **Document accepted but flagged for possible fraud** | Treated the same as accepted: the document was read successfully, so its age is used and the session resolves as `SUCCESS` or `UNDERAGE`. The fraud flag is retained by iDenfy for review and is **not** currently reported in the result notification. |
| **Document rejected**                                | The age could not be established from the ID, so the session resolves as `UNCERTAIN`. This is terminal -- the end user is not re-prompted for another ID.                                                                                               |
| **Face did not match**                               | The ID does not appear to belong to the person who took the selfie; the session resolves as `FACE_MISMATCH`. This is terminal.                                                                                                                          |
| **Step-up abandoned or lapsed**                      | The end user backed out, or the document session expired before completion. The session stays live and the end user can start a step-up again, subject to `retry_limit`.                                                                                |

<Warning>
  **Fraud-flagged documents are accepted.** iDenfy may flag a document session for possible fraudulent activity even when the document itself was read and the face matched. Because the purpose of the step-up is to establish the age, such a session yields a normal `SUCCESS` / `UNDERAGE` result rather than `UNCERTAIN`. If your own risk policy needs to act on the fraud signal, contact iDenfy -- surfacing it in the result notification is planned but not yet available.
</Warning>

## Enumerations

**Status** (`status`)

| Value        | Meaning                                                               |
| ------------ | --------------------------------------------------------------------- |
| `PENDING`    | Created, awaiting/undergoing capture.                                 |
| `PROCESSING` | Reserved lifecycle state.                                             |
| `COMPLETED`  | Finished with a definitive result.                                    |
| `FAILED`     | Finished unsuccessfully (technical failure or unrecoverable outcome). |
| `EXPIRED`    | Session lapsed without a terminal result.                             |

**Outcome** (`outcome`)

| Value               | Meaning                                                                                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SUCCESS`           | Meets the minimum age.                                                                                                                                   |
| `UNDERAGE`          | Below the minimum age.                                                                                                                                   |
| `UNCERTAIN`         | Inconclusive: an uncertain estimate with `escalation = NONE`, a document step-up whose document was rejected, or a technical failure during the step-up. |
| `FACE_MISMATCH`     | Step-up document face did not match the selfie.                                                                                                          |
| `ATTEMPTS_EXCEEDED` | Retry limit reached without a decision.                                                                                                                  |

**Escalation** (`escalation`): `DOC` (document step-up), `NONE` (no step-up).

## Billing

* The age-estimation fee is charged **once per terminal result** (`COMPLETED` or `FAILED`). Sessions that merely expire are not charged.
* A `DOC` step-up performs a document check, which is billed as a standard document scan in addition to the age-estimation fee.
* At creation, your balance is pre-checked for the age-estimation fee (plus a document scan when `escalation = DOC`); insufficient funds cause the create request to be rejected.

## Next Steps

<CardGroup cols={2}>
  <Card title="Create a Session" icon="key" href="/age-estimation/create-session">
    Create an age estimation session via the Partner API or the Dashboard.
  </Card>

  <Card title="Retrieve Tokens" icon="magnifying-glass" href="/age-estimation/retrieve-tokens">
    List and inspect sessions from the Dashboard.
  </Card>

  <Card title="Result Webhook" icon="bell" href="/age-estimation/webhooks">
    Receive the outcome as soon as a session finishes.
  </Card>
</CardGroup>


## Related topics

- [Age Estimation](/guides/dashboard/age-estimation/age-estimation.md)
- [Age estimation result](/api-reference/webhooks/age-estimation-result.md)
- [Age Estimation Webhooks](/age-estimation/webhooks.md)
- [Age Verification](/guides/dashboard/kyc/age-verification.md)
- [Create a Session](/age-estimation/create-session.md)