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

> Creates an age estimation session. On creation, your balance is checked for the age-estimation fee (and, when `escalation` is `DOC`, also for a document scan); if funds are insufficient the request is rejected.



## OpenAPI

````yaml /openapi/age-estimation.yaml post /age-estimation/token/
openapi: 3.1.0
info:
  title: iDenfy IVS Core API
  version: 0.0.0
  description: iDenfy Identity Verification Service's Core API documentation.
  contact:
    name: API Support
    url: https://idenfy-ivs.atlassian.net/servicedesk/customer/portal/1/group/-1
  x-logo:
    url: /static/idenfy_logo.svg
    altText: iDenfy logo
servers:
  - url: https://ivs.idenfy.com
security: []
tags:
  - name: Age Estimation
    description: Age estimation session endpoints.
  - name: Webhooks
    description: Webhooks.
externalDocs:
  description: For other/more docs on iDenfy services visit our main documentation page.
  url: https://documentation.idenfy.com
paths:
  /age-estimation/token/:
    post:
      tags:
        - Age Estimation
      summary: Create session
      description: >-
        Creates an age estimation session. On creation, your balance is checked
        for the age-estimation fee (and, when `escalation` is `DOC`, also for a
        document scan); if funds are insufficient the request is rejected.
      operationId: ageEstimationTokenCreate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgeEstimationTokenRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgeEstimationToken'
          description: ''
      security:
        - apiKeyPair: []
components:
  schemas:
    AgeEstimationTokenRequest:
      type: object
      properties:
        min_age:
          type: integer
          minimum: 1
          maximum: 120
          description: Minimum age the end user must meet.
        confidence_threshold:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: Minimum model confidence to accept an estimate without a step-up.
        buffer:
          type: integer
          default: 0
          minimum: 0
          maximum: 20
          description: >-
            Age band (in years) around `min_age` that triggers a step-up instead
            of an immediate decision. Must not exceed `min_age`. Applies to the
            AI estimate only, never to a document-derived age.
        escalation:
          allOf:
            - $ref: '#/components/schemas/AgeEstimationEscalationEnum'
          default: DOC
          description: >-
            Action when the estimate is uncertain. `DOC` = document step-up;
            `NONE` = resolve as `UNCERTAIN`.
        retry_limit:
          type: integer
          default: 3
          minimum: 1
          maximum: 3
          description: Max estimation attempts before the session locks.
        save_photo:
          type: boolean
          default: true
          description: Whether the analysed selfie is stored for sessions from this token.
        expiry_minutes:
          type: integer
          default: 60
          minimum: 5
          maximum: 1440
          description: Token validity window in minutes from creation.
        success_redirect:
          type: string
          format: uri
          maxLength: 2048
          default: ''
          description: Redirect after a `SUCCESS` outcome (blank = built-in result screen).
        underage_redirect:
          type: string
          format: uri
          maxLength: 2048
          default: ''
          description: Redirect after an `UNDERAGE` outcome.
        uncertain_redirect:
          type: string
          format: uri
          maxLength: 2048
          default: ''
          description: Redirect after a terminal `UNCERTAIN` outcome.
        webhook_url:
          type: string
          format: uri
          maxLength: 2048
          default: ''
          description: >-
            Per-session override for where the result notification is sent.
            Blank = use your account's default Age Estimation webhook
            notification.
        client_id:
          type: string
          maxLength: 100
          nullable: true
          description: >-
            Your own identifier for the end user; echoed back in the result
            webhook for correlation.
      required:
        - min_age
        - confidence_threshold
    AgeEstimationToken:
      type: object
      properties:
        token:
          type: string
          readOnly: true
          description: Opaque session credential used by the capture page.
        session_url:
          type: string
          format: uri
          readOnly: true
          description: URL to send the end user to.
        expires_at:
          type: string
          format: date-time
          readOnly: true
          description: Absolute UTC expiry.
        min_age:
          type: integer
        confidence_threshold:
          type: number
          format: float
        buffer:
          type: integer
        escalation:
          $ref: '#/components/schemas/AgeEstimationEscalationEnum'
        retry_limit:
          type: integer
        save_photo:
          type: boolean
        expiry_minutes:
          type: integer
        client_id:
          type: string
          nullable: true
      required:
        - token
        - session_url
        - expires_at
        - min_age
        - confidence_threshold
    AgeEstimationEscalationEnum:
      enum:
        - DOC
        - NONE
      type: string
  securitySchemes:
    apiKeyPair:
      type: http
      scheme: basic
      description: >-
        The request must contain basic auth headers where username is *API key*
        and password is *API secret*.<br>

        In order for you to start using our API you will need an **API key** and
        **API secret**.<br>

        Both can be retrieved by contacting *iDenfy's support* or *iDenfy's
        sales team*.

````

## Related topics

- [Create a Session](/age-estimation/create-session.md)
- [Creating a KYB Session](/guides/dashboard/kyb/creating-session.md)
- [ID Verification (KYC)](/kyc/overview.md)
- [Sole Proprietorship Workflow Step](/guides/dashboard/kyb/step-sole-proprietorship.md)
- [Gambling and Gaming](/guides/use-cases/gambling.md)