infinihash-com Obligations API

openapi: 3.2.0
info:
  title: Infinihash KYC Obligations 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: Obligations
paths:
  /api/obligations:
    get:
      x-route-source:
        file: routes/obligations.js
        method: get
        path: /
      summary: List obligations
      description: Lists this API key's deferred verification obligations, ordered by status then due date. Anything past due is first settled to `lapsed` (reported in `newly_lapsed`). `blocking=true` answers "may this card keep transacting?" by returning only lapsed obligations whose on_lapse is `block` (it overrides `status`).
      tags:
      - Obligations
      operationId: listObligations
      parameters:
      - name: status
        in: query
        required: false
        description: Filter by status.
        schema:
          type: string
          enum:
          - open
          - satisfied
          - lapsed
          - waived
      - name: card_ref
        in: query
        required: false
        description: Filter by partner card token.
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: Filter by obligation type (e.g. dl_image).
        schema:
          type: string
      - name: blocking
        in: query
        required: false
        description: Pass `true` to return only lapsed obligations that block the card.
        schema:
          type: string
          enum:
          - 'true'
      - name: limit
        in: query
        required: false
        description: Max rows (default 100, max 500).
        schema:
          type: integer
          default: 100
          maximum: 500
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Obligations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationList'
        '400':
          description: invalid_status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationError'
        '401':
          description: Missing or invalid API key
          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: query_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/obligations/{id}:
    get:
      x-route-source:
        file: routes/obligations.js
        method: get
        path: /:id
      summary: Get an obligation
      description: Returns one obligation owned by this API key, after settling any past-due obligations to `lapsed`.
      tags:
      - Obligations
      operationId: getObligation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: The obligation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Obligation'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 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: query_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/obligations/{id}/satisfy:
    post:
      x-route-source:
        file: routes/obligations.js
        method: post
        path: /:id/satisfy
      summary: Satisfy an obligation with evidence
      description: Closes the obligation by attaching the uploaded evidence document. A lapsed obligation can still be satisfied (late evidence is accepted and the lapse timestamp is kept). Already satisfied or waived obligations return 409.
      tags:
      - Obligations
      operationId: satisfyObligation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObligationSatisfyRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Obligation satisfied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationResult'
        '400':
          description: document_id_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationError'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: already_satisfied or already_waived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationConflict'
        '429':
          description: Rate limited (global per-IP limit)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: update_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/obligations/{id}/waive:
    post:
      x-route-source:
        file: routes/obligations.js
        method: post
        path: /:id/waive
      summary: Waive an obligation (admin only)
      description: 'ADMIN ONLY: requires the `X-Admin-Secret` header (requireAdmin), not a tenant API key. Closes the obligation without evidence as a compliance override; a written reason of at least 8 characters is mandatory. Pass `api_key_id` to restrict the lookup to one tenant. Failed admin auth returns 403.'
      tags:
      - Obligations
      operationId: waiveObligation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      - name: X-Admin-Secret
        in: header
        required: true
        description: Admin secret.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObligationWaiveRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Obligation waived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationResult'
        '400':
          description: reason_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationError'
        '403':
          description: Admin access required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 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: update_failed, or server_misconfigured when ADMIN_SECRET is unset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /obligations:
    get:
      x-route-source:
        file: routes/obligations.js
        method: get
        path: /
      summary: List obligations
      description: Lists this API key's deferred verification obligations, ordered by status then due date. Anything past due is first settled to `lapsed` (reported in `newly_lapsed`). `blocking=true` answers "may this card keep transacting?" by returning only lapsed obligations whose on_lapse is `block` (it overrides `status`).
      tags:
      - Obligations
      operationId: get_obligations
      parameters:
      - name: status
        in: query
        required: false
        description: Filter by status.
        schema:
          type: string
          enum:
          - open
          - satisfied
          - lapsed
          - waived
      - name: card_ref
        in: query
        required: false
        description: Filter by partner card token.
        schema:
          type: string
      - name: type
        in: query
        required: false
        description: Filter by obligation type (e.g. dl_image).
        schema:
          type: string
      - name: blocking
        in: query
        required: false
        description: Pass `true` to return only lapsed obligations that block the card.
        schema:
          type: string
          enum:
          - 'true'
      - name: limit
        in: query
        required: false
        description: Max rows (default 100, max 500).
        schema:
          type: integer
          default: 100
          maximum: 500
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Obligations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationList'
        '400':
          description: invalid_status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationError'
        '401':
          description: Missing or invalid API key
          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: query_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /obligations/{id}:
    get:
      x-route-source:
        file: routes/obligations.js
        method: get
        path: /:id
      summary: Get an obligation
      description: Returns one obligation owned by this API key, after settling any past-due obligations to `lapsed`.
      tags:
      - Obligations
      operationId: get_obligations_id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: The obligation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Obligation'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 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: query_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /obligations/{id}/satisfy:
    post:
      x-route-source:
        file: routes/obligations.js
        method: post
        path: /:id/satisfy
      summary: Satisfy an obligation with evidence
      description: Closes the obligation by attaching the uploaded evidence document. A lapsed obligation can still be satisfied (late evidence is accepted and the lapse timestamp is kept). Already satisfied or waived obligations return 409.
      tags:
      - Obligations
      operationId: post_obligations_id_satisfy
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObligationSatisfyRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Obligation satisfied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationResult'
        '400':
          description: document_id_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationError'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: already_satisfied or already_waived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationConflict'
        '429':
          description: Rate limited (global per-IP limit)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: update_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /obligations/{id}/waive:
    post:
      x-route-source:
        file: routes/obligations.js
        method: post
        path: /:id/waive
      summary: Waive an obligation (admin only)
      description: 'ADMIN ONLY: requires the `X-Admin-Secret` header (requireAdmin), not a tenant API key. Closes the obligation without evidence as a compliance override; a written reason of at least 8 characters is mandatory. Pass `api_key_id` to restrict the lookup to one tenant. Failed admin auth returns 403.'
      tags:
      - Obligations
      operationId: post_obligations_id_waive
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      - name: X-Admin-Secret
        in: header
        required: true
        description: Admin secret.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObligationWaiveRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Obligation waived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationResult'
        '400':
          description: reason_required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObligationError'
        '403':
          description: Admin access required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 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: update_failed, or server_misconfigured when ADMIN_SECRET is unset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ObligationResult:
      type: object
      required:
      - ok
      - obligation
      properties:
        ok:
          type: boolean
          enum:
          - true
        obligation:
          $ref: '#/components/schemas/Obligation'
    ObligationWaiveRequest:
      type: object
      required:
      - reason
      properties:
        reason:
          type: string
          minLength: 8
          description: Written justification, at least 8 characters (truncated to 1000 on storage).
        api_key_id:
          type: string
          description: 'Optional: restrict the lookup to obligations of this tenant API key.'
    ObligationSatisfyRequest:
      type: object
      required:
      - document_id
      properties:
        document_id:
          type: string
          maxLength: 255
          description: Id of the uploaded evidence document (truncated to 255 chars).
        note:
          type: string
          maxLength: 1000
          description: Optional note (truncated to 1000 chars).
    ObligationConflict:
      type: object
      required:
      - error
      - obligation
      properties:
        error:
          type: string
          enum:
          - already_satisfied
          - already_waived
        obligation:
          $ref: '#/components/schemas/Obligation'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    ObligationError:
      type: object
      required:
      - error
      properties:
        error:
          type: string
        detail:
          type: string
        allowed:
          type: array
          items:
            type: string
          description: Valid statuses (on invalid_status).
    Obligation:
      type: object
      description: A deferred verification obligation (e.g. a driving-licence photo owed after a card crosses a spend threshold). Lapse is evaluated lazily on read.
      required:
      - id
      - type
      - status
      - on_lapse
      - due_by
      - blocking
      - overdue_seconds
      properties:
        id:
          type: string
        type:
          type: string
          description: Obligation type, currently dl_image.
        status:
          type: string
          enum:
          - open
          - satisfied
          - lapsed
          - waived
        card_ref:
          type:
          - string
          - 'null'
        transaction_ref:
          type:
          - string
          - 'null'
        submission_id:
          type:
          - string
          - 'null'
        decision_id:
          type:
          - string
          - 'null'
        amount:
          type:
          - number
          - 'null'
        card_cumulative_total:
          type:
          - number
          - 'null'
        ruleset_version:
          type: integer
        reason_code:
          type:
          - string
          - 'null'
        on_lapse:
          type: string
          description: 'Tenant decision on lapse: flag | block | escalate.'
        due_by:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type:
          - string
          - 'null'
          format: date-time
        satisfied_at:
          type:
          - string
          - 'null'
          format: date-time
        document_id:
          type:
          - string
          - 'null'
        satisfied_note:
          type:
          - string
          - 'null'
        lapsed_at:
          type:
          - string
          - 'null'
          format: date-time
        blocking:
          type: boolean
          description: 'Derived: status is lapsed and on_lapse is block.'
        overdue_seconds:
          type: integer
          description: 'Derived: seconds past due_by while still open; 0 otherwise.'
    ObligationList:
      type: object
      required:
      - count
      - newly_lapsed
      - obligations
      properties:
        count:
          type: integer
        newly_lapsed:
          type: integer
          description: Open obligations that were moved to lapsed by this call.
        obligations:
          type: array
          items:
            $ref: '#/components/schemas/Obligation'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer