infinihash-com Liveness & Biometrics API

openapi: 3.2.0
info:
  title: Infinihash KYC Liveness & Biometrics API
  version: 1.0.0
  description: 'Identity verification, KYB, sanctions screening, UBO orchestration and periodic review.


    Auth: send your key as `X-API-Key: ` (or `Authorization: Bearer `).


    Most endpoints are mounted twice — at the root (`/kyc/...`) and under `/api` (`/api/kyc/...`). Prefer the `/api` form; it is what the hosted portals and SDKs use.


    Python SDK: `pip install "git+https://github.com/Infinihash/kyc-python@v0.1.0"` (https://github.com/Infinihash/kyc-python; runnable examples in examples/).'
  contact:
    name: Infinihash
    url: https://kyc.infinihash.com
servers:
- url: https://kyc-api.infinihash.com
  description: Production
tags:
- name: Liveness & Biometrics
  description: Selfie liveness challenges and face matching.
paths:
  /kyc/{id}/liveness-check:
    post:
      x-route-source:
        file: routes/kyc.js
        method: post
        path: /:id/liveness-check
      summary: Create an IDV / liveness session
      description: Creates an identity-verification (liveness) session with the configured provider for the submission and records a running liveness_check. Send the end user to session_url. No request body.
      tags:
      - Liveness & Biometrics
      operationId: post_kyc_id_liveness_check
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '201':
          description: Session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KycLivenessSession'
        '401':
          description: Missing or invalid API key
        '404':
          description: Submission not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '500':
          description: Provider or unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /kyc/{id}/consent:
    post:
      x-route-source:
        file: routes/consent.js
        method: post
        path: /:id/consent
      summary: Record biometric consent
      description: Stores an auditable, append-only biometric/PII processing consent record for the submission's primary subject (snapshotting the consent text, policy version and retention schedule, plus IP and user agent). `method` is mandatory so the record states honestly how consent was obtained. Liveness, selfie and face-match calls are refused (412) until consent exists.
      tags:
      - Liveness & Biometrics
      operationId: recordConsent
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsentRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '201':
          description: Consent recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentRecord'
        '400':
          description: method_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentError'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: submission not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited (global per-IP limit)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: consent_capture_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      x-route-source:
        file: routes/consent.js
        method: get
        path: /:id/consent
      summary: Get biometric consent status
      description: Returns whether the primary subject has consented, with all consent records for the submission (oldest first; UBO consents appear with subject `other`). Does not write a record.
      tags:
      - Liveness & Biometrics
      operationId: getConsentStatus
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Consent status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsentStatus'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: submission not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited (global per-IP limit)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: consent_status_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /kyc/{submissionId}/biometric:
    post:
      x-route-source:
        file: routes/biometric.js
        method: post
        path: /:submissionId/biometric
      summary: Face match and passive liveness
      description: Compares a selfie with the face on an uploaded ID document (embedding cosine similarity) and scores passive liveness. Individuals only. Requires recorded biometric consent (POST /kyc/{id}/consent). Sets the submission status to biometric_passed, biometric_failed or biometric_review; embeddings are never returned or stored.
      tags:
      - Liveness & Biometrics
      operationId: post_kyc_submissionId_biometric
      parameters:
      - name: submissionId
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BioFaceMatchRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Decision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BioFaceMatchResult'
        '400':
          description: selfie_b64 / id_document_id required, biometric_only_for_individuals, or the document type is not passport/id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
        '404':
          description: submission not found, or id_document not found in submission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: id_document image no longer available; re-upload and retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '412':
          description: 'biometric_consent_required: no biometric consent on file; POST /kyc/{id}/consent first (body carries consentEndpoint)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '500':
          description: biometric_check_failed (detail has the cause; upstream worker errors may surface their own status)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /kyc/liveness.html:
    get:
      x-route-source:
        file: routes/liveness-v2.js
        method: get
        path: /liveness.html
      summary: Legacy liveness capture page
      description: Static HTML page of the legacy face-api.js selfie capture UI. No authentication.
      tags:
      - Liveness & Biometrics
      operationId: get_kyc_liveness_html
      security: []
      responses:
        '200':
          description: HTML page
          content:
            text/html:
              schema:
                type: string
        '429':
          description: Rate limited
  /kyc/liveness.js:
    get:
      x-route-source:
        file: routes/liveness-v2.js
        method: get
        path: /liveness.js
      summary: Legacy liveness capture script
      description: Static JavaScript for the legacy liveness page. No authentication.
      tags:
      - Liveness & Biometrics
      operationId: get_kyc_liveness_js
      security: []
      responses:
        '200':
          description: JavaScript source
          content:
            application/javascript:
              schema:
                type: string
        '429':
          description: Rate limited
  /kyc/{id}/liveness:
    post:
      x-route-source:
        file: routes/liveness-v2.js
        method: post
        path: /:id/liveness
      summary: Submit a selfie for ID face match
      description: 'One selfie is compared (ArcFace) with the most recent completed ID document image of the submission and stored as check liveness_v2_face_match. NOT a liveness proof: any photo is accepted, so it only shows that the photo matches the ID. Requires biometric consent. A passing match triggers the automatic sanctions screening. A worker failure still answers 200 with passed:false and error set (check goes to review).'
      tags:
      - Liveness & Biometrics
      operationId: post_kyc_id_liveness
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LiveSelfieRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Face match outcome
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveFaceMatchResult'
        '400':
          description: selfie_image (base64) is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
        '404':
          description: Submission not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '412':
          description: 'biometric_consent_required: no biometric consent on file; POST /kyc/{id}/consent first (body carries consentEndpoint)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'no_id_image: no ID document image on the submission; upload a document first'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /kyc/{id}/liveness-status:
    get:
      x-route-source:
        file: routes/liveness-v2.js
        method: get
        path: /:id/liveness-status
      summary: Liveness / face-match status
      description: Summarises the IDV session check (liveness_check) and the selfie face match (liveness_v2_face_match) of the submission.
      tags:
      - Liveness & Biometrics
      operationId: get_kyc_id_liveness_status
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveStatus'
        '401':
          description: Missing or invalid API key
        '404':
          description: Submission not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/kyc/{id}/liveness-check:
    post:
      x-route-source:
        file: routes/kyc.js
        method: post
        path: /:id/liveness-check
      summary: Create an IDV / liveness session
      description: Creates an identity-verification (liveness) session with the configured provider for the submission and records a running liveness_check. Send the end user to session_url. No request body.
      tags:
      - Liveness & Biometrics
      operationId: createLivenessCheck
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '201':
          description: Session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KycLivenessSession'
        '401':
          description: Missing or invalid API key
        '404':
          description: Submission not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '500':
          description: Provider or unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/kyc/{submissionId}/biometric:
    post:
      x-route-source:
        file: routes/biometric.js
        method: post
        path: /:submissionId/biometric
      summary: Face match and passive liveness
      description: Compares a selfie with the face on an uploaded ID document (embedding cosine similarity) and scores passive liveness. Individuals only. Requires recorded biometric consent (POST /kyc/{id}/consent). Sets the submission status to biometric_passed, biometric_failed or biometric_review; embeddings are never returned or stored.
      tags:
      - Liveness & Biometrics
      operationId: biometricCheck
      parameters:
      - name: submissionId
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BioFaceMatchRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Decision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BioFaceMatchResult'
        '400':
          description: selfie_b64 / id_document_id required, biometric_only_for_individuals, or the document type is not passport/id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
        '404':
          description: submission not found, or id_document not found in submission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: id_document image no longer available; re-upload and retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '412':
          description: 'biometric_consent_required: no biometric consent on file; POST /kyc/{id}/consent first (body carries consentEndpoint)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '500':
          description: biometric_check_failed (detail has the cause; upstream worker errors may surface their own status)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/kyc/liveness.html:
    get:
      x-route-source:
        file: routes/liveness-v2.js
        method: get
        path: /liveness.html
      summary: Legacy liveness capture page
      description: Static HTML page of the legacy face-api.js selfie capture UI. No authentication.
      tags:
      - Liveness & Biometrics
      operationId: getLegacyLivenessPage
      security: []
      responses:
        '200':
          description: HTML page
          content:
            text/html:
              schema:
                type: string
        '429':
          description: Rate limited
  /api/kyc/liveness.js:
    get:
      x-route-source:
        file: routes/liveness-v2.js
        method: get
        path: /liveness.js
      summary: Legacy liveness capture script
      description: Static JavaScript for the legacy liveness page. No authentication.
      tags:
      - Liveness & Biometrics
      operationId: getLegacyLivenessScript
      security: []
      responses:
        '200':
          description: JavaScript source
          content:
            application/javascript:
              schema:
                type: string
        '429':
          description: Rate limited
  /api/kyc/{id}/liveness:
    post:
      x-route-source:
        file: routes/liveness-v2.js
        method: post
        path: /:id/liveness
      summary: Submit a selfie for ID face match
      description: 'One selfie is compared (ArcFace) with the most recent completed ID document image of the submission and stored as check liveness_v2_face_match. NOT a liveness proof: any photo is accepted, so it only shows that the photo matches the ID. Requires biometric consent. A passing match triggers the automatic sanctions screening. A worker failure still answers 200 with passed:false and error set (check goes to review).'
      tags:
      - Liveness & Biometrics
      operationId: submitLivenessSelfie
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LiveSelfieRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Face match outcome
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveFaceMatchResult'
        '400':
          description: selfie_image (base64) is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
        '404':
          description: Submission not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '412':
          description: 'biometric_consent_required: no biometric consent on file; POST /kyc/{id}/consent first (body carries consentEndpoint)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'no_id_image: no ID document image on the submission; upload a document first'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/kyc/{id}/liveness-status:
    get:
      x-route-source:
        file: routes/liveness-v2.js
        method: get
        path: /:id/liveness-status
      summary: Liveness / face-match status
      description: Summarises the IDV session check (liveness_check) and the selfie face match (liveness_v2_face_match) of the submission.
      tags:
      - Liveness & Biometrics
      operationId: getLivenessStatus
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveStatus'
        '401':
          description: Missing or invalid API key
        '404':
          description: Submission not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ConsentRecord:
      type: object
      required:
      - id
      - submissionId
      - purpose
      - policyVersion
      - retentionPeriod
      - method
      - createdAt
      - consentText
      properties:
        id:
          type: string
        submissionId:
          type: string
        purpose:
          type: string
        policyVersion:
          type: string
        retentionPeriod:
          type: string
        method:
          type: string
        createdAt:
          type: string
          format: date-time
        consentText:
          type: string
          description: Snapshot of the exact consent text recorded.
    LiveSelfieRequest:
      type: object
      properties:
        selfie_image:
          type: string
          description: 'Selfie as base64 or a data: URL.'
        selfie_mime:
          type: string
          default: image/jpeg
          description: Accepted but the image is always processed as image/jpeg.
      required:
      - selfie_image
    ConsentStatus:
      type: object
      required:
      - submissionId
      - hasConsent
      - records
      properties:
        submissionId:
          type: string
        hasConsent:
          type: boolean
          description: true only if the PRIMARY subject (subjectRef == submission id) has consented; UBO consent rows do not count.
        records:
          type: array
          items:
            type: object
            required:
            - id
            - purpose
            - policyVersion
            - method
            - createdAt
            - subject
            properties:
              id:
                type: string
              purpose:
                type: string
              policyVersion:
                type: string
              method:
                type: string
              createdAt:
                type: string
                format: date-time
              subject:
                type: string
                enum:
                - primary
                - other
    ConsentRequest:
      type: object
      required:
      - method
      description: Record the subject's biometric consent (BIPA/GDPR) before liveness/face-match. `method` must state honestly how consent was obtained.
      properties:
        method:
          type: string
          example: ui_checkbox
          description: e.g. ui_checkbox, api_explicit_flag.
        purpose:
          type: string
          description: Defaults to the standard biometric-verification purpose.
      example:
        method: ui_checkbox
    ConsentError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        detail:
          type: string
          description: Present on method_required.
    KycLivenessSession:
      type: object
      properties:
        submissionId:
          type: string
        session_id:
          type: string
        session_url:
          type: string
          description: URL the end user opens to complete the IDV/liveness session.
        provider:
          type: string
        status:
          type: string
        expires_at:
          type: string
          format: date-time
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    BioFaceMatchRequest:
      type: object
      properties:
        selfie_b64:
          type: string
          description: 'Selfie as raw base64 or a data: URL.'
        selfie_video_frames:
          type: array
          items:
            type: string
          description: Optional base64 frames (MediaRecorder) for the passive liveness score; defaults to the selfie alone.
        id_document_id:
          type: string
          description: Id of an uploaded passport or id KycDocument of this submission.
      required:
      - selfie_b64
      - id_document_id
    LiveFaceMatchResult:
      type: object
      properties:
        passed:
          type: boolean
        score:
          type: integer
          minimum: 0
          maximum: 100
          description: ArcFace similarity x100.
        threshold:
          type: integer
          description: Pass threshold x100.
        next_step:
          type: string
          enum:
          - review
          - liveness_retry
        error:
          type: string
          description: Present when the face-match worker failed; the check is then set to review.
      required:
      - passed
      - score
      - threshold
      - next_step
    BioFaceMatchResult:
      type: object
      properties:
        matchScore:
          type: number
          description: Face-embedding cosine similarity.
        livenessScore:
          type: number
        decision:
          type: string
          enum:
          - pass
          - fail
          - review
        reasons:
          type: array
          items:
            type: string
            description: e.g. face_match_fail:0.312, liveness_review:0.610
    LiveStatus:
      type: object
      properties:
        submission_id:
          type: string
        liveness_passed:
          type:
          - boolean
          - 'null'
        liveness_score:
          type:
          - number
          - 'null'
        liveness_checked_at:
          type:
          - string
          - 'null'
        selfie_stored:
          type: boolean
        idv_session_status:
          type: string
          description: Status of the liveness_check check, or not_started.
        face_match_status:
          type: string
          description: Status of the liveness_v2_face_match check, or not_started.
        face_match_result:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: 'Stored face-match result: passed, score, model, match_raw, error.'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer