> ## Documentation Index
> Fetch the complete documentation index at: https://docs-attestly.code4source.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Look up an identifier across all subject-register sources

> Accepts a typed identifier (``{ type, value }``) and returns every matching entry across all registered ``subject_register`` sources (sanctions lists, ownership registers, etc.). No compliance verdict is applied — callers wire their own downstream logic.

Response content is negotiated via the ``Accept`` header:
- ``application/json`` (default) — ``StandardResponse[SubjectsResponse]``.
- ``application/x-ndjson`` — server-side fan-out streamed as NDJSON, one frame per source completion (``meta``, then ``source`` per candidate, then ``summary``).



## OpenAPI

````yaml /openapi.json post /v1/subjects
openapi: 3.0.3
info:
  description: >-
    Geographic compliance API — evaluates polygons against authoritative
    environmental and regulatory datasets and returns deterministic, audit-ready
    verdicts.
  title: Attestly API
  version: 1.0.0
servers: []
security: []
paths:
  /v1/subjects:
    post:
      tags:
        - Subjects
      summary: Look up an identifier across all subject-register sources
      description: >-
        Accepts a typed identifier (``{ type, value }``) and returns every
        matching entry across all registered ``subject_register`` sources
        (sanctions lists, ownership registers, etc.). No compliance verdict is
        applied — callers wire their own downstream logic.


        Response content is negotiated via the ``Accept`` header:

        - ``application/json`` (default) —
        ``StandardResponse[SubjectsResponse]``.

        - ``application/x-ndjson`` — server-side fan-out streamed as NDJSON, one
        frame per source completion (``meta``, then ``source`` per candidate,
        then ``summary``).
      operationId: find_subjects_v1_subjects_post
      parameters:
        - in: header
          name: accept
          required: false
          schema:
            nullable: true
            title: Accept
            type: string
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            nullable: true
            title: Idempotency-Key
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubjectsRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/SubjectsResponse'
                  errors:
                    description: >-
                      Non-fatal warnings or field-level errors (empty on full
                      success)
                    items:
                      $ref: '#/components/schemas/FieldWarning'
                    title: Errors
                    type: array
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                  - data
                title: StandardResponse[SubjectsResponse]
                type: object
            application/x-ndjson:
              schema:
                title: NDJSON stream
                type: string
          description: Matches returned.
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Malformed request body.
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Missing or invalid JWT token
        '402':
          description: User subscription is inactive or past due
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Authorization failed.
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Resource not found.
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Resource conflict.
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Request body failed schema validation
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Rate limit exceeded
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
          description: Unexpected server error.
      security:
        - HTTPBearer: []
components:
  schemas:
    SubjectsRequest:
      additionalProperties: false
      properties:
        input:
          $ref: '#/components/schemas/SubjectInput'
          description: User-supplied identifier for the lookup. Required.
        match_op:
          $ref: '#/components/schemas/MatchOp'
          default: equals
          description: >-
            Matching operator applied against the identifier value. ``equals``
            performs an exact case-insensitive match on the canonicalized value.
            ``ilike`` performs a SQL ``ILIKE`` pattern match (supports ``%``
            wildcards).
        reference_id:
          description: Optional caller-provided reference identifier for audit/trace.
          maxLength: 128
          nullable: true
          title: Reference Id
          type: string
        subject_source:
          description: >-
            Pin the lookup to a specific subject-register source name (e.g.
            ``'ofac_sdn'``). When absent, all registered ``subject_register``
            sources are searched.
          maxLength: 64
          nullable: true
          title: Subject Source
          type: string
      required:
        - input
      title: SubjectsRequest
      type: object
    SubjectsResponse:
      properties:
        matches:
          items:
            $ref: '#/components/schemas/SubjectMatchHit'
          title: Matches
          type: array
        reference_id:
          nullable: true
          title: Reference Id
          type: string
        subject_check:
          $ref: '#/components/schemas/ReferenceAreasCheckStatus'
          default: ok
      title: SubjectsResponse
      type: object
    FieldWarning:
      properties:
        field:
          description: Dot-notation path to the field that produced the warning
          nullable: true
          title: Field
          type: string
        message:
          description: Human-readable explanation of the warning
          title: Message
          type: string
        type:
          description: Machine-readable warning type
          nullable: true
          title: Type
          type: string
      required:
        - message
      title: FieldWarning
      type: object
    Meta:
      properties:
        api_version:
          default: v1
          description: API version string
          title: Api Version
          type: string
        lint:
          description: >-
            Advisory lint warnings from the ruleset linter. Populated only when
            `?lint=true` was passed on the request. Absent otherwise — the
            envelope is byte-equivalent to the pre-linter baseline.
          items:
            $ref: '#/components/schemas/LintWarningResponse'
          nullable: true
          title: Lint
          type: array
        mode:
          description: >-
            Key mode the request was authenticated under: ``test`` (sandbox, no
            billing) or ``live`` (full billing path). Mirrors the
            ``X-Attestly-Mode`` response header. Absent for anonymous traffic.
          nullable: true
          title: Mode
          type: string
        request_id:
          description: Correlation ID injected by the request-id middleware
          nullable: true
          title: Request Id
          type: string
      title: Meta
      type: object
    ProblemDetail:
      properties:
        detail:
          type: string
        instance:
          type: string
        status:
          type: integer
        title:
          type: string
        type:
          format: uri
          type: string
      required:
        - type
        - title
        - status
      type: object
    SubjectInput:
      additionalProperties: false
      properties:
        scheme:
          $ref: '#/components/schemas/SchemeInput'
          description: >-
            Typed identifier to look up — ``{ type, value }`` where ``type`` is
            the scheme namespace (``br:cnpj``, ``ofac:sdn``, etc.) and ``value``
            is the canonicalized identifier.
      required:
        - scheme
      title: SubjectInput
      type: object
    MatchOp:
      enum:
        - equals
        - ilike
      title: MatchOp
      type: string
    SubjectMatchHit:
      properties:
        indexed_at:
          format: date-time
          nullable: true
          title: Indexed At
          type: string
        properties:
          additionalProperties: true
          title: Properties
          type: object
        source_id:
          title: Source Id
          type: string
        source_name:
          title: Source Name
          type: string
        value:
          description: Matched identifier value.
          title: Value
          type: string
      required:
        - source_name
        - source_id
        - value
      title: SubjectMatchHit
      type: object
    ReferenceAreasCheckStatus:
      enum:
        - ok
        - failed
      title: ReferenceAreasCheckStatus
      type: string
    LintWarningResponse:
      properties:
        code:
          description: Stable rule identifier, e.g. 'LNT001'.
          pattern: ^LNT[0-9]{3}$
          title: Code
          type: string
        message:
          description: Human-readable description naming the offending element.
          title: Message
          type: string
        path:
          description: >-
            Dot/brace path to the offending node (e.g. `sets.foo`). Null for
            cross-cutting findings with no single location.
          nullable: true
          title: Path
          type: string
        severity:
          $ref: '#/components/schemas/LintSeverity'
          description: >-
            `warning` for smells that are almost always worth fixing; `info` for
            suggestions that may be intentional.
      required:
        - code
        - message
        - severity
      title: LintWarningResponse
      type: object
    SchemeInput:
      additionalProperties: false
      properties:
        type:
          description: >-
            Typed identifier scheme (``<authority>:<scheme-name>``, lowercase,
            max 65 chars). Examples: ``br:cnpj``, ``br:cpf``, ``ofac:sdn``.
          example: br:cnpj
          pattern: ^[a-z][a-z0-9-]{0,15}:[a-z][a-z0-9._-]{0,47}$
          title: Type
          type: string
        value:
          description: >-
            Identifier value. Cosmetic separators (spaces, dashes, dots,
            slashes, parens, etc.) and case differences are stripped at
            validation time — ``"12.345.678/0001-90"`` and ``"12345678000190"``
            are equivalent. The same canonicalization is applied at ingest, so
            ``equals`` matches are deterministic.
          example: 12.345.678/0001-90
          maxLength: 256
          minLength: 1
          title: Value
          type: string
      required:
        - type
        - value
      title: SchemeInput
      type: object
    LintSeverity:
      enum:
        - warning
        - info
      title: LintSeverity
      type: string
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http

````