Criar verificações

A porta única de criação de verificações: corpo, resposta, idempotência e allowlist de origens.

Existe uma porta de criação, e é só uma: o seu backend chama o endpoint de criação com a chave de API e recebe a sdkUrl da verificação. Não há criação pelo navegador, por link genérico nem por credencial no corpo.

O endpoint está implementado e ainda não foi liberado. O contrato abaixo é o do produto e não muda de forma silenciosa; a URL base sai quando o autenticador entrar em produção.

A requisição

POST /public/verifications

POST /public/get-sdk-url é um alias da mesma rota, com o mesmo corpo e o mesmo comportamento. Prefira /public/verifications: é o nome do que a chamada faz, e é o que esta documentação usa.

Autenticação pelo header x-api-key, com a chave precisando conceder a criação de verificações. Sem esse escopo a resposta é 403.

Corpo

O schema é estrito: campo desconhecido é recusado com 400, nunca ignorado em silêncio.

Campo	Tipo	Obrigatório	O que é
schema_version	"1.0"	sim	a versão do contrato
document	objeto	sim	{ "type": "cpf", "number": "..." }. O CPF entra com ou sem máscara e é normalizado para dígitos
ref_id	string, 1–120	não	o seu identificador do pedido. É a chave da idempotência
flow_public_id	uuid	não	ausente usa o fluxo publicado padrão da integração da chave
integration_origin_public_id	uuid	não	ausente cria sem pino de origem. Informado, precisa ser da mesma integração e estar verificado

Requisição

{
  "schema_version": "1.0",
  "document": { "type": "cpf", "number": "000.000.000-00" },
  "ref_id": "pedido-4471"
}

O CPF acima é fictício e usa máscara neutra.

A resposta é a sdkUrl

Resposta 201

{
  "schema_version": "1.0",
  "verification": {
    "public_id": "<uuid>",
    "status": "pending",
    "expires_at": "2026-09-01T18:30:00.000Z"
  },
  "entry": {
    "kind": "web",
    "url": "https://verify.legitimuz.com/#v=<uuid>"
  }
}

O campo entry.url é a sdkUrl: entregue esse valor ao seu front-end e monte o widget, como no passo 6 do caminho de integração.

A entrada varia com a origem:

entry.kind	Quando	O que traz
web	origem web, ou nenhuma origem	url, com o identificador só no fragmento
native	origem iOS ou Android	public_id, entregue ao SDK nativo por canal seguro

O identificador viaja no fragmento da URL (#v=...), que o navegador nunca envia a servidor HTTP. A resposta também vai com Cache-Control: no-store.

A sdkUrl é a credencial da verificação. Vale por tempo limitado, tem escopo de um único fluxo, e não lista nem alcança outras verificações. Não logue, não persista e não mande para tag manager.

Idempotência

A criação aceita um identificador de referência seu (ref_id) e trata repetição de forma previsível:

Situação	Resposta
ref_id novo	201 com a verificação criada
Mesmo ref_id, mesmo payload	200 com a verificação existente, não uma segunda
Mesmo ref_id, payload diferente	409

Nova tentativa para o mesmo titular é uma decisão sua: crie outra verificação, com outro ref_id. Não existe clonagem nem reativação pelo navegador.

Limite de requisições

A criação aceita até 500 requisições por minuto por chave de API.

Allowlist de origens

O widget só monta em páginas cuja origem está registrada e verificada na integração — a mesma allowlist descrita em segurança, cadastrada no passo 3. Origem pendente não autoriza nada.

Erros

A API responde com o código HTTP correto, sem erro de negócio disfarçado de sucesso:

Código	Significado
400	Requisição inválida, inclusive campo desconhecido no corpo
401	Credencial ausente, inválida ou expirada
403	A chave não tem a permissão necessária
404	Recurso fora do escopo da chave; a existência não é confirmada
409	ref_id já usado com payload diferente
422	Recusado por regra de negócio, com o motivo em código