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

> How iDenfy's selfie-based age estimation works: the session flow, document step-up outcomes, and the statuses and outcomes a session can resolve to.

<Info>
  Looking for **Age Verification** instead? That's a different, simpler feature -- a min/max age restriction applied during a full KYC verification, based on the scanned document's date of birth. See [Age Verification](/guides/dashboard/kyc/age-verification).
</Info>

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.

Sessions can be created and reviewed [from the dashboard](/guides/dashboard/age-estimation/dashboard), or created programmatically -- see [API integration](#api-integration). Charges draw on finances allocated to Age Estimation; see [Age Estimation Billing](/guides/dashboard/age-estimation/billing).

<Note>
  Results reach your systems through the [result webhook](/age-estimation/webhooks). To list past estimations, filter them, or inspect an individual session, sign in to the dashboard -- there is no Partner API endpoint for retrieving sessions.
</Note>

## How a Session Flows

<Steps>
  <Step title="Create">
    You create a session with the desired settings. You get back a verification link and an expiry time.
  </Step>

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

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

    * Confident and above the minimum age → **Success**.
    * Confident and below the minimum age → **Underage**.
    * Not confident (within the safety margin) → **step-up**, if enabled:
      * document step-up enabled → a document check is created and the age is read from the ID's date of birth (see [Step-Up Outcomes](#step-up-outcomes)).
      * document step-up disabled → the session resolves as **Uncertain**.
  </Step>

  <Step title="Result">
    When the session finishes, iDenfy sends a result notification to your webhook (if set), redirects the user to the matching redirect URL (if configured), and shows the outcome in the dashboard.
  </Step>
</Steps>

## Step-Up Outcomes

A document 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 the minimum age -- the safety margin 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 ≥ minimum) 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 the 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>

## Statuses and Outcomes

A session has a lifecycle **status**, and once it finishes, an **outcome**. The values below are what the API returns; the dashboard shows the same values as labels.

**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**

| Value               | Dashboard label   | Meaning                                                                                                                                                   |
| ------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SUCCESS`           | Success           | Meets the minimum age.                                                                                                                                    |
| `UNDERAGE`          | Underage          | Below the minimum age.                                                                                                                                    |
| `UNCERTAIN`         | Uncertain         | Inconclusive: an uncertain estimate with the step-up disabled, a document step-up whose document was rejected, or a technical failure during the step-up. |
| `FACE_MISMATCH`     | Face Mismatch     | Step-up document face did not match the selfie.                                                                                                           |
| `ATTEMPTS_EXCEEDED` | Attempts Exceeded | Retry limit reached without a decision.                                                                                                                   |

## API Integration

<CardGroup cols={2}>
  <Card title="Create a Session" icon="key" href="/age-estimation/create-session">
    Create a session from your backend, with the full request schema and error responses.
  </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 Dashboard](/guides/dashboard/age-estimation/dashboard.md)
- [Age Verification](/guides/dashboard/kyc/age-verification.md)
- [Create a Session](/age-estimation/create-session.md)
- [Age Estimation Billing](/guides/dashboard/age-estimation/billing.md)
- [Age estimation result](/api-reference/webhooks/age-estimation-result.md)