infinihash-com Verification API

openapi: 3.2.0
info:
  title: Infinihash KYC Verification 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: Verification
paths:
  /verify:
    post:
      x-route-source:
        file: routes/verify.js
        method: post
        path: /
      summary: Verify an identity document
      description: 'User-facing document verification: classifies (if needed) and extracts an identity document and returns a pass/fail with the key fields. Nothing is stored. Mounted at the root only; /history is an alias of /verify for the POST route. Authentication is not the standard middleware: send either an API key (X-API-Key / Bearer) or an infinihash SSO token (Authorization: Bearer or the ih_token cookie); otherwise 401.'
      tags:
      - Verification
      operationId: verifyDocument
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
      security: []
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResult'
        '400':
          description: data / mime_type missing, unsupported file type, file over 10 MB, or the document could not be classified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Extraction failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '500':
          description: Verification failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      x-route-source:
        file: routes/verify.js
        method: get
        path: /
      summary: Verification history (stub)
      description: 'Placeholder for the user''s recent verifications: always returns an empty array for an authenticated caller. Only an infinihash SSO token (Authorization: Bearer or ih_token cookie) is accepted here, not an API key; otherwise 401. Mounted at the root only.'
      tags:
      - Verification
      operationId: verifyHistoryRoot
      security: []
      responses:
        '200':
          description: Always an empty array for now
          content:
            application/json:
              schema:
                type: array
                items: {}
                maxItems: 0
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
  /history:
    post:
      x-route-source:
        file: routes/verify.js
        method: post
        path: /
      summary: Verify an identity document
      description: 'User-facing document verification: classifies (if needed) and extracts an identity document and returns a pass/fail with the key fields. Nothing is stored. Mounted at the root only; /history is an alias of /verify for the POST route. Authentication is not the standard middleware: send either an API key (X-API-Key / Bearer) or an infinihash SSO token (Authorization: Bearer or the ih_token cookie); otherwise 401.'
      tags:
      - Verification
      operationId: verifyDocumentViaHistory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
      security: []
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyResult'
        '400':
          description: data / mime_type missing, unsupported file type, file over 10 MB, or the document could not be classified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Extraction failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '500':
          description: Verification failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      x-route-source:
        file: routes/verify.js
        method: get
        path: /
      summary: Verification history (stub)
      description: 'Placeholder for the user''s recent verifications: always returns an empty array for an authenticated caller. Only an infinihash SSO token (Authorization: Bearer or ih_token cookie) is accepted here, not an API key; otherwise 401. Mounted at the root only.'
      tags:
      - Verification
      operationId: verifyHistoryAlias
      security: []
      responses:
        '200':
          description: Always an empty array for now
          content:
            application/json:
              schema:
                type: array
                items: {}
                maxItems: 0
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
  /verify-signatory:
    post:
      x-route-source:
        file: routes/verify-signatory.js
        method: post
        path: /
      summary: Gate a signatory on a completed KYC
      description: 'Decides whether a named person may sign. With kyc_token: checks the completed KYC case (risk score and name match against the case entity name) and answers 200. Without it: extracts the supplied ID document, opens a new individual KYC case and answers 202 with verified:false; run the case, then call again with its id as kyc_token. Rate limited to 10 requests/min per API key.'
      tags:
      - Verification
      operationId: post_verify_signatory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifySignatoryRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Gate decision for an existing KYC case
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifySignatoryResult'
        '202':
          description: 'No KYC yet: a case was created'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifySignatoryPending'
        '400':
          description: party_name missing / too long, or neither kyc_token nor doc_b64 given, or document over 10 MB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
        '404':
          description: KYC case not found or not owned by this API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: KYC case not yet complete (status and message in body), or it has no risk score
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Document extraction failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/verify-signatory:
    post:
      x-route-source:
        file: routes/verify-signatory.js
        method: post
        path: /
      summary: Gate a signatory on a completed KYC
      description: 'Decides whether a named person may sign. With kyc_token: checks the completed KYC case (risk score and name match against the case entity name) and answers 200. Without it: extracts the supplied ID document, opens a new individual KYC case and answers 202 with verified:false; run the case, then call again with its id as kyc_token. Rate limited to 10 requests/min per API key.'
      tags:
      - Verification
      operationId: verifySignatory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifySignatoryRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Gate decision for an existing KYC case
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifySignatoryResult'
        '202':
          description: 'No KYC yet: a case was created'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifySignatoryPending'
        '400':
          description: party_name missing / too long, or neither kyc_token nor doc_b64 given, or document over 10 MB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
        '404':
          description: KYC case not found or not owned by this API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: KYC case not yet complete (status and message in body), or it has no risk score
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Document extraction failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    VerifySignatoryResult:
      type: object
      properties:
        verified:
          type: boolean
          description: true only if the name matches (>= 0.70) AND the case risk score is below 70.
        kyc_case_id:
          type: string
        kyc_score:
          type: number
        kyc_status:
          type: string
        match_confidence:
          type: number
          description: 0-1 name similarity, 2 decimals.
        match_verdict:
          type: string
          enum:
          - strong_match
          - fuzzy_match
          - mismatch
        matched_name:
          type: string
        message:
          type: string
    VerifyResult:
      type: object
      properties:
        status:
          type: string
          enum:
          - pass
          - fail
          description: fail when nothing was extracted or confidence < 0.4.
        result:
          type: string
          enum:
          - pass
          - fail
          description: Same as status.
        full_name:
          type: string
        document_type:
          type: string
        document_number:
          type: string
        date_of_birth:
          type: string
        nationality:
          type: string
        expiry_date:
          type: string
        confidence:
          type:
          - number
          - 'null'
        warnings:
          type: array
          items:
            type: string
        raw_data:
          type: object
          additionalProperties: true
          description: Everything the extractor read from the document.
      description: String fields hold "—" when the value is unknown.
    VerifySignatoryRequest:
      type: object
      properties:
        party_name:
          type: string
          maxLength: 300
          description: Name of the person who is to sign.
        kyc_token:
          type: string
          description: Id of a COMPLETE KYC submission of this API key to use as the gate.
        doc_b64:
          type: string
          format: byte
          description: Base64 ID document, max 10 MB. Used only when kyc_token is absent.
      required:
      - party_name
      description: 'Exactly one route is taken: with kyc_token the existing case is checked; otherwise doc_b64 is required and a new KYC case is created.'
    VerifyRequest:
      type: object
      properties:
        doc_type:
          type: string
          enum:
          - ''
          - auto
          - passport
          - national_id
          - drivers_license
          - driver_license
          - residence_permit
          - id
          - formation
          default: ''
          description: Empty or "auto" classifies the document; unknown values are treated as auto.
        mime_type:
          type: string
          enum:
          - image/jpeg
          - image/png
          - image/webp
          - application/pdf
        data:
          type: string
          format: byte
          description: Base64 file content, max 10 MB decoded.
        first_name:
          type: string
          description: Optional hint; used to fill full_name when the document yields none.
        last_name:
          type: string
          description: Optional hint.
        dob:
          type: string
          description: Optional hint (YYYY-MM-DD); fallback for date_of_birth.
        nationality:
          type: string
          description: Optional hint (ISO-2); fallback for nationality.
      required:
      - mime_type
      - data
    VerifySignatoryPending:
      type: object
      properties:
        verified:
          type: boolean
          enum:
          - false
        kyc_case_id:
          type: string
        message:
          type: string
        _links:
          type: object
          properties:
            run:
              type: string
            status:
              type: string
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer