infinihash-com Policy API

openapi: 3.2.0
info:
  title: Infinihash KYC Policy 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: Policy
paths:
  /kyc/policy/evaluate:
    post:
      x-route-source:
        file: routes/stepup-policy.js
        method: post
        path: /policy/evaluate
      summary: Evaluate a transaction against the step-up policy
      description: Decides which verification step (none, sms_confirmation, dl_number, dl_image, liveness, full_idv) a transaction needs, using the tenant's active ruleset (or the Infinihash default). Override rules can only raise the requirement; otherwise the first matching rule wins, then the ruleset default. A storage error fails closed to full_idv. The decision is logged; a `dl_image` outcome records a dated obligation (one open obligation per card_ref). 503 `obligation_unrecordable` is returned if that obligation cannot be saved.
      tags:
      - Policy
      operationId: post_kyc_policy_evaluate
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyEvaluateRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Decision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDecision'
        '401':
          description: Missing API key, or invalid or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '503':
          description: Decision made but the deferred obligation could not be persisted; retry
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
                    enum:
                    - obligation_unrecordable
                  detail:
                    type: string
                  verification_required:
                    $ref: '#/components/schemas/PolicyOutcome'
                  reason_code:
                    type: string
  /kyc/policy:
    get:
      x-route-source:
        file: routes/stepup-policy.js
        method: get
        path: /policy
      summary: Get the tenant's active step-up ruleset
      description: Returns the active ruleset for the calling API key; `source` is 'tenant' for a published ruleset or 'default' for the Infinihash baseline.
      tags:
      - Policy
      operationId: get_kyc_policy
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Active ruleset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyActive'
        '401':
          description: Missing API key, or invalid or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: ruleset_unavailable (storage error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      x-route-source:
        file: routes/stepup-policy.js
        method: put
        path: /policy
      summary: Publish a new step-up ruleset version (admin)
      description: 'Publishes a new immutable ruleset version for an API key and deactivates the previous one. The ruleset is validated first; its version must be greater than the key''s latest version. Admin-only: requires the X-Admin-Secret header (not an API key).'
      tags:
      - Policy
      operationId: put_kyc_policy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyPublishRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '201':
          description: Ruleset published
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyPublished'
        '400':
          description: api_key_id required, or invalid_ruleset (with `details` listing the validation errors)
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
                  details:
                    type: array
                    items:
                      type: string
        '403':
          description: Missing or wrong X-Admin-Secret header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: version_not_increasing
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
                  current:
                    type: integer
                    description: Latest published version.
        '500':
          description: publish_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /kyc/policy/decisions:
    get:
      x-route-source:
        file: routes/stepup-policy.js
        method: get
        path: /policy/decisions
      summary: List recent step-up decisions
      description: Returns the calling key's most recent policy decisions (audit trail), newest first.
      tags:
      - Policy
      operationId: get_kyc_policy_decisions
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          maximum: 200
        description: Maximum decisions to return (default 50, capped at 200).
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Recent decisions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDecisionList'
        '401':
          description: Missing API key, or invalid or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: query_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/kyc/policy/evaluate:
    post:
      x-route-source:
        file: routes/stepup-policy.js
        method: post
        path: /policy/evaluate
      summary: Evaluate a transaction against the step-up policy
      description: Decides which verification step (none, sms_confirmation, dl_number, dl_image, liveness, full_idv) a transaction needs, using the tenant's active ruleset (or the Infinihash default). Override rules can only raise the requirement; otherwise the first matching rule wins, then the ruleset default. A storage error fails closed to full_idv. The decision is logged; a `dl_image` outcome records a dated obligation (one open obligation per card_ref). 503 `obligation_unrecordable` is returned if that obligation cannot be saved.
      tags:
      - Policy
      operationId: evaluateStepupPolicy
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyEvaluateRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Decision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDecision'
        '401':
          description: Missing API key, or invalid or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '503':
          description: Decision made but the deferred obligation could not be persisted; retry
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
                    enum:
                    - obligation_unrecordable
                  detail:
                    type: string
                  verification_required:
                    $ref: '#/components/schemas/PolicyOutcome'
                  reason_code:
                    type: string
  /api/kyc/policy:
    get:
      x-route-source:
        file: routes/stepup-policy.js
        method: get
        path: /policy
      summary: Get the tenant's active step-up ruleset
      description: Returns the active ruleset for the calling API key; `source` is 'tenant' for a published ruleset or 'default' for the Infinihash baseline.
      tags:
      - Policy
      operationId: getStepupPolicy
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Active ruleset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyActive'
        '401':
          description: Missing API key, or invalid or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: ruleset_unavailable (storage error)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      x-route-source:
        file: routes/stepup-policy.js
        method: put
        path: /policy
      summary: Publish a new step-up ruleset version (admin)
      description: 'Publishes a new immutable ruleset version for an API key and deactivates the previous one. The ruleset is validated first; its version must be greater than the key''s latest version. Admin-only: requires the X-Admin-Secret header (not an API key).'
      tags:
      - Policy
      operationId: publishStepupPolicy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicyPublishRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '201':
          description: Ruleset published
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyPublished'
        '400':
          description: api_key_id required, or invalid_ruleset (with `details` listing the validation errors)
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
                  details:
                    type: array
                    items:
                      type: string
        '403':
          description: Missing or wrong X-Admin-Secret header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: version_not_increasing
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
                  current:
                    type: integer
                    description: Latest published version.
        '500':
          description: publish_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/kyc/policy/decisions:
    get:
      x-route-source:
        file: routes/stepup-policy.js
        method: get
        path: /policy/decisions
      summary: List recent step-up decisions
      description: Returns the calling key's most recent policy decisions (audit trail), newest first.
      tags:
      - Policy
      operationId: listStepupDecisions
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          maximum: 200
        description: Maximum decisions to return (default 50, capped at 200).
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Recent decisions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDecisionList'
        '401':
          description: Missing API key, or invalid or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: query_failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    PolicyObligation:
      type: object
      required:
      - id
      - type
      - status
      - due_by
      - on_lapse
      - card_ref
      - existing
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - dl_image
        status:
          type: string
          description: open on creation (or the status of the existing open obligation).
        due_by:
          type: string
          format: date-time
        on_lapse:
          type: string
          enum:
          - flag
          - block
          - escalate
        card_ref:
          type:
          - string
          - 'null'
        existing:
          type: boolean
          description: true when an already-open obligation for this card was returned instead of creating a new one.
    PolicyRuleset:
      type: object
      required:
      - version
      - default
      - rules
      properties:
        version:
          type: integer
          minimum: 1
        default:
          $ref: '#/components/schemas/PolicyOutcome'
        rules:
          type: array
          items:
            $ref: '#/components/schemas/PolicyRule'
        obligations:
          type: object
          description: Deferred-obligation config, keyed by obligation type. Only `dl_image` is allowed.
          properties:
            dl_image:
              type: object
              properties:
                due_hours:
                  type: number
                  description: Default 48.
                  exclusiveMinimum: 0
                on_lapse:
                  type: string
                  enum:
                  - flag
                  - block
                  - escalate
                  description: Default block.
          additionalProperties: false
    PolicyDecisionRecord:
      type: object
      properties:
        id:
          type: string
        apiKeyId:
          type: string
        submissionId:
          type:
          - string
          - 'null'
        rulesetVersion:
          type: integer
        input:
          type: string
          description: JSON-encoded request facts (truncated to 4000 chars).
        outcome:
          $ref: '#/components/schemas/PolicyOutcome'
        reasonCode:
          type: string
        matchedRule:
          type:
          - string
          - 'null'
        createdAt:
          type: string
          format: date-time
    PolicyRule:
      type: object
      required:
      - id
      - when
      - then
      properties:
        id:
          type: string
          description: Unique within the ruleset.
        when:
          type: object
          additionalProperties: true
          description: field -> condition, ALL must hold. A condition is a scalar (equality) or an object of operators eq, ne, in, not_in, exists, gt, gte, lt, lte. Unknown operators never match.
        then:
          $ref: '#/components/schemas/PolicyOutcome'
        reason:
          type: string
          description: Reason code reported when this rule matches (e.g. P01).
        override:
          type: boolean
          description: Override rules are evaluated first and can only raise the requirement; the highest matching override wins.
    PolicyDecisionList:
      type: object
      required:
      - count
      - decisions
      properties:
        count:
          type: integer
        decisions:
          type: array
          items:
            $ref: '#/components/schemas/PolicyDecisionRecord'
    PolicyPublishRequest:
      type: object
      required:
      - api_key_id
      - ruleset
      properties:
        api_key_id:
          type: string
          description: API key the ruleset is published to.
        ruleset:
          allOf:
          - $ref: '#/components/schemas/PolicyRuleset'
          description: Version must be strictly greater than the key's latest version.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    PolicyOutcome:
      type: string
      enum:
      - none
      - sms_confirmation
      - dl_number
      - dl_image
      - liveness
      - full_idv
      description: Verification step required. Ordered from least to most restrictive.
    PolicyDecision:
      type: object
      required:
      - verification_required
      - reason_code
      - matched_rule
      - ruleset_version
      - evaluated_at
      - fail_closed
      - obligation
      - ruleset_source
      properties:
        verification_required:
          $ref: '#/components/schemas/PolicyOutcome'
        reason_code:
          type: string
          description: P00 default, P01-P08 rule reasons (custom rules may set others), P99 fail-closed.
        matched_rule:
          type:
          - string
          - 'null'
          description: Id of the rule that matched, null when the ruleset default applied.
        ruleset_version:
          type:
          - integer
          - 'null'
        evaluated_at:
          type: string
          format: date-time
        fail_closed:
          type: boolean
          description: true when evaluation failed and the most restrictive outcome (full_idv) was returned.
        obligation:
          allOf:
          - $ref: '#/components/schemas/PolicyObligation'
          description: Deferred obligation recorded for a dl_image outcome; null otherwise.
        ruleset_source:
          type: string
          enum:
          - default
          - tenant
          - error
        errors:
          type: array
          items:
            type: string
          description: Present on fail-closed decisions caused by an invalid ruleset or evaluation error.
    PolicyEvaluateRequest:
      type: object
      additionalProperties: true
      description: Transaction facts evaluated against the active ruleset. Rule `when` clauses may reference ANY field, so the object is open; the fields below are the ones the default ruleset and the handler use.
      properties:
        amount:
          type: number
        channel:
          type: string
          description: e.g. 'ecom' or 'pos'.
        cumulative_24h:
          type: number
        verification_age_days:
          type: number
        kyt_risk_level:
          type: string
          description: e.g. high or critical triggers step-up in the default ruleset.
        sanctions_hit:
          type: boolean
        card_ref:
          type: string
          description: Card identifier; obligations are de-duplicated per card (max 255 chars).
        transaction_ref:
          type: string
        submission_id:
          type: string
        card_cumulative_total:
          type: number
        dl_on_file:
          type: boolean
          description: Whether a driving licence is already held. When omitted it is derived from the obligation ledger by card_ref.
    PolicyActive:
      type: object
      required:
      - source
      - ruleset
      properties:
        source:
          type: string
          enum:
          - default
          - tenant
        ruleset:
          $ref: '#/components/schemas/PolicyRuleset'
    PolicyPublished:
      type: object
      required:
      - ok
      - id
      - version
      properties:
        ok:
          type: boolean
          enum:
          - true
        id:
          type: string
        version:
          type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer