SanctionsKit Source discovery API

openapi: 3.2.0
info:
  title: SanctionsKit Source discovery API
  version: 1.0.0
  description: Explore success and error examples without an account or API key. Recorded examples use isolated synthetic application data; remaining examples are labeled contract fixtures. Potential-match screening is for review. No-match is limited to selected, qualified sources. Sandbox uses synthetic records and is never billed. Each successfully completed subject consumes one allowance unit, including monitoring rescreens. Failed rows and idempotent retries do not consume additional units.
servers:
- url: /api/v1
  description: This site origin; deployment configuration and access rules apply
tags:
- name: Source discovery
paths:
  /sources:
    get:
      operationId: get__sources
      summary: Discover source capabilities, qualification and availability
      tags:
      - Source discovery
      description: 'Required API key scope: sources:read.


        This GET operation has no path parameters, query parameters or request body. Send your bearer API key with sources:read. The returned source IDs are used in screening and monitor request bodies; they are not parameters to this discovery endpoint.'
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '200':
          headers:
            X-Request-Id:
              description: Server-generated request correlation identifier.
              schema:
                type: string
                format: uuid
          description: Successful response. JSON object with the required data key. All properties marked required are present, including keys whose value may be null. Unmarked properties can be omitted; clients should tolerate additional response properties.
          content:
            application/json:
              examples:
                success:
                  summary: Synthetic success example
                  description: Synthetic contract example, validated against the response schema. Invented data; no live customer, provider request, payment, message or source activation.
                  value:
                    data:
                    - id: sandbox-synthetic
                      name: Synthetic example records
                      authority: SanctionsKit sandbox
                      availability: available
                      capabilities:
                      - person
                      - organization
                      rightsStatus: approved
                      category: other
                      qualification:
                        implemented: true
                        fixtureTested: true
                        liveFetchTested: false
                        rightsApproved: true
                        activated: false
                        blockers:
                        - Synthetic fixture only; no government source was fetched or activated.
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/SourceList'
        '400':
          headers:
            X-Request-Id:
              schema:
                type: string
                format: uuid
              description: Server-generated correlation identifier, also returned in error.requestId.
          description: '**invalid_request** — Correct the request fields, resource identifiers, JSON body or query parameters before retrying.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  summary: invalid request
                  description: Synthetic error example. Correct the request fields, resource identifiers, JSON body or query parameters before retrying.
                  value:
                    error:
                      code: invalid_request
                      message: The request is invalid.
                      requestId: 01234567-89ab-4cde-8f01-23456789abcd
        '401':
          headers:
            X-Request-Id:
              schema:
                type: string
                format: uuid
              description: Server-generated correlation identifier, also returned in error.requestId.
            WWW-Authenticate:
              schema:
                type: string
              description: Bearer authentication challenge.
          description: '**authentication_required** — Send Authorization: Bearer with a valid API key. An omitted header can produce authentication_required; invalid supplied credentials produce invalid_api_key.


            **invalid_api_key** — Use an active key for the intended environment.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                authentication_required:
                  summary: authentication required
                  description: 'Synthetic error example. Send Authorization: Bearer with a valid API key. An omitted header can produce authentication_required; invalid supplied credentials produce invalid_api_key.'
                  value:
                    error:
                      code: authentication_required
                      message: Sign in to continue.
                      requestId: 01234567-89ab-4cde-8f01-23456789abcd
                invalid_api_key:
                  summary: invalid api key
                  description: Synthetic error example. Use an active key for the intended environment.
                  value:
                    error:
                      code: invalid_api_key
                      message: The API key is invalid, expired, or revoked.
                      requestId: 01234567-89ab-4cde-8f01-23456789abcd
        '403':
          headers:
            X-Request-Id:
              schema:
                type: string
                format: uuid
              description: Server-generated correlation identifier, also returned in error.requestId.
          description: '**permission_denied** — Ask an organization owner to grant the required role or API-key scope.


            **insufficient_scope** — Use a key with the scope stated in this operation.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                permission_denied:
                  summary: permission denied
                  description: Synthetic error example. Ask an organization owner to grant the required role or API-key scope.
                  value:
                    error:
                      code: permission_denied
                      message: Your role does not allow this action.
                      requestId: 01234567-89ab-4cde-8f01-23456789abcd
                insufficient_scope:
                  summary: insufficient scope
                  description: Synthetic error example. Use a key with the scope stated in this operation.
                  value:
                    error:
                      code: insufficient_scope
                      message: The API key does not grant this action.
                      requestId: 01234567-89ab-4cde-8f01-23456789abcd
        '405':
          headers:
            X-Request-Id:
              schema:
                type: string
                format: uuid
              description: Server-generated correlation identifier, also returned in error.requestId.
            Allow:
              schema:
                type: string
              description: Comma-separated supported HTTP methods.
          description: '**method_not_allowed** — Use a method in the Allow response header. OPTIONS lists supported methods; HEAD follows GET authorization and returns no body.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                method_not_allowed:
                  summary: method not allowed
                  description: Synthetic error example. Use a method in the Allow response header. OPTIONS lists supported methods; HEAD follows GET authorization and returns no body.
                  value:
                    error:
                      code: method_not_allowed
                      message: This method is not supported for this endpoint.
                      requestId: 01234567-89ab-4cde-8f01-23456789abcd
        '413':
          headers:
            X-Request-Id:
              schema:
                type: string
                format: uuid
              description: Server-generated correlation identifier, also returned in error.requestId.
          description: '**response_too_large** — Reduce the requested page size or use the documented segmented case archive. No evidence is silently truncated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                response_too_large:
                  summary: response too large
                  description: Synthetic error example. Reduce the requested page size or use the documented segmented case archive. No evidence is silently truncated.
                  value:
                    error:
                      code: response_too_large
                      message: This response exceeds the size limit. Request a smaller page or a segmented export.
                      requestId: 01234567-89ab-4cde-8f01-23456789abcd
        '429':
          headers:
            X-Request-Id:
              schema:
                type: string
                format: uuid
              description: Server-generated correlation identifier, also returned in error.requestId.
            Retry-After:
              schema:
                type: string
              description: When present, a delay in seconds or an HTTP-date before which the client should not retry. Service-unavailable responses default to a one-second delay unless another safe value is supplied. A usage allowance error may require quota recovery instead of retrying.
          description: '**rate_limited** — Wait for the request window to reset and retry with backoff.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  summary: rate limited
                  description: Synthetic error example. Wait for the request window to reset and retry with backoff.
                  value:
                    error:
                      code: rate_limited
                      message: The per-minute request limit has been reached.
                      requestId: 01234567-89ab-4cde-8f01-23456789abcd
        '500':
          headers:
            X-Request-Id:
              schema:
                type: string
                format: uuid
              description: Server-generated correlation identifier, also returned in error.requestId.
          description: '**internal_error** — Retry with backoff. For writes reuse the same idempotency key and identical input; include requestId when contacting support.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                internal_error:
                  summary: internal error
                  description: Synthetic error example. Retry with backoff. For writes reuse the same idempotency key and identical input; include requestId when contacting support.
                  value:
                    error:
                      code: internal_error
                      message: The request could not be completed.
                      requestId: 01234567-89ab-4cde-8f01-23456789abcd
        '503':
          headers:
            X-Request-Id:
              schema:
                type: string
                format: uuid
              description: Server-generated correlation identifier, also returned in error.requestId.
            Retry-After:
              schema:
                type: string
              description: When present, a delay in seconds or an HTTP-date before which the client should not retry. Service-unavailable responses default to a one-second delay unless another safe value is supplied. A usage allowance error may require quota recovery instead of retrying.
          description: '**temporarily_unavailable** — Honor Retry-After when present and retry with bounded backoff. Follow this endpoint’s retry contract; preserve the same key and input for idempotent writes. Contact support with requestId if the failure persists.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                temporarily_unavailable:
                  summary: temporarily unavailable
                  description: Synthetic error example. Honor Retry-After when present and retry with bounded backoff. Follow this endpoint’s retry contract; preserve the same key and input for idempotent writes. Contact support with requestId if the failure persists.
                  value:
                    error:
                      code: temporarily_unavailable
                      message: The service is temporarily unavailable. Retry shortly.
                      requestId: 01234567-89ab-4cde-8f01-23456789abcd
