Skip to main content
POST
/
api
/
v1
/
bureau
/
runs
cURL
curl -X POST https://admin.kycert.com.br/api/v1/bureau/runs \
  -H "x-api-key: $KYCERT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "550e8400-e29b-41d4-a716-446655440000",
    "subject": {
      "type": "pf",
      "doc": "12345678901",
      "name": "João Silva"
    },
    "webhook_url": "https://broker.com/webhooks/kycert"
  }'
{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "estimated_seconds": 15,
  "livemode": true
}

Authorizations

​
x-api-key
string
header
required

API key no header x-api-key (recomendado)

Headers

​
Idempotency-Key
string<uuid>

UUID único por tentativa. Mesmo valor nas próximas 24h retorna o run original sem executar novamente. Use sempre que implementar retry no seu código.

​
x-kycert-api-version
string

Versão da API a usar. Omitir = versão mais recente. Fixe em 2026-06-03 para garantir estabilidade em produção.

Example:

"2026-06-03"

Body

application/json
​
template_id
string<uuid>
required

ID do template configurado no dashboard kycert

​
subject
object
required

Sujeito a ser analisado

​
webhook_url
string<uri>

URL HTTPS para entrega do resultado deste run. Se omitido, usa o endpoint padrão configurado em Settings → Webhooks no dashboard.

​
external_id
string

Seu identificador interno para este run. Útil para correlacionar com seu sistema.

Maximum string length: 255
​
metadata
object

Até 10 pares chave-valor string. Retornado no webhook e no GET /runs.

Response

Run criado e em processamento. Resultado entregue via webhook.

​
run_id
string<uuid>

Identificador único do run — use para polling e correlação

​
status
enum<string>

Sempre queued na criação

Available options:
queued
​
estimated_seconds
integer

Estimativa de conclusão em segundos — use como Retry-After no polling

​
livemode
boolean

true para produção, false para sandbox