Criar cliente

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"
  }'

const res = await fetch('https://admin.kycert.com.br/api/v1/customers', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.KYCERT_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    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',
  }),
})
const { customer_id, run_id } = await res.json()
console.log(customer_id, run_id)

import requests

url = "https://admin.kycert.com.br/api/v1/customers"

payload = {
    "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",
    "external_id": "cust_abc123",
    "metadata": { "channel": "app_mobile" }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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',
    external_id: 'cust_abc123',
    metadata: {channel: 'app_mobile'}
  })
};

fetch('https://admin.kycert.com.br/api/v1/customers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://admin.kycert.com.br/api/v1/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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',
    'external_id' => 'cust_abc123',
    'metadata' => [
        'channel' => 'app_mobile'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://admin.kycert.com.br/api/v1/customers"

	payload := strings.NewReader("{\n  \"type\": \"pf\",\n  \"doc\": \"12345678901\",\n  \"name\": \"João Silva\",\n  \"email\": \"joao@example.com\",\n  \"run_bureau\": true,\n  \"template_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"webhook_url\": \"https://broker.com/webhooks/kycert\",\n  \"external_id\": \"cust_abc123\",\n  \"metadata\": {\n    \"channel\": \"app_mobile\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://admin.kycert.com.br/api/v1/customers")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"pf\",\n  \"doc\": \"12345678901\",\n  \"name\": \"João Silva\",\n  \"email\": \"joao@example.com\",\n  \"run_bureau\": true,\n  \"template_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"webhook_url\": \"https://broker.com/webhooks/kycert\",\n  \"external_id\": \"cust_abc123\",\n  \"metadata\": {\n    \"channel\": \"app_mobile\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://admin.kycert.com.br/api/v1/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"pf\",\n  \"doc\": \"12345678901\",\n  \"name\": \"João Silva\",\n  \"email\": \"joao@example.com\",\n  \"run_bureau\": true,\n  \"template_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"webhook_url\": \"https://broker.com/webhooks/kycert\",\n  \"external_id\": \"cust_abc123\",\n  \"metadata\": {\n    \"channel\": \"app_mobile\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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
}

POST

api

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"
  }'

const res = await fetch('https://admin.kycert.com.br/api/v1/customers', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.KYCERT_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    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',
  }),
})
const { customer_id, run_id } = await res.json()
console.log(customer_id, run_id)

import requests

url = "https://admin.kycert.com.br/api/v1/customers"

payload = {
    "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",
    "external_id": "cust_abc123",
    "metadata": { "channel": "app_mobile" }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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',
    external_id: 'cust_abc123',
    metadata: {channel: 'app_mobile'}
  })
};

fetch('https://admin.kycert.com.br/api/v1/customers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://admin.kycert.com.br/api/v1/customers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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',
    'external_id' => 'cust_abc123',
    'metadata' => [
        'channel' => 'app_mobile'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://admin.kycert.com.br/api/v1/customers"

	payload := strings.NewReader("{\n  \"type\": \"pf\",\n  \"doc\": \"12345678901\",\n  \"name\": \"João Silva\",\n  \"email\": \"joao@example.com\",\n  \"run_bureau\": true,\n  \"template_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"webhook_url\": \"https://broker.com/webhooks/kycert\",\n  \"external_id\": \"cust_abc123\",\n  \"metadata\": {\n    \"channel\": \"app_mobile\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://admin.kycert.com.br/api/v1/customers")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"pf\",\n  \"doc\": \"12345678901\",\n  \"name\": \"João Silva\",\n  \"email\": \"joao@example.com\",\n  \"run_bureau\": true,\n  \"template_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"webhook_url\": \"https://broker.com/webhooks/kycert\",\n  \"external_id\": \"cust_abc123\",\n  \"metadata\": {\n    \"channel\": \"app_mobile\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://admin.kycert.com.br/api/v1/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"pf\",\n  \"doc\": \"12345678901\",\n  \"name\": \"João Silva\",\n  \"email\": \"joao@example.com\",\n  \"run_bureau\": true,\n  \"template_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"webhook_url\": \"https://broker.com/webhooks/kycert\",\n  \"external_id\": \"cust_abc123\",\n  \"metadata\": {\n    \"channel\": \"app_mobile\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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ário	Endpoint recomendado
Cadastrar + verificar em uma chamada	`POST /api/v1/customers` com `run_bureau: true`
Verificar sem criar cadastro permanente	`POST /api/v1/bureau/runs`
Cadastrar agora, verificar depois	`POST /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

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

Show child attributes

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

Show child attributes

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

doc

string

CPF/CNPJ mascarado — nunca retorna em claro

Example:

"***456789**"

external_id

string | null

metadata

object | null

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

Começando

Guias

Webhooks

Referência da API

Quando usar

Campo `doc` na resposta

Campo `run_bureau`

Authorizations

Headers

Body

Response

​Quando usar

​Campo doc na resposta

​Campo run_bureau

Authorizations

Headers

Body

Response

Quando usar

Campo `doc` na resposta

Campo `run_bureau`