> ## 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.

# POST /v1/subjects

> Match an identifier against subject registers (sanctions, blacklists, registries).

Non-spatial endpoint: send a single typed identifier (CNPJ, EIN, OFAC
SDN, etc.); get back which subject registers contain a match.

## Request

```json theme={null}
{
  "input": {
    "scheme": { "type": "ofac:sdn", "value": "12345" }
  },
  "subject_source": "ofac_sdn",
  "match_op": "equals",
  "reference_id": "kyc-2026-05-001"
}
```

| Field            | Required | Notes                                                                 |
| ---------------- | -------- | --------------------------------------------------------------------- |
| `input.scheme`   | yes      | `{type, value}`. `type` is the scheme namespace, e.g. `br:cnpj`.      |
| `subject_source` | no       | Pin lookup to a single source. Omit to search all available.          |
| `match_op`       | no       | `equals` (default, exact canonical match) or `ilike` (`%` wildcards). |
| `reference_id`   | no       | Caller-provided correlation id, echoed in response.                   |

The identifier `value` is canonicalized server-side: spaces, dashes,
dots, slashes, and parentheses are stripped, case is normalized. So
`"12.345.678/0001-90"` and `"12345678000190"` are equivalent.

## Response

```json theme={null}
{
  "data": {
    "matches": [
      {
        "source_name": "ofac_sdn",
        "source_id": "sdn-12345",
        "value": "12345",
        "indexed_at": "2026-04-30T00:00:00Z",
        "properties": { "name": "...", "program": "..." }
      }
    ],
    "subject_check": "ok",
    "reference_id": "kyc-2026-05-001"
  },
  "meta": { "request_id": "..." },
  "errors": []
}
```

An empty `matches` array means no match was found. `subject_check` is
`"ok"` when all sources answered, `"failed"` when a partial answer was
returned.

## Schemes

Schemes follow `<authority>:<name>` (lowercase, max 65 chars total).
Some common ones:

| Scheme     | Description                         |
| ---------- | ----------------------------------- |
| `br:cnpj`  | Brazilian corporate ID              |
| `br:cpf`   | Brazilian individual taxpayer ID    |
| `us:ein`   | US Employer Identification Number   |
| `ofac:sdn` | OFAC Specially Designated Nationals |

Call `GET /v1/sources?kind=subject_register` to see which schemes are
available to your Organization.

See the **OpenAPI** tab in the sidebar for the complete request/response
schema.