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

# Create a new verification session



## OpenAPI

````yaml /api-reference/openapi.json post /v1/sessions
openapi: 3.1.0
info:
  title: Kayle ID
  version: 1.5.0
  description: Privacy-first identity verification.
  license:
    name: Apache License 2.0
    url: https://github.com/kayleai/kayle-id/blob/main/LICENSE
  contact:
    name: Kayle ID
    url: https://kayle.id
    email: help@kayle.id
  termsOfService: https://kayle.id/terms
servers:
  - url: http://127.0.0.1:8787
    description: ''
security:
  - bearerAuth: []
paths:
  /v1/sessions:
    post:
      tags:
        - Sessions
      summary: Create a new verification session
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSessionRequest'
      responses:
        '200':
          description: >-
            Successful operation. Returns the newly created verification
            session.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: The ID of the verification session
                      status:
                        type: string
                        enum:
                          - created
                          - in_progress
                          - succeeded
                          - failed
                          - expired
                          - cancelled
                        description: The status of the verification session
                      failure_code:
                        type:
                          - string
                          - 'null'
                        enum:
                          - document_authenticity_failed
                          - document_active_authentication_failed
                          - document_chip_authentication_failed
                          - document_anti_cloning_attestation_failed
                          - document_data_invalid
                          - liveness_failed
                          - selfie_face_mismatch
                        description: >-
                          Terminal failure code when status='failed'. Null in
                          any other state.
                      nfc_tries_used:
                        type: integer
                        minimum: 0
                        maximum: 3
                        description: >-
                          Number of NFC chip-read failures the session has
                          consumed. The session terminalizes on the 3rd failure.
                      liveness_tries_used:
                        type: integer
                        minimum: 0
                        maximum: 3
                        description: >-
                          Number of liveness check failures the session has
                          consumed. The session terminalizes on the 3rd failure.
                      contract_version:
                        type: integer
                        description: Version of the session share contract.
                      share_fields:
                        type: object
                        additionalProperties:
                          type: object
                          properties:
                            required:
                              type: boolean
                              description: Whether this field must always be shared.
                            reason:
                              type: string
                              description: Reason shown to the user for this field.
                            source:
                              type: string
                              enum:
                                - default
                                - rc
                              description: >-
                                Whether the field came from defaults or RC
                                request.
                          required:
                            - required
                            - reason
                            - source
                        description: >-
                          Effective normalized share fields used by this
                          session.
                      redirect_url:
                        type:
                          - string
                          - 'null'
                        description: >-
                          The URL to redirect to after the verification session
                          is completed, if provided by the integrator.
                      webhook_endpoint_id:
                        anyOf:
                          - type: string
                          - type: array
                            items:
                              type: string
                          - type: 'null'
                        description: >-
                          The webhook endpoint or endpoint list selected for
                          this session, or null when events fan out to all
                          enabled subscribed endpoints.
                      verification_url:
                        type: string
                        format: uri
                        description: >-
                          The URL that the platform should send the user to in
                          order to complete the verification. Includes the
                          one-shot `cancel_token` as a query parameter so the
                          verify browser / native app can pass it back when
                          cancelling.
                      cancel_token:
                        type: string
                        description: >-
                          One-shot token required by `POST
                          /v1/verify/session/:id/cancel`. Returned only on
                          session creation.
                      expires_at:
                        type: string
                        description: The expiration time of the verification session
                      completed_at:
                        type:
                          - string
                          - 'null'
                        description: >-
                          The time the verification session reached a terminal
                          state (i.e., succeeded, failed, expired or cancelled),
                          or null if not yet terminal.
                      created_at:
                        type: string
                        description: The time the verification session was created
                      updated_at:
                        type: string
                        description: The time the verification session was last updated
                    required:
                      - id
                      - status
                      - failure_code
                      - nfc_tries_used
                      - liveness_tries_used
                      - contract_version
                      - share_fields
                      - redirect_url
                      - webhook_endpoint_id
                      - verification_url
                      - expires_at
                      - completed_at
                      - created_at
                      - updated_at
                    examples:
                      - id: >-
                          vs_mza7vecksrtyfw193ekcvl5vnws3bt1lz96buu3iw7zidckf8dga2zx2echb3t16
                        status: created
                        failure_code: null
                        nfc_tries_used: 0
                        liveness_tries_used: 0
                        contract_version: 1
                        share_fields:
                          document_type_code:
                            required: false
                            reason: Needed to know the document type code
                            source: rc
                          date_of_birth:
                            required: true
                            reason: Needed to verify age eligibility
                            source: rc
                          kayle_document_id:
                            required: true
                            reason: Sharing "Kayle Document ID"
                            source: default
                        redirect_url: https://example.com/redirect
                        webhook_endpoint_id: null
                        verification_url: >-
                          https://verify.kayle.id/vs_mza7vecksrtyfw193ekcvl5vnws3bt1lz96buu3iw7zidckf8dga2zx2echb3t16
                        expires_at: '2025-01-01T00:00:00Z'
                        completed_at: null
                        created_at: '2025-01-01T00:00:00Z'
                        updated_at: '2025-01-01T00:00:00Z'
                  error:
                    type: 'null'
                required:
                  - data
                  - error
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                    description: Empty data object.
                  error:
                    type:
                      - object
                      - 'null'
                    properties:
                      code:
                        type: string
                        description: The error code
                      message:
                        type: string
                        description: The error message
                      hint:
                        type: string
                        description: A hint to help the user fix the error
                      docs:
                        type: string
                        description: A link to the documentation for the error
                    required:
                      - code
                      - message
                      - hint
                      - docs
                required:
                  - data
                  - error
                example:
                  data: null
                  error:
                    code: UNKNOWN_CLAIM_KEY
                    message: Unknown claim key.
                    hint: >-
                      Use a supported claim key from the share contract
                      allowlist.
                    docs: https://kayle.id/docs/api/sessions#create
        '410':
          description: Organization is scheduled for deletion.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                    description: Empty data object.
                  error:
                    type:
                      - object
                      - 'null'
                    properties:
                      code:
                        type: string
                        description: The error code
                      message:
                        type: string
                        description: The error message
                      hint:
                        type: string
                        description: A hint to help the user fix the error
                      docs:
                        type: string
                        description: A link to the documentation for the error
                    required:
                      - code
                      - message
                      - hint
                      - docs
                required:
                  - data
                  - error
        '429':
          description: Unverified organization has exceeded the rolling 24h session limit.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                    description: Empty data object.
                  error:
                    type:
                      - object
                      - 'null'
                    properties:
                      code:
                        type: string
                        description: The error code
                      message:
                        type: string
                        description: The error message
                      hint:
                        type: string
                        description: A hint to help the user fix the error
                      docs:
                        type: string
                        description: A link to the documentation for the error
                    required:
                      - code
                      - message
                      - hint
                      - docs
                required:
                  - data
                  - error
                example:
                  data: null
                  error:
                    code: ORG_NOT_VERIFIED_LIMIT_EXCEEDED
                    message: >-
                      Unverified organizations are limited to 5
                      identity-revealing sessions per 24 hours.
                    hint: >-
                      Verify the organization in the platform settings, or wait
                      until the rolling window resets. Age-gate-only sessions
                      remain available.
                    docs: https://kayle.id/docs/api/sessions#create
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - INTERNAL_SERVER_ERROR
                      message:
                        type: string
                        enum:
                          - Internal server error.
                      hint:
                        type: string
                        enum:
                          - The server encountered an error.
                      docs:
                        type: string
                        enum:
                          - https://kayle.id/docs/api/errors
                    required:
                      - code
                      - message
                      - hint
                      - docs
                required:
                  - data
                  - error
      security:
        - bearerAuth: []
components:
  schemas:
    CreateSessionRequest:
      type: object
      properties:
        redirect_url:
          type: string
          maxLength: 2048
          description: >-
            Optional URL to redirect the user to after the verification session
            is completed. Must use https:// (http:// is only accepted for
            localhost in development).
        share_fields:
          type: object
          additionalProperties:
            type: object
            properties:
              required:
                type: boolean
                description: Whether this field is required by the RC.
              reason:
                type: string
                maxLength: 200
                description: >-
                  Human-readable reason for requesting this field. Required for
                  most claims; may be empty for an `age_over_X` claim when
                  `date_of_birth` is also requested in the same session.
            required:
              - required
              - reason
          description: >-
            Optional map of requested share fields keyed by claim key. Each
            entry must include `required` (boolean) and `reason` (non-empty
            string, max 200).
        webhook_endpoint_id:
          anyOf:
            - type: string
              minLength: 1
              maxLength: 128
              pattern: ^[A-Za-z0-9_-]+$
            - type: array
              items:
                type: string
                minLength: 1
                maxLength: 128
                pattern: ^[A-Za-z0-9_-]+$
              minItems: 1
              maxItems: 25
          description: >-
            Optional webhook endpoint ID or endpoint ID list to target for this
            session. When omitted, events fan out to every enabled subscribed
            endpoint.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````