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

# Consultar identidade com o LegitID

> POST /v1/legitid/verifications: envie CPF e selfie em multipart ou JSON, leia o Score de Identidade e trate os erros e o tempo de resposta.

Envia o CPF e a selfie do titular e devolve o Score de Identidade, na mesma chamada. Para ler o
score e decidir o que fazer com ele, veja [LegitID](https://documentacao.legitimuz.com/platform/legitid.md).

```bash title="Multipart" theme={null}
curl -X POST https://api-core.legitimuz.com/v1/legitid/verifications \
  -H "X-API-Key: $LEGITIMUZ_API_KEY" \
  -F "cpf=12345678909" \
  -F "selfie=@selfie.jpg;type=image/jpeg" \
  --max-time 90
```

```bash title="JSON com base64" theme={null}
SELFIE_BASE64=$(base64 < selfie.jpg | tr -d '\n')
printf '{"cpf":"12345678909","selfie":"%s"}' "$SELFIE_BASE64" > legitid-body.json

curl -X POST https://api-core.legitimuz.com/v1/legitid/verifications \
  -H "X-API-Key: $LEGITIMUZ_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @legitid-body.json \
  --max-time 90
```

```json title="200" theme={null}
{
  "id": "01a18241-bb50-7103-81ee-1995ad772022",
  "cpf": "12345678909",
  "identity_score": 80
}
```

```json title="400 (CPF inválido)" theme={null}
{
  "message": "E_VALIDATION_FAILURE",
  "errors": [
    "E_VALIDATION_FAILURE: Invalid payload.",
    "E_VALIDATION_FAILURE: cpf: invalid CPF"
  ]
}
```

O CPF `12345678909` dos exemplos é fictício. Em sandbox, use os [CPFs de teste](https://documentacao.legitimuz.com/platform/legitid.md#sandbox).

## Pré-requisitos

* Uma chave de API com a permissão de criar verificação (**Criar link de verificação**, no
  dashboard).
* O LegitID liberado nessa chave pela equipe da Legitimuz. Veja
  [liberação do LegitID](https://documentacao.legitimuz.com/platform/legitid.md#liberar-o-legitid-na-chave).

Sem uma das duas, a resposta é `403 E_FORBIDDEN`.

## Autenticação

**X-API-Key** `string` *required*

A chave da integração, no formato `lz_...`. Criada em
[Integrações → Segurança → Chaves de API](https://documentacao.legitimuz.com/platform/tokens.md).

A chave não é aceita no corpo nem na query. Veja [autenticação](https://documentacao.legitimuz.com/start/authentication.md).

**Content-Type** `string` *required*

`multipart/form-data` ou `application/json`. Qualquer outro valor responde
`400 E_VALIDATION_FAILURE`.

## Corpo

**cpf** `string` *required*

O CPF do titular, com ou sem máscara: `123.456.789-09` e `12345678909` valem igual. É conferido só
pelo dígito verificador, sem consulta à Receita Federal. CPF com todos os dígitos iguais é
inválido.

**selfie** `file` *required*

A selfie do titular, em JPEG ou PNG, com até 10 MB. O formato é detectado pelos bytes, não pela
extensão nem pelo `Content-Type` da parte. PDF é recusado.

Vai em **um** formato só:

* no `multipart/form-data`, como arquivo na parte `selfie`, ou como texto base64 no campo `selfie`;
* no `application/json`, como texto base64 no campo `selfie`.

O base64 pode vir com o prefixo `data:image/jpeg;base64,`. Arquivo e base64 na mesma requisição
respondem `400 E_SELFIE_DUAL_SEND`.

No `application/json`, o corpo inteiro tem limite de 15 MB. Acima disso, a resposta é
`413 E_PAYLOAD_TOO_LARGE`.

No JSON, qualquer campo além de `cpf` e `selfie` responde `400 E_VALIDATION_FAILURE`.

## Requisição

Os dois formatos levam ao mesmo resultado. O multipart evita o aumento de cerca de um terço que o
base64 traz ao tamanho do corpo.

```bash title="curl, multipart" theme={null}
curl -X POST https://api-core.legitimuz.com/v1/legitid/verifications \
  -H "X-API-Key: $LEGITIMUZ_API_KEY" \
  -F "cpf=12345678909" \
  -F "selfie=@selfie.jpg;type=image/jpeg" \
  --max-time 90
```

```bash title="curl, JSON com base64" theme={null}
SELFIE_BASE64=$(base64 < selfie.jpg | tr -d '\n')
printf '{"cpf":"123.456.789-09","selfie":"%s"}' "$SELFIE_BASE64" > legitid-body.json

curl -X POST https://api-core.legitimuz.com/v1/legitid/verifications \
  -H "X-API-Key: $LEGITIMUZ_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @legitid-body.json \
  --max-time 90
```

```ts title="Node.js (fetch)" theme={null}
import { readFile } from "node:fs/promises";

const selfie = await readFile("selfie.jpg");

const form = new FormData();
form.append("cpf", "12345678909");
form.append("selfie", new Blob([selfie], { type: "image/jpeg" }), "selfie.jpg");

const response = await fetch("https://api-core.legitimuz.com/v1/legitid/verifications", {
  method: "POST",
  headers: { "X-API-Key": process.env.LEGITIMUZ_API_KEY! },
  body: form,
  signal: AbortSignal.timeout(90_000),
});

const result = await response.json();
```

```python title="Python (requests)" theme={null}
import os

import requests

with open("selfie.jpg", "rb") as selfie:
    response = requests.post(
        "https://api-core.legitimuz.com/v1/legitid/verifications",
        headers={"X-API-Key": os.environ["LEGITIMUZ_API_KEY"]},
        data={"cpf": "12345678909"},
        files={"selfie": ("selfie.jpg", selfie, "image/jpeg")},
        timeout=(10, 90),
    )

result = response.json()
```

> [!WARNING]
>
> A selfie e o CPF são dados pessoais do titular, e a selfie é dado biométrico. Não registre o corpo
> da requisição em log, nem o base64 da selfie, e não guarde a imagem além do que a sua finalidade
> exige.

## Resposta

```json theme={null}
{
  "id": "01a18241-bb50-7103-81ee-1995ad772022",
  "cpf": "12345678909",
  "identity_score": 80
}
```

**id** `string`

O identificador público e único desta consulta. Guarde-o junto do resultado: é o que o suporte
pede para localizar a consulta.

**cpf** `string`

O CPF consultado, só com dígitos, mesmo que a requisição tenha vindo com máscara.

**identity\_score** `number`

O Score de Identidade. Sempre um destes valores: `0`, `10`, `20`, `40`, `80`, `90` ou `100`. O
significado de cada um e a recomendação por faixa estão na [régua](https://documentacao.legitimuz.com/platform/legitid.md#régua-do-score-de-identidade).

A resposta vem com `Cache-Control: no-store`: cada chamada é uma consulta nova. Toda resposta `200`
é cobrada, inclusive o score 0.

## Tempo de resposta e retentativa

A resposta é síncrona e pode levar vários segundos. Cada base biométrica consultada tem o próprio
limite de tempo, e não existe um teto total para a chamada.

* Configure o timeout do seu cliente HTTP em **pelo menos 90 segundos**.
* **Não repita** uma chamada que respondeu `200`. Uma nova chamada é uma nova consulta, cobrada de
  novo, e não há idempotência.
* Repita com backoff só em `503`, e em `429` depois do `Retry-After`.
* Se o seu cliente desistir antes da resposta, a consulta pode ter terminado do lado da Legitimuz e
  ter sido cobrada. Prefira um timeout longo a repetir.

## Erros

O corpo de erro segue o [envelope da API](https://documentacao.legitimuz.com/api/errors.md). Nenhum erro é cobrado.

| HTTP | Código | Quando | Repetir |
| - | - | - | - |
| `400` | `E_VALIDATION_FAILURE` | CPF inválido, selfie ausente, base64 ilegível ou acima do limite, imagem que não abre, campo extra no JSON ou `Content-Type` fora de multipart e JSON | não |
| `400` | `E_SELFIE_DUAL_SEND` | Selfie enviada como arquivo e como base64 na mesma requisição | não |
| `401` | `E_UNAUTHORIZED_ACCESS` | Chave ausente, inválida, expirada ou revogada | não |
| `403` | `E_FORBIDDEN` | Chave sem a permissão de criar verificação ou sem o LegitID liberado | não |
| `413` | `E_PAYLOAD_TOO_LARGE` | Arquivo da selfie acima de 10 MB, imagem com resolução acima do limite, ou corpo JSON acima de 15 MB | não |
| `415` | `E_UNSUPPORTED_MEDIA_TYPE` | Selfie fora de JPEG e PNG, inclusive PDF | não |
| `429` | `E_RATE_LIMITED` | Acima de 500 chamadas por minuto na chave | sim, após `Retry-After` |
| `500` | `E_INTERNAL_SERVER_ERROR` | Falha inesperada | sim, com backoff |
| `503` | `E_LEGITID_UNAVAILABLE` | Nenhuma base biométrica respondeu, ou a consulta não pôde ser registrada | sim, com backoff |

### Selfie em um formato só

`E_SELFIE_DUAL_SEND` chega quando a mesma requisição traz a selfie como arquivo e como base64.

```json theme={null}
{
  "message": "E_SELFIE_DUAL_SEND",
  "errors": [
    "E_SELFIE_DUAL_SEND: Send the selfie in one format only: a multipart file or a base64 JSON field."
  ]
}
```

Escolha um dos dois. No multipart, mande a selfie só como arquivo na parte `selfie`; no JSON, só
como base64.

### LegitID indisponível

`503 E_LEGITID_UNAVAILABLE` quer dizer que não há resultado: nenhuma base respondeu, ou a consulta
não pôde ser registrada. Não é score 0 e não é cobrado.

```json theme={null}
{
  "message": "E_LEGITID_UNAVAILABLE",
  "errors": ["E_LEGITID_UNAVAILABLE: Identity check unavailable, try again later."]
}
```

Repita mais tarde, com backoff. Não trate o `503` como reprovação do titular.

### 403 com chave válida

A chave autentica, mas falta uma das duas condições. Confira no dashboard se ela tem a permissão
**Criar link de verificação**. Se tiver, falta a liberação do LegitID: peça ao
[suporte](https://painel.legitimuz.com/support).

## Próximo passo

> [card] [Ler o score](https://documentacao.legitimuz.com/platform/legitid.md)
>
> A régua, as recomendações e a diferença entre 10 e 0.

> [card] [Erros e limites](https://documentacao.legitimuz.com/api/errors.md)
>
> O envelope e o catálogo completo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.