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.example.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>"
  },
  "integration_origin_public_id": "<string>",
  "ref_id": "<string>",
  "flow_public_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.access_credential": "<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 configuração e a origem naquele instante, e devolve uma credencial de curta duração. É por isso que ela nasce no seu backend: a chave de API nunca chega ao browser nem ao app.

curl -X POST https://api.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>" },
    "integration_origin_public_id": "<ORIGIN_PUBLIC_ID>"
  }'

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.

integration_origin_public_id · string · required

A origem onde o fluxo vai abrir, um domínio web ou um app bundle. Precisa pertencer à integração e estar verificada, senão a chamada responde 422.

O canal (web, iOS, Android) é derivado do tipo da origem; não existe campo channel.

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.

flow_public_id · string

O fluxo a usar. Ausente, a integração usa o fluxo publicado padrão dela. Precisa pertencer à mesma conta e integração.

Resposta

schema_version · string

A versão do contrato.

verification · object

Show campos

verification.public_id · string

O identificador da verificação. Não é segredo: use-o em log e em chamado de suporte.

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, derivado da origem.

Show campos

entry.kind · string

"web" ou "native".

entry.url · string

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

entry.access_credential · string

Só em kind: "native". A credencial que o seu app entrega ao SDK.

Origem 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=<access_credential>"
  }
}

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 ou origem fora do alcance da conta.
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	A origem existe, mas não foi verificada.
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.

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.