Skip to main content
POST
/
api
/
v1
/
customers
cURL
curl -X POST https://admin.kycert.com.br/api/v1/customers \
  -H "x-api-key: $KYCERT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "pf",
    "doc": "12345678901",
    "name": "João Silva",
    "email": "joao@example.com",
    "run_bureau": true,
    "template_id": "550e8400-e29b-41d4-a716-446655440000",
    "webhook_url": "https://broker.com/webhooks/kycert"
  }'
{
  "customer_id": "661e9511-f3ac-52e5-b827-557766551111",
  "object": "customer",
  "status": "em_analise",
  "type": "pf",
  "name": "João Silva",
  "email": "joao@example.com",
  "doc": "***456789**",
  "external_id": "cust_abc123",
  "metadata": {
    "channel": "app_mobile"
  },
  "created_at": "2026-06-12T14:00:00Z",
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "bureau_status": "queued",
  "livemode": true
}

​
Quando usar

Use este endpoint para registrar um cliente no kycert antes ou independentemente de rodar um bureau. Ideal para fluxos em que o cadastro acontece em etapas separadas da verificação KYC.
CenárioEndpoint recomendado
Cadastrar + verificar em uma chamadaPOST /api/v1/customers com run_bureau: true
Verificar sem criar cadastro permanentePOST /api/v1/bureau/runs
Cadastrar agora, verificar depoisPOST /api/v1/customers (sem run_bureau)

​
Campo doc na resposta

O CPF ou CNPJ nunca é retornado em claro. A resposta sempre retorna uma versão mascarada:
  • CPF: ***456789**
  • CNPJ: **34567890****

​
Campo run_bureau

Quando run_bureau: true, o bureau é disparado imediatamente após criar o cliente. O comportamento é idêntico ao POST /api/v1/bureau/runs e o resultado chega via webhook. Veja Conceitos — Run para entender o ciclo de vida de um run.

Authorizations

​
x-api-key
string
header
required

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

Headers

​
x-kycert-api-version
string
Example:

"2026-06-03"

Body

application/json
​
type
enum<string>
required

Tipo do cliente — pessoa física ou jurídica

Available options:
pf,
pj
​
doc
string
required

CPF (11 dígitos) ou CNPJ (14 dígitos), sem formatação

Example:

"12345678901"

​
name
string
required

Nome completo (PF) ou razão social (PJ)

Required string length: 2 - 300
​
email
string<email>

Email do cliente. Obrigatório para PF.

​
phone
string

Telefone do cliente. Opcional.

​
birth_date
string<date>

Data de nascimento no formato YYYY-MM-DD (apenas PF)

​
address
object

Endereço do cliente

​
external_id
string

Seu identificador interno para este cliente. Deve ser único no tenant.

Maximum string length: 255
​
metadata
object

Até 10 pares chave-valor string

​
run_bureau
boolean

Se true, dispara um bureau run imediatamente após criar o cliente. Requer template_id.

​
template_id
string<uuid>

ID do template de bureau (obrigatório quando run_bureau: true)

​
webhook_url
string<uri>

URL HTTPS para entrega do resultado do bureau (quando run_bureau: true)

Response

Cliente criado com sucesso

​
customer_id
string<uuid>

Identificador único do cliente

​
object
enum<string>
Available options:
customer
​
status
string
Example:

"em_analise"

​
type
enum<string>
Available options:
pf,
pj
​
name
string
​
email
string
​
doc
string

CPF/CNPJ mascarado — nunca retorna em claro

Example:

"***456789**"

​
external_id
string | null
​
metadata
object
​
created_at
string<date-time>
​
run_id
string<uuid> | null

ID do run de bureau criado (presente apenas quando run_bureau=true)

​
bureau_status
enum<string> | null

Status do bureau (presente apenas quando run_bureau=true)

Available options:
queued
​
livemode
boolean