Consultar identidade com o LegitID

POST

legitid

verifications

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

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

{
  "id": "01a18241-bb50-7103-81ee-1995ad772022",
  "cpf": "12345678909",
  "identity_score": 80
}

{
  "message": "E_VALIDATION_FAILURE",
  "errors": [
    "E_VALIDATION_FAILURE: Invalid payload.",
    "E_VALIDATION_FAILURE: cpf: invalid CPF"
  ]
}

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.

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

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

{
  "id": "01a18241-bb50-7103-81ee-1995ad772022",
  "cpf": "12345678909",
  "identity_score": 80
}

{
  "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.

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.

Sem uma das duas, a resposta é 403 E_FORBIDDEN.

Autenticação

string

required

A chave da integração, no formato lz_.... Criada em Integrações → Segurança → Chaves de API.A chave não é aceita no corpo nem na query. Veja autenticação.

string

required

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

Corpo

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.

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.

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

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

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();

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()

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

{
  "id": "01a18241-bb50-7103-81ee-1995ad772022",
  "cpf": "12345678909",
  "identity_score": 80
}

string

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

string

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

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.

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

{
  "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.

{
  "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.

Próximo passo

Ler o score

A régua, as recomendações e a diferença entre 10 e 0.

Erros e limites

O envelope e o catálogo completo.

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

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

{
  "id": "01a18241-bb50-7103-81ee-1995ad772022",
  "cpf": "12345678909",
  "identity_score": 80
}

{
  "message": "E_VALIDATION_FAILURE",
  "errors": [
    "E_VALIDATION_FAILURE: Invalid payload.",
    "E_VALIDATION_FAILURE: cpf: invalid CPF"
  ]
}

​Pré-requisitos

​Autenticação

​Corpo

​Requisição

​Resposta

​Tempo de resposta e retentativa

​Erros

​Selfie em um formato só

​LegitID indisponível

​403 com chave válida

​Próximo passo

Ler o score

Erros e limites

Pré-requisitos

Autenticação

Corpo

Requisição

Resposta

Tempo de resposta e retentativa

Erros

Selfie em um formato só

LegitID indisponível

403 com chave válida

Próximo passo