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

# Create a verification session

> Creates a new identity verification session with the specified configuration



## OpenAPI

````yaml POST /sessions
openapi: 3.0.3
info:
  title: FaceSign API
  description: >
    The FaceSign API enables developers to create AI-powered identity
    verification flows with conversational interfaces, 

    biometric verification, document scanning, and multi-factor authentication.
  version: 1.0.18
  contact:
    name: FaceSign Support
    email: support@facesign.ai
    url: https://facesign.ai
  license:
    name: MIT
    url: https://github.com/facesignai/facesign-api/blob/main/LICENSE
servers:
  - url: https://api.facesign.ai
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Sessions
    description: Identity verification session management
  - name: Languages
    description: Supported language operations
  - name: Avatars
    description: Available avatar operations
paths:
  /sessions:
    post:
      tags:
        - Sessions
      summary: Create a verification session
      description: >-
        Creates a new identity verification session with the specified
        configuration
      operationId: createSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionSettings'
            examples:
              basicSession:
                summary: Basic conversational session
                value:
                  clientReferenceId: user-123
                  metadata:
                    source: web-app
                  flow:
                    - id: start
                      type: start
                      outcome: greeting
                    - id: greeting
                      type: conversation
                      prompt: 'Say: Hello! What''s your name?'
                      outcomes:
                        - id: t1
                          condition: user provided name
                          targetNodeId: end
                    - id: end
                      type: end
      responses:
        '200':
          description: Session created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSessionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    SessionSettings:
      type: object
      required:
        - clientReferenceId
      properties:
        clientReferenceId:
          type: string
          description: Your internal reference ID for this session
          example: user-123
        metadata:
          type: object
          description: Custom metadata (max 50KB)
          example:
            source: web-app
            department: sales
        initialPhrase:
          type: string
          description: Opening message from the avatar
        finalPhrase:
          type: string
          description: Closing message from the avatar
        providedData:
          type: object
          additionalProperties:
            type: string
          description: Pre-filled user data
        avatarId:
          type: string
          description: Specific avatar to use
        langs:
          type: array
          items:
            type: string
          description: Available languages for the session
          example:
            - en
            - es
            - fr
        defaultLang:
          type: string
          description: Default language
          example: en
        zone:
          type: string
          enum:
            - es
            - eu
          description: Geographic zone
        modules:
          type: array
          items:
            $ref: '#/components/schemas/Module'
          description: Legacy module configuration (deprecated, use flow instead)
        flow:
          type: array
          items:
            $ref: '#/components/schemas/FSNode'
          description: |
            Flat array of nodes that defines the verification flow. Each node
            carries its own `outcome` (START node) or `outcomes` (verification
            nodes) that reference other node ids by string, so there is no
            separate edges array. See the `FSNode` schema for per-type shapes.
      oneOf:
        - required:
            - modules
          not:
            required:
              - flow
        - required:
            - flow
          not:
            required:
              - modules
    CreateSessionResponse:
      type: object
      required:
        - session
        - clientSecret
      properties:
        session:
          $ref: '#/components/schemas/Session'
        clientSecret:
          $ref: '#/components/schemas/ClientSecret'
    Module:
      oneOf:
        - $ref: '#/components/schemas/EmailVerification'
        - $ref: '#/components/schemas/SmsVerification'
        - $ref: '#/components/schemas/IdentityVerification'
        - $ref: '#/components/schemas/DocumentAuthentication'
        - $ref: '#/components/schemas/AgeEstimation'
        - $ref: '#/components/schemas/ProofOfIntent'
        - $ref: '#/components/schemas/KnowledgeVerify'
      discriminator:
        propertyName: type
    FSNode:
      oneOf:
        - $ref: '#/components/schemas/FSStartNode'
        - $ref: '#/components/schemas/FSEndNode'
        - $ref: '#/components/schemas/FSConversationNode'
        - $ref: '#/components/schemas/FSLivenessDetectionNode'
        - $ref: '#/components/schemas/FSEnterEmailNode'
        - $ref: '#/components/schemas/FSDataValidationNode'
        - $ref: '#/components/schemas/FSDocumentScanNode'
        - $ref: '#/components/schemas/FSRecognitionNode'
        - $ref: '#/components/schemas/FSFaceScanNode'
        - $ref: '#/components/schemas/FSTwoFactorNode'
      discriminator:
        propertyName: type
        mapping:
          start:
            $ref: '#/components/schemas/FSStartNode'
          end:
            $ref: '#/components/schemas/FSEndNode'
          conversation:
            $ref: '#/components/schemas/FSConversationNode'
          liveness_detection:
            $ref: '#/components/schemas/FSLivenessDetectionNode'
          enter_email:
            $ref: '#/components/schemas/FSEnterEmailNode'
          data_validation:
            $ref: '#/components/schemas/FSDataValidationNode'
          document_scan:
            $ref: '#/components/schemas/FSDocumentScanNode'
          recognition:
            $ref: '#/components/schemas/FSRecognitionNode'
          face_scan:
            $ref: '#/components/schemas/FSFaceScanNode'
          two_factor:
            $ref: '#/components/schemas/FSTwoFactorNode'
    Session:
      type: object
      required:
        - id
        - createdAt
        - status
        - settings
      properties:
        id:
          type: string
        createdAt:
          type: integer
          description: Unix timestamp
        startedAt:
          type: integer
          description: Unix timestamp when user began
        finishedAt:
          type: integer
          description: Unix timestamp when completed/canceled
        status:
          $ref: '#/components/schemas/SessionStatus'
        settings:
          $ref: '#/components/schemas/SessionSettings'
        version:
          type: string
        report:
          $ref: '#/components/schemas/SessionReport'
    ClientSecret:
      type: object
      required:
        - secret
        - createdAt
        - expireAt
        - url
      properties:
        secret:
          type: string
        createdAt:
          type: integer
          description: Unix timestamp
        expireAt:
          type: integer
          description: Unix timestamp
        url:
          type: string
          description: Hosted session URL
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - message
          properties:
            type:
              type: string
              enum:
                - authentication_error
                - validation_error
                - not_found_error
                - rate_limit_error
                - server_error
            message:
              type: string
            code:
              type: string
    EmailVerification:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - emailVerification
        name:
          type: string
        email:
          type: string
        publicRecognitionEnabled:
          type: boolean
    SmsVerification:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - smsVerification
        phone:
          type: string
    IdentityVerification:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - identityVerification
    DocumentAuthentication:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - documentAuthentication
    AgeEstimation:
      type: object
      required:
        - type
        - age
      properties:
        type:
          type: string
          enum:
            - ageEstimation
        age:
          type: integer
    ProofOfIntent:
      type: object
      required:
        - type
        - requestedData
      properties:
        type:
          type: string
          enum:
            - proofOfIntent
        requestedData:
          type: array
          items:
            $ref: '#/components/schemas/RequestedData'
    KnowledgeVerify:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - knowledgeVerify
    FSStartNode:
      allOf:
        - $ref: '#/components/schemas/FSNodeBase'
        - type: object
          required:
            - outcome
          properties:
            type:
              type: string
              enum:
                - start
            outcome:
              type: string
              description: >-
                Id of the next node the flow transitions to when the session
                begins.
    FSEndNode:
      allOf:
        - $ref: '#/components/schemas/FSNodeBase'
        - type: object
          properties:
            type:
              type: string
              enum:
                - end
    FSConversationNode:
      allOf:
        - $ref: '#/components/schemas/FSNodeBase'
        - type: object
          required:
            - prompt
            - outcomes
          properties:
            type:
              type: string
              enum:
                - conversation
            prompt:
              type: string
              description: >
                The avatar's prompt. Two modes:

                - `"Say: ..."` — literal speech; the avatar speaks the text
                verbatim. Use for English-only flows.

                - Descriptive goal-driven prompt — the LLM paraphrases and
                translates. Use for multilingual flows.
            outcomes:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/FSConditionalOutcome'
              description: >
                Array of conditional outcomes evaluated by the AI in order. The
                first matching

                condition determines the next node. At least one outcome is
                required.
            doesNotRequireReply:
              type: boolean
              description: >
                Set to true only on the final conversation node before an END,
                where the avatar

                speaks but no user reply is expected. Using this on non-final
                nodes causes loops.
    FSLivenessDetectionNode:
      allOf:
        - $ref: '#/components/schemas/FSNodeBase'
        - type: object
          required:
            - outcomes
          properties:
            type:
              type: string
              enum:
                - liveness_detection
            outcomes:
              type: object
              additionalProperties:
                type: string
              description: Maps outcome to target node ID
    FSEnterEmailNode:
      allOf:
        - $ref: '#/components/schemas/FSNodeBase'
        - type: object
          required:
            - outcomes
          properties:
            type:
              type: string
              enum:
                - enter_email
            outcomes:
              type: object
              additionalProperties:
                type: string
              description: >
                Map of outcome keys (`emailEntered`, `canceled`) to target node
                ids.
    FSDataValidationNode:
      allOf:
        - $ref: '#/components/schemas/FSNodeBase'
        - type: object
          required:
            - outcomes
            - validation
          properties:
            type:
              type: string
              enum:
                - data_validation
            outcomes:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/FSConditionalOutcome'
            validation:
              type: object
              required:
                - field
                - action
              properties:
                field:
                  type: string
                action:
                  type: string
                value:
                  type: string
    FSDocumentScanNode:
      allOf:
        - $ref: '#/components/schemas/FSNodeBase'
        - type: object
          required:
            - scanningMode
            - allowedDocumentTypes
            - outcomes
          properties:
            type:
              type: string
              enum:
                - document_scan
            scanningMode:
              $ref: '#/components/schemas/FSDocumentScanMode'
            allowedDocumentTypes:
              type: array
              items:
                $ref: '#/components/schemas/FSDocumentType'
            outcomes:
              type: object
              additionalProperties:
                type: string
            showTorchButton:
              type: boolean
              default: true
            showCameraSwitch:
              type: boolean
              default: true
    FSRecognitionNode:
      allOf:
        - $ref: '#/components/schemas/FSNodeBase'
        - type: object
          required:
            - outcomes
          properties:
            type:
              type: string
              enum:
                - recognition
            outcomes:
              type: object
              additionalProperties:
                type: string
    FSFaceScanNode:
      allOf:
        - $ref: '#/components/schemas/FSNodeBase'
        - type: object
          required:
            - mode
            - outcomes
          properties:
            type:
              type: string
              enum:
                - face_scan
            mode:
              $ref: '#/components/schemas/FSFaceScanMode'
            outcomes:
              type: object
              additionalProperties:
                type: string
            captureInstructions:
              type: string
            saveToField:
              type: string
            requireLiveness:
              type: boolean
            referenceImageSource:
              type: string
              enum:
                - session
                - providedData
                - url
            referenceImageKey:
              type: string
            referenceImageUrl:
              type: string
            similarityThreshold:
              type: number
              minimum: 0
              maximum: 1
            captureDelay:
              type: integer
              default: 3000
            detectionInterval:
              type: integer
              default: 150
            qualityThreshold:
              type: number
              default: 0.7
            blurThreshold:
              type: number
              default: 50
            minFaceSize:
              type: integer
              default: 100
            maxFaceSize:
              type: integer
              default: 400
            enableSound:
              type: boolean
              default: true
            enableHaptics:
              type: boolean
              default: true
            useWebGL:
              type: boolean
              default: true
            maxRetries:
              type: integer
              default: 3
    FSTwoFactorNode:
      allOf:
        - $ref: '#/components/schemas/FSNodeBase'
        - type: object
          required:
            - channels
            - contactSource
            - outcomes
          properties:
            type:
              type: string
              enum:
                - two_factor
            channels:
              type: array
              items:
                $ref: '#/components/schemas/FSTwoFactorChannel'
            contactSource:
              $ref: '#/components/schemas/FSTwoFactorContactSource'
            outcomes:
              type: object
              additionalProperties:
                type: string
            staticEmail:
              type: string
            staticPhone:
              type: string
            emailTemplate:
              type: string
            smsTemplate:
              type: string
            otpLength:
              type: integer
              minimum: 4
              maximum: 8
              default: 6
            expirySeconds:
              type: integer
              default: 300
            maxAttempts:
              type: integer
              default: 3
            resendAfterSeconds:
              type: integer
            showUI:
              type: boolean
              default: true
            testMode:
              type: object
              properties:
                enabled:
                  type: boolean
                email:
                  type: string
                phone:
                  type: string
    SessionStatus:
      type: string
      description: >
        Session lifecycle status.


        - `created` — session created on backend, user has not opened the
        verification URL yet

        - `inProgress` — user has opened the verification URL and is completing
        the flow

        - `complete` — user finished the flow; full report available

        - `incomplete` — session ended without the user reaching an END node
        (abandoned, expired, or terminated)
      enum:
        - created
        - inProgress
        - complete
        - incomplete
    SessionReport:
      type: object
      properties:
        transcript:
          type: array
          items:
            $ref: '#/components/schemas/Phrase'
        aiAnalysis:
          $ref: '#/components/schemas/SessionReportAIAnalysis'
        location:
          type: object
          description: Geolocation data
        device:
          type: object
          description: Device fingerprint
        livenessDetected:
          type: boolean
        lang:
          type: string
        extractedData:
          type: object
          additionalProperties:
            type: string
        screenshots:
          type: array
          items:
            type: string
        videos:
          type: object
          properties:
            avatarVideoUrl:
              type: string
            userVideoUrl:
              type: string
        isVerified:
          type: boolean
    RequestedData:
      type: object
      required:
        - key
      properties:
        key:
          type: string
        isRequired:
          type: boolean
        description:
          type: string
    FSNodeBase:
      type: object
      required:
        - id
        - type
      properties:
        id:
          type: string
          description: Unique identifier for the node within the flow
        type:
          $ref: '#/components/schemas/FSNodeType'
    FSConditionalOutcome:
      type: object
      required:
        - id
        - condition
        - targetNodeId
      properties:
        id:
          type: string
          description: Unique identifier for this outcome within the node.
        condition:
          type: string
          description: >-
            Natural-language condition the AI evaluates against the dialog
            state.
        targetNodeId:
          type: string
          description: Id of the node to transition to when this condition matches.
    FSDocumentScanMode:
      type: string
      enum:
        - SINGLE_SIDE
        - MULTI_SIDE
        - BARCODE
    FSDocumentType:
      type: string
      enum:
        - MRTD_TYPE_UNKNOWN
        - MRTD_TYPE_IDENITY_CARD
        - MRTD_TYPE_PASSPORT
        - MRTD_TYPE_VISA
        - MRTD_TYPE_GREEN_CARD
        - MRTD_TYPE_MYS_PASS_IMM13P
        - MRTD_TYPE_DL
        - MRTD_TYPE_INTERNAL_TRAVEL_DOCUMENT
        - MRTD_TYPE_BORDER_CROSSING_CARD
    FSFaceScanMode:
      type: string
      enum:
        - capture
        - compare
    FSTwoFactorChannel:
      type: string
      enum:
        - email
        - sms
    FSTwoFactorContactSource:
      type: string
      enum:
        - session_data
        - module_settings
        - recognition_match
    Phrase:
      type: object
      required:
        - id
        - createdAt
        - text
        - isAvatar
      properties:
        id:
          type: string
        createdAt:
          type: integer
          description: Unix timestamp
        text:
          type: string
        isAvatar:
          type: boolean
    SessionReportAIAnalysis:
      type: object
      properties:
        ageMin:
          type: integer
        ageMax:
          type: integer
        sex:
          type: string
          enum:
            - male
            - female
        realPersonOrVirtual:
          type: string
          enum:
            - real
            - virtual
            - noface
        overallSummary:
          type: string
        analysis:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              shortDescription:
                type: string
              longDescription:
                type: string
    FSNodeType:
      type: string
      enum:
        - start
        - end
        - conversation
        - liveness_detection
        - enter_email
        - data_validation
        - document_scan
        - recognition
        - face_scan
        - two_factor
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: validation_error
              message: Invalid request parameters
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: authentication_error
              message: Invalid API key provided
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: rate_limit_error
              message: Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: The rate limit ceiling
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: The number of requests remaining in the current window
        X-RateLimit-Reset:
          schema:
            type: integer
          description: The time at which the rate limit window resets in Unix time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key authentication. Use format "Bearer sk_live_..." or "Bearer
        sk_test_..."

````