Incode Face and Liveness API

openapi: 3.0.1
info:
  title: Incode Omni API
  description: >-
    REST API for the Incode Omni identity verification platform. Onboarding
    sessions capture and validate government IDs, run face match and passive
    liveness, perform government-database and watchlist/AML screening, and
    return scores, OCR data, and images. All calls require an x-api-key, and
    module calls additionally require the session token in the
    X-Incode-Hardware-Id header.
  termsOfService: https://incode.com/legal/terms-of-service
  contact:
    name: Incode Support
    url: https://developer.incode.com/
  version: '1.0'
servers:
  - url: https://demo-api.incodesmile.com
    description: Demo / sandbox
  - url: https://api.incodesmile.com
    description: Production
security:
  - ApiKeyAuth: []
    SessionToken: []
tags:
  - name: Onboarding
    description: Create and complete onboarding sessions.
  - name: ID Verification
    description: Government ID capture and validation.
  - name: Face and Liveness
    description: Selfie capture, passive liveness, and face match.
  - name: Government Validation
    description: Validation against government databases.
  - name: Watchlist and AML
    description: Sanctions, PEP, and warning-list screening.
  - name: Results
    description: Fetch scores, OCR data, and images.
paths:
  /omni/start:
    post:
      operationId: startOnboarding
      tags:
        - Onboarding
      summary: Start an onboarding session.
      description: >-
        Creates a new onboarding session from a Flow configuration and returns a
        session token (Onboarding Token) used to authorize all subsequent Omni
        module calls.
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartSessionRequest'
      responses:
        '200':
          description: Session created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartSessionResponse'
  /omni/add/front-id/v2:
    post:
      operationId: addFrontId
      tags:
        - ID Verification
      summary: Add the front of an ID document.
      description: Uploads a base64-encoded image of the front of a government ID.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/HardwareId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddImageRequest'
      responses:
        '200':
          description: ID front processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddIdResponse'
  /omni/add/back-id/v2:
    post:
      operationId: addBackId
      tags:
        - ID Verification
      summary: Add the back of an ID document.
      description: Uploads a base64-encoded image of the back of a government ID.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/HardwareId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddImageRequest'
      responses:
        '200':
          description: ID back processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddIdResponse'
  /omni/process/id:
    post:
      operationId: processId
      tags:
        - ID Verification
      summary: Process the captured ID.
      description: >-
        Runs document validation and OCR on the captured ID images for the
        session. Accepts an empty JSON object.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/HardwareId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: ID processed; scores available via the Results API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessResponse'
  /omni/add/face/third-party:
    post:
      operationId: addFace
      tags:
        - Face and Liveness
      summary: Add a selfie image and run liveness.
      description: >-
        Uploads a base64-encoded selfie image. Passive liveness is evaluated on
        upload, indicating whether the image is of a real, present person.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/HardwareId'
        - name: imageType
          in: query
          required: true
          schema:
            type: string
            default: selfie
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddImageRequest'
      responses:
        '200':
          description: Selfie added; liveness result returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceResponse'
  /omni/process/face:
    post:
      operationId: processFace
      tags:
        - Face and Liveness
      summary: Run face match.
      description: >-
        Compares the session selfie against the face on the captured ID and
        returns the face match result.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/HardwareId'
        - name: imageType
          in: query
          required: false
          schema:
            type: string
            default: selfie
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Face match result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceResponse'
  /omni/process/government-validation:
    post:
      operationId: processGovernmentValidation
      tags:
        - Government Validation
      summary: Validate ID data against a government database.
      description: >-
        Validates captured ID data against the applicable government source
        based on the session country code (e.g. Mexico INE, Peru RENIEC), with
        optional fallback and selfie-to-government-image comparison.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/HardwareId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GovernmentValidationRequest'
      responses:
        '200':
          description: Government validation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessResponse'
  /omni/process/global-watchlist:
    post:
      operationId: processGlobalWatchlist
      tags:
        - Watchlist and AML
      summary: Run a global watchlist screening.
      description: >-
        Screens the session subject against global sanctions, PEP, and warning
        lists using the Flow configuration; results persist with the session.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/HardwareId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistRequest'
      responses:
        '200':
          description: Watchlist screening result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistResponse'
  /omni/watchlist-result:
    post:
      operationId: watchlistResult
      tags:
        - Watchlist and AML
      summary: Query watchlist data without persistence.
      description: >-
        Lightweight screening that queries watchlist data using request and
        interview data without persistent storage.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/HardwareId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistRequest'
      responses:
        '200':
          description: Watchlist result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistResponse'
  /omni/updated-watchlist-result:
    get:
      operationId: updatedWatchlistResult
      tags:
        - Watchlist and AML
      summary: Retrieve updated watchlist results.
      description: >-
        Retrieves refreshed watchlist search results after an ongoing-monitoring
        webhook notification.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/HardwareId'
        - name: id
          in: query
          required: false
          schema:
            type: string
          description: Interview ID.
        - name: ref
          in: query
          required: true
          schema:
            type: string
          description: Reference number from the watchlist update webhook.
      responses:
        '200':
          description: Updated watchlist result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistResponse'
  /omni/finish-status:
    get:
      operationId: finishStatus
      tags:
        - Onboarding
      summary: Get onboarding completion status.
      description: Returns the completion status of the onboarding session.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/HardwareId'
      responses:
        '200':
          description: Onboarding status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinishStatusResponse'
  /omni/get/score:
    get:
      operationId: getScore
      tags:
        - Results
      summary: Fetch session scores.
      description: >-
        Returns all check and validation results for a completed session,
        including the overall status (OK, WARN, FAIL).
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/HardwareId'
        - name: id
          in: query
          required: false
          schema:
            type: string
          description: Interview ID (Session ID); extracted from the token if omitted.
      responses:
        '200':
          description: Score data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreResponse'
  /omni/get/ocr-data:
    get:
      operationId: getOcrData
      tags:
        - Results
      summary: Fetch OCR data.
      description: Returns OCR data extracted from the captured ID for the session.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/HardwareId'
        - name: interviewId
          in: query
          required: false
          schema:
            type: string
          description: Interview ID (Session ID).
      responses:
        '200':
          description: OCR data.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /omni/get/images:
    get:
      operationId: getImages
      tags:
        - Results
      summary: Fetch session images.
      description: Returns the captured images for the onboarding session.
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/HardwareId'
        - name: interviewId
          in: query
          required: false
          schema:
            type: string
          description: Interview ID (Session ID).
      responses:
        '200':
          description: Image data.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Client API key issued by Incode.
    SessionToken:
      type: apiKey
      in: header
      name: X-Incode-Hardware-Id
      description: Session token (Onboarding Token) returned by POST /omni/start.
  parameters:
    ApiVersion:
      name: api-version
      in: header
      required: true
      schema:
        type: string
        default: '1.0'
    HardwareId:
      name: X-Incode-Hardware-Id
      in: header
      required: true
      schema:
        type: string
      description: Session token returned by POST /omni/start.
  schemas:
    StartSessionRequest:
      type: object
      required:
        - configurationId
      properties:
        configurationId:
          type: string
          description: The Incode Flow identifier (Flow ID).
        countryCode:
          type: string
          description: Country code for the session (e.g. ALL, MEX, USA).
          example: ALL
        externalCustomerId:
          type: string
          description: Custom ID linking the session to your system.
    StartSessionResponse:
      type: object
      properties:
        token:
          type: string
          description: Session token used for subsequent Omni calls.
        interviewId:
          type: string
          description: Unique session identifier.
        interviewToken:
          type: string
    AddImageRequest:
      type: object
      required:
        - base64Image
      properties:
        base64Image:
          type: string
          description: Base64-encoded image.
    AddIdResponse:
      type: object
      properties:
        sharpness:
          type: number
        glare:
          type: number
        classification:
          type: boolean
        typeOfId:
          type: string
    FaceResponse:
      type: object
      properties:
        confidence:
          type: number
        isBright:
          type: boolean
        hasLenses:
          type: boolean
        hasFaceMask:
          type: boolean
        existingUser:
          type: boolean
    ProcessResponse:
      type: object
      properties:
        success:
          type: boolean
      additionalProperties: true
    GovernmentValidationRequest:
      type: object
      properties:
        fallbackEnabled:
          type: boolean
          default: false
        scrapingMethod:
          type: boolean
          default: false
      additionalProperties: true
    WatchlistRequest:
      type: object
      properties:
        firstName:
          type: string
        surName:
          type: string
        dateOfBirth:
          type: string
        watchlistTypes:
          type: array
          items:
            type: string
            enum:
              - sanction
              - pep
              - warning
        subscribe:
          type: boolean
    WatchlistResponse:
      type: object
      properties:
        status:
          type: string
        hits:
          type: array
          items:
            type: object
            additionalProperties: true
    FinishStatusResponse:
      type: object
      properties:
        onboardingStatus:
          type: string
          example: ONBOARDING_FINISHED
    ScoreResponse:
      type: object
      properties:
        overall:
          type: object
          properties:
            status:
              type: string
              enum:
                - OK
                - WARN
                - FAIL
            value:
              type: number
      additionalProperties: true