Skip to main content
GET
cURL

Paginação

A listagem usa cursor pagination. Quando has_more: true, o campo next_cursor está presente — passe-o como parâmetro cursor na próxima requisição.
cursor é um valor opaco (data de criação ISO 8601 concatenada ao ID do último registro da página) — pode conter caracteres reservados de URL como : e +, por isso é sempre necessário encodeURIComponent ao montá-lo na query string.

Campo doc

Por privacidade, o campo doc é retornado como *** na listagem. Para ver a versão mascarada com dígitos parciais, use GET /customers/:id.

Campos ausentes na listagem

Cada item de data[] é um resumo — inclui email e phone (colunas simples, sem custo extra), mas não inclui documents nem latest_run. Isso é intencional, não uma lacuna: documents e latest_run exigiriam uma query adicional por cliente para montar a listagem (N+1) — o mesmo padrão de problema de performance já evitado em outras telas da plataforma. Numa listagem de 100 clientes isso significaria até 200 queries extras só para popular uma página. Se você precisa de documents ou latest_run para um cliente específico, use GET /customers/:id — o objeto completo só é montado sob demanda, um cliente por vez.

Erros

Formato completo do envelope e estratégia de retry em Tratamento de erros. Os códigos deste endpoint: missing_api_key, invalid_api_key, insufficient_scope, invalid_date (created_after/created_before fora do formato ISO 8601).

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"

Query Parameters

type
enum<string>

Filtrar por tipo de pessoa

Available options:
pf,
pj
status
enum<string>

Status de onboarding do cliente (vocabulário do portal de cadastro — distinto do status de bureau run que usa inglês: completed, running, blocked).

  • em_analise — cadastro recebido, bureau em andamento
  • aprovado — bureau concluído, cliente aprovado
  • pendencia — bureau concluído com pendências para revisão manual
  • recusado — cliente recusado pelo compliance
Available options:
em_analise,
aprovado,
pendencia,
recusado
external_id
string

Filtrar pelo identificador interno

doc
string

Filtrar por CPF ou CNPJ (sem formatação) — busca por hash

created_after
string<date-time>

Retornar apenas clientes criados após esta data (ISO 8601)

created_before
string<date-time>

Retornar apenas clientes criados antes desta data (ISO 8601)

limit
integer
default:20

Número máximo de clientes por página

Required range: 1 <= x <= 100
cursor
string

Cursor de paginação retornado em next_cursor da página anterior

Response

Lista de clientes

data
object[]
has_more
boolean
next_cursor
string | null

Cursor para a próxima página (presente quando has_more=true)

livemode
boolean