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

> Coincide un identificador contra subject registers (sanciones, blacklists, registros).

Endpoint no-espacial: envía un único identificador tipado (CNPJ,
EIN, OFAC SDN, etc.); recibe qué subject registers contienen una
coincidencia.

## 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            | Obligatorio | Notas                                                               |
| ---------------- | ----------- | ------------------------------------------------------------------- |
| `input.scheme`   | sí          | `{type, value}`. `type` es el namespace del scheme, ej.: `br:cnpj`. |
| `subject_source` | no          | Restringe el lookup a un único source. Omite para buscar en todos.  |
| `match_op`       | no          | `equals` (default, exacto canónico) o `ilike` (comodines `%`).      |
| `reference_id`   | no          | Id de correlación del cliente, ecoado en la respuesta.              |

El `value` del identificador se canonicaliza en el servidor:
espacios, guiones, puntos, barras y paréntesis se eliminan, la caja
se normaliza. Entonces `"12.345.678/0001-90"` y `"12345678000190"`
son 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"
  }
}
```

Un array `matches` vacío significa que no hubo coincidencia.
`subject_check` vale `"ok"` cuando todos los sources respondieron,
`"failed"` cuando se devolvió una respuesta parcial.

## Schemes

Los schemes siguen `<authority>:<name>` (minúsculas, máx 65
caracteres). Algunos comunes:

| Scheme     | Descripción                         |
| ---------- | ----------------------------------- |
| `br:cnpj`  | CNPJ                                |
| `br:cpf`   | CPF                                 |
| `us:ein`   | US Employer Identification Number   |
| `ofac:sdn` | OFAC Specially Designated Nationals |

Llama a `GET /v1/sources?kind=subject_register` para ver qué
schemes están disponibles para tu Organización.