infinihash-com SAR API

openapi: 3.2.0
info:
  title: Infinihash KYC SAR 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: SAR
paths:
  /sar:
    post:
      x-route-source:
        file: routes/sar.js
        method: post
        path: /
      summary: Create a SAR alert
      description: Creates a suspicious-activity alert in stage `generated` for this API key.
      tags:
      - SAR
      operationId: createSar
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SarCreateRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '201':
          description: Alert created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SarAlert'
        '400':
          description: alertType is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      x-route-source:
        file: routes/sar.js
        method: get
        path: /
      summary: List SAR alerts
      description: Lists this API key's SAR alerts, newest first. `total` is the number of alerts in this page, not the overall count.
      tags:
      - SAR
      operationId: listSar
      parameters:
      - name: stage
        in: query
        required: false
        description: Filter by stage.
        schema:
          type: string
          enum:
          - generated
          - under_review
          - filed
          - closed
      - name: priority
        in: query
        required: false
        description: Filter by exact priority value.
        schema:
          type: string
      - name: alertType
        in: query
        required: false
        description: Filter by exact alert type.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Page size (default 50, max 200).
        schema:
          type: integer
          default: 50
          maximum: 200
      - name: offset
        in: query
        required: false
        description: Rows to skip.
        schema:
          type: integer
          default: 0
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Alerts page
          content:
            application/json:
              schema:
                type: object
                required:
                - alerts
                - total
                properties:
                  alerts:
                    type: array
                    items:
                      $ref: '#/components/schemas/SarAlert'
                  total:
                    type: integer
                    description: Count of alerts returned in this response.
        '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: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sar/{id}:
    get:
      x-route-source:
        file: routes/sar.js
        method: get
        path: /:id
      summary: Get a SAR alert
      description: Returns one SAR alert owned by this API key.
      tags:
      - SAR
      operationId: getSar
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: The alert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SarAlert'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Alert 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: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sar/{id}/stage:
    patch:
      x-route-source:
        file: routes/sar.js
        method: patch
        path: /:id/stage
      summary: Advance a SAR alert stage
      description: Sets the alert stage (generated, under_review, filed, closed) and optionally assignedTo / analystNotes. Moving to `filed` requires `filingRef`; moving to `closed` requires `closureReason`. Any stage can be set from any stage (no transition ordering is enforced).
      tags:
      - SAR
      operationId: updateSarStage
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: KYC submission id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SarStageRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Updated alert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SarAlert'
        '400':
          description: Invalid stage, or filingRef / closureReason required for the chosen stage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sar/{sarId}/narrative:
    post:
      x-route-source:
        file: routes/sarnarrative.js
        method: post
        path: /:sarId/narrative
      summary: Add a SAR narrative version
      description: Appends a new narrative draft to a SAR owned by this API key; the version number increments automatically. Also reachable at /team/{sarId}/narrative.
      tags:
      - SAR
      operationId: createSarNarrative
      parameters:
      - name: sarId
        in: path
        required: true
        schema:
          type: string
        description: sarId
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SarNarrativeRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '201':
          description: Narrative created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SarNarrative'
        '400':
          description: narrative is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: SAR 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: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      x-route-source:
        file: routes/sarnarrative.js
        method: get
        path: /:sarId/narrative
      summary: List SAR narrative versions
      description: Lists every narrative draft for a SAR owned by this API key, newest version first. Also reachable at /team/{sarId}/narrative.
      tags:
      - SAR
      operationId: listSarNarratives
      parameters:
      - name: sarId
        in: path
        required: true
        schema:
          type: string
        description: sarId
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Narratives
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SarNarrative'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: SAR 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: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sar/{sarId}/narrative/{narId}/approve:
    patch:
      x-route-source:
        file: routes/sarnarrative.js
        method: patch
        path: /:sarId/narrative/:narId/approve
      summary: Approve a SAR narrative
      description: Marks the narrative approved and stamps approvedAt. No body. Idempotent (re-approving refreshes approvedAt). Also reachable at /team/{sarId}/narrative/{narId}/approve.
      tags:
      - SAR
      operationId: approveSarNarrative
      parameters:
      - name: sarId
        in: path
        required: true
        schema:
          type: string
        description: sarId
      - name: narId
        in: path
        required: true
        schema:
          type: string
        description: narId
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: The approved narrative
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SarNarrative'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: SAR not found, or narrative 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: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /team/{sarId}/narrative:
    post:
      x-route-source:
        file: routes/sarnarrative.js
        method: post
        path: /:sarId/narrative
      summary: Add a SAR narrative version
      description: Appends a new narrative draft to a SAR owned by this API key; the version number increments automatically. Also reachable at /team/{sarId}/narrative.
      tags:
      - SAR
      operationId: post_team_sarId_narrative
      parameters:
      - name: sarId
        in: path
        required: true
        schema:
          type: string
        description: sarId
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SarNarrativeRequest'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '201':
          description: Narrative created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SarNarrative'
        '400':
          description: narrative is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: SAR 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: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      x-route-source:
        file: routes/sarnarrative.js
        method: get
        path: /:sarId/narrative
      summary: List SAR narrative versions
      description: Lists every narrative draft for a SAR owned by this API key, newest version first. Also reachable at /team/{sarId}/narrative.
      tags:
      - SAR
      operationId: get_team_sarId_narrative
      parameters:
      - name: sarId
        in: path
        required: true
        schema:
          type: string
        description: sarId
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Narratives
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SarNarrative'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: SAR 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: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /team/{sarId}/narrative/{narId}/approve:
    patch:
      x-route-source:
        file: routes/sarnarrative.js
        method: patch
        path: /:sarId/narrative/:narId/approve
      summary: Approve a SAR narrative
      description: Marks the narrative approved and stamps approvedAt. No body. Idempotent (re-approving refreshes approvedAt). Also reachable at /team/{sarId}/narrative/{narId}/approve.
      tags:
      - SAR
      operationId: patch_team_sarId_narrative_narId_approve
      parameters:
      - name: sarId
        in: path
        required: true
        schema:
          type: string
        description: sarId
      - name: narId
        in: path
        required: true
        schema:
          type: string
        description: narId
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: The approved narrative
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SarNarrative'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: SAR not found, or narrative 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: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SarAlert:
      type: object
      required:
      - id
      - apiKeyId
      - alertType
      - stage
      - priority
      - createdAt
      - updatedAt
      description: A suspicious-activity alert tracked through generated -> under_review -> filed -> closed.
      properties:
        id:
          type: string
        apiKeyId:
          type: string
        alertType:
          type: string
        stage:
          type: string
          enum:
          - generated
          - under_review
          - filed
          - closed
        priority:
          type: string
          description: Free-form priority (default medium).
        subject:
          type:
          - string
          - 'null'
        submissionId:
          type:
          - string
          - 'null'
        transactionRefs:
          type:
          - string
          - 'null'
          description: Comma-joined transaction references.
        autoFlags:
          type:
          - string
          - 'null'
          description: Comma-joined automatic flags.
        assignedTo:
          type:
          - string
          - 'null'
        analystNotes:
          type:
          - string
          - 'null'
        filingRef:
          type:
          - string
          - 'null'
        filedAt:
          type:
          - string
          - 'null'
          format: date-time
        closureReason:
          type:
          - string
          - 'null'
        closedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    SarCreateRequest:
      type: object
      required:
      - alertType
      properties:
        alertType:
          type: string
        priority:
          type: string
          default: medium
          description: Free-form (not validated); default medium.
        subject:
          type: string
          description: Subject of the alert (person/entity).
        submissionId:
          type: string
          description: Related KYC submission id (stored as given; not ownership-checked).
        transactionRefs:
          description: Transaction references, array or string; arrays are comma-joined on storage.
          oneOf:
          - type: array
            items:
              type: string
          - type: string
        autoFlags:
          description: Automatic flags, array or string; arrays are comma-joined on storage.
          oneOf:
          - type: array
            items:
              type: string
          - type: string
    SarNarrativeRequest:
      type: object
      required:
      - narrative
      properties:
        narrative:
          type: string
          description: Narrative text.
        draftedBy:
          type: string
          description: Author (person or system) of this draft.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    SarStageRequest:
      type: object
      required:
      - stage
      properties:
        stage:
          type: string
          enum:
          - generated
          - under_review
          - filed
          - closed
        filingRef:
          type: string
          description: Regulator filing reference. REQUIRED when stage is `filed` (sets filedAt).
        closureReason:
          type: string
          description: REQUIRED when stage is `closed` (sets closedAt).
        assignedTo:
          type: string
          description: Analyst assignment (updated only when non-empty).
        analystNotes:
          type: string
          description: Analyst notes (updated only when non-empty).
    SarNarrative:
      type: object
      required:
      - id
      - sarId
      - narrative
      - version
      - approved
      - createdAt
      properties:
        id:
          type: string
        sarId:
          type: string
        narrative:
          type: string
        version:
          type: integer
          description: Auto-incremented per SAR starting at 1.
        draftedBy:
          type:
          - string
          - 'null'
        approved:
          type: boolean
        approvedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer