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

> Casa um identificador contra subject registers (sanções, blacklists, registros).

Endpoint não-espacial: envie um único identificador tipado (CNPJ,
EIN, OFAC SDN, etc.); receba quais subject registers contêm uma
correspondência.

## Request

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

| Campo            | Obrigatório | Notas                                                             |
| ---------------- | ----------- | ----------------------------------------------------------------- |
| `input.scheme`   | sim         | `{type, value}`. `type` é o namespace do scheme, ex.: `br:cnpj`.  |
| `subject_source` | não         | Restringe o lookup a um único source. Omita para buscar em todos. |
| `match_op`       | não         | `equals` (default, exato canônico) ou `ilike` (curingas `%`).     |
| `reference_id`   | não         | Id de correlação fornecido pelo cliente, ecoado na resposta.      |

O `value` do identificador é canonicalizado no servidor: espaços,
hífens, pontos, barras e parênteses são removidos, caixa é
normalizada. Então `"12.345.678/0001-90"` e `"12345678000190"` são
equivalentes.

## 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"
  }
}
```

Um array `matches` vazio significa que não houve match.
`subject_check` vale `"ok"` quando todos os sources responderam,
`"failed"` quando uma resposta parcial foi retornada.

## Schemes

Schemes seguem `<authority>:<name>` (minúsculo, máx 65 chars). Alguns
comuns:

| Scheme     | Descrição                           |
| ---------- | ----------------------------------- |
| `br:cnpj`  | CNPJ                                |
| `br:cpf`   | CPF                                 |
| `us:ein`   | US Employer Identification Number   |
| `ofac:sdn` | OFAC Specially Designated Nationals |

Chame `GET /v1/sources?kind=subject_register` para ver quais
schemes estão disponíveis para sua Organização.