components:
  schemas:
    SourceList:
      type: array
      items:
        type: object
        required:
        - id
        - name
        - authority
        - availability
        - capabilities
        - rightsStatus
        - category
        properties:
          id:
            type: string
          name:
            type: string
          authority:
            type: string
          availability:
            enum:
            - available
            - disabled
          capabilities:
            type: array
            items:
              type: string
          category:
            enum:
            - financial_sanctions
            - export_control
            - debarment
            - regulatory_enforcement
            - public_office
            - reference
            - other
            - mixed
          rightsStatus:
            enum:
            - approved
            - review_required
            - restricted
          jurisdiction:
            type: string
          homepage:
            type: string
          downloadUrl:
            type: string
          format:
            type: string
          attribution:
            type: string
          termsUrl:
            type: string
          disabledReason:
            type: string
          refreshHours:
            type: integer
            minimum: 0
          parserVersion:
            type: string
          fresh:
            type: boolean
          qualification:
            type: object
            properties:
              implemented:
                type: boolean
              fixtureTested:
                type: boolean
              liveFetchTested:
                type: boolean
              rightsApproved:
                type: boolean
              activated:
                type: boolean
              liveFetchedAt:
                type: string
                format: date-time
              blockers:
                type: array
                items:
                  type: string
            required:
            - implemented
            - fixtureTested
            - liveFetchTested
            - rightsApproved
            - activated
            - blockers
          currentVersion:
            anyOf:
            - type: object
              properties:
                source_id:
                  type: string
                id:
                  type: string
                retrieved_at:
                  type: string
                  format: date-time
                last_checked_at:
                  anyOf:
                  - type: string
                    format: date-time
                  - type: 'null'
                published_at:
                  anyOf:
                  - type: string
                    format: date-time
                  - type: 'null'
                status:
                  type: string
                rights_approved:
                  type: boolean
              required:
              - source_id
              - id
              - retrieved_at
              - status
              - rights_approved
            - type: 'null'
          lastImport:
            anyOf:
            - type: object
              properties:
                source_id:
                  type: string
                id:
                  type: string
                retrieved_at:
                  type: string
                  format: date-time
                last_checked_at:
                  anyOf:
                  - type: string
                    format: date-time
                  - type: 'null'
                published_at:
                  anyOf:
                  - type: string
                    format: date-time
                  - type: 'null'
                status:
                  type: string
                rights_approved:
                  type: boolean
              required:
              - source_id
              - id
              - retrieved_at
              - status
              - rights_approved
            - type: 'null'
    Error:
      type: object
      required:
      - error
      description: Failure envelope for every documented non-2xx API response. No data property is returned. Switch on error.code; messages may change.
      properties:
        error:
          type: object
          required:
          - code
          - message
          - requestId
          properties:
            code:
              type: string
              description: Machine-readable failure code. See this operation’s status-specific examples for codes and recovery.
            message:
              type: string
              description: Human-readable explanation. Do not parse this text to control application behavior.
            requestId:
              type: string
              format: uuid
              description: Server correlation ID, also returned in X-Request-Id. Include this ID in support requests.
            details:
              description: Optional JSON details for client and validation failures. Validation failures return an array of { path, message } issues; other 4xx codes may return a code-specific object. Server failures omit details. Never assume this key is present.
              anyOf:
              - type: array
                maxItems: 50
                items:
                  type: object
                  required:
                  - path
                  - message
                  properties:
                    path:
                      type: string
                      maxLength: 160
                      description: Dot-separated invalid field path, including array indexes.
                    message:
                      type: string
                      maxLength: 300
                      description: Validation problem for this field.
              - type: object
                additionalProperties: true
              - type:
                - string
                - number
                - boolean
                - 'null'
            detailsTruncated:
              type: boolean
              description: True when only the first 50 validation issues are returned. Validation paths and messages are bounded.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sk_test_... or sk_live_...
x-docs-revision: 499779e00214c23622695c6d7114fb3656edf29161460d9f9e9d2ab65d0cf087