Criar verificação

POST /public/verifications, o corpo, a resposta, a idempotência por ref_id e os onze códigos de resposta.

POST /public/verifications

Criar verificação

cURL

curl --request POST \
  --url https://api-core.legitimuz.com/public/verifications \
  --header 'Content-Type: <content-type>' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "schema_version": "<string>",
  "document": {
    "document.type": "<string>",
    "document.number": "<string>"
  },
  "flow_public_id": "<string>",
  "ref_id": "<string>"
}
'

200

{
  "schema_version": "<string>",
  "verification": {
    "verification.public_id": "<string>",
    "verification.status": "<string>",
    "verification.expires_at": "<string>"
  },
  "entry": {
    "entry.kind": "<string>",
    "entry.url": "<string>",
    "entry.public_id": "<string>"
  }
}

Cria uma verificação e emite a entrada da jornada. É a única chamada que o seu servidor faz para começar uma verificação.

A chamada resolve a conta e a integração pela chave, fixa a versão publicada do fluxo naquele instante e devolve a entrada da jornada. É por isso que ela nasce no seu backend: a chave de API nunca chega ao browser nem ao app.

curl -X POST https://api-core.legitimuz.com/public/verifications \
  -H "X-API-Key: $LEGITIMUZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_version": "1.0",
    "ref_id": "pedido-4471",
    "document": { "type": "cpf", "number": "<CPF_DO_TITULAR>" }
  }'

Autenticação

X-API-Key · 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.

Content-Type · string · required

application/json. Qualquer outro valor responde 415.

traceparent · string

Propaga tracing distribuído. Opcional.

Corpo

schema_version · string · required

A versão do contrato. Hoje, "1.0".

document · object · required

O documento que identifica o titular.

Show campos

document.type · string · required

Hoje só "cpf".

document.number · string · required

Normalizado e validado no servidor. Nunca volta na resposta nem no bootstrap do widget.

flow_public_id · string

O fluxo que a verificação vai usar. Copie o id em Solução KYC → Fluxos, no menu da linha do fluxo, em Copiar ID do fluxo.

Ausente, a chamada usa o fluxo padrão da integração. Se a integração não tiver fluxo padrão definido, a resposta é 404 E_NOT_FOUND — o mesmo código de um fluxo que não existe. Veja quando o 404 é de fluxo.

ref_id · string

A sua chave para essa verificação, número do pedido, id do cadastro. Até 120 caracteres, único por conta.

É o que volta no webhook de desfecho. Sem ele, você precisa guardar o public_id da plataforma para saber de quem é o evento.

Resposta

schema_version · string

A versão do contrato.

verification · object

Show campos

verification.public_id · string

O identificador da verificação, e o mesmo valor que abre a jornada: é ele que vai no fragmento da entry.url. Guarde-o no seu banco para ligar o webhook ao seu pedido, e trate-o como segredo de curta duração até o expires_at.

verification.status · string

Um dos cinco status. Numa criação, not_opened.

verification.expires_at · string

Quando a jornada deixa de poder ser aberta. ISO 8601 em UTC.

entry · object

Como o titular entra na jornada. União discriminada por kind. Quem decide é a origem resolvida pela sua chave: origem de domínio web, ou integração sem origem, devolve "web"; origem de bundle de app devolve "native".

As SDKs de Android e iOS consomem o embed URL de entry.url.

Show campos

entry.kind · string

"web" ou "native".

entry.url · string

Só em kind: "web". A URL da jornada, com o public_id da verificação no fragmento. Gere o QR code a partir dela se quiser entrega por celular.

entry.public_id · string

Só em kind: "native". É o mesmo verification.public_id, sem a URL em volta.

Link web

{
  "schema_version": "1.0",
  "verification": {
    "public_id": "019f0000-0000-7000-8000-000000000000",
    "status": "not_opened",
    "expires_at": "2026-09-15T14:30:00.000Z"
  },
  "entry": {
    "kind": "web",
    "url": "https://verify.legitimuz.com/#v=019f0000-0000-7000-8000-000000000000"
  }
}

A entry.url carrega a credencial da jornada. Trate-a como segredo de curta duração: ela sai do seu backend para o titular daquela verificação e para mais ninguém. Não a registre em log, não a mande por e-mail e não a fixe no código do cliente.

Idempotência

A idempotência é por ref_id, no escopo da conta. Você não envia header de idempotência.

Chamada	Resposta
ref_id novo	201 com a verificação criada
Mesmo ref_id, mesmo corpo	200 com a verificação existente, o status pode ter avançado
Mesmo ref_id, corpo diferente	409 E_REF_ID_CONFLICT

Isso torna a chamada segura para retentativa: um timeout de rede não cria duas verificações para o mesmo pedido.

Códigos de resposta

HTTP	Código	Quando
201	—	Verificação criada.
200	—	Repetição idempotente recuperou a existente.
400	E_VALIDATION_FAILURE	Forma do corpo, CPF ou campo inválido.
401	E_UNAUTHORIZED_ACCESS	Chave ausente, inválida, expirada ou revogada.
403	E_FORBIDDEN	Chave válida, sem permissão de criar verificação.
404	E_NOT_FOUND	Fluxo fora do alcance da conta, sem versão publicada, ou integração sem fluxo padrão.
409	E_REF_ID_CONFLICT	Mesmo ref_id, corpo diferente.
415	E_UNSUPPORTED_MEDIA_TYPE	Content-Type não é application/json.
422	E_ORIGIN_NOT_VERIFIED	Reservado para origem de app. Não alcançável pela criação atual.
429	E_RATE_LIMITED	Teto da chave ou da integração. Veja limites.
500	E_INTERNAL_SERVER_ERROR	Falha inesperada.
503	E_AUDIT_UNAVAILABLE	Escrita obrigatória de auditoria indisponível. Tente de novo.

Quando o 404 é de fluxo

O 404 E_NOT_FOUND da criação é o mesmo para quatro situações diferentes, de propósito: a resposta não conta a quem pergunta o que existe na conta de outra pessoa. As quatro são de fluxo.

O que aconteceu	Como confirmar
A chamada não mandou flow_public_id e a integração não tem fluxo padrão	Em Integrações, a coluna Fluxo padrão mostra Sem fluxo
O flow_public_id não existe, ou é de outra conta	Compare com o id em Fluxos → Copiar ID do fluxo
O fluxo existe, mas nunca foi publicado	O fluxo aparece em Fluxos sem versão publicada
O fluxo está inativo	O fluxo aparece arquivado em Fluxos

Mande o flow_public_id na chamada e o primeiro caso sai da lista. O fluxo padrão da integração é definido pela Legitimuz na implantação; se a sua integração está sem ele, fale com o suporte.

O formato do corpo de erro está em erros da API.

Próximo passo

Abrir o fluxo

O que fazer com a entry no browser ou no app.

Receber a decisão

O evento que fecha o ciclo, com o desfecho no corpo.