> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kycert.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar clientes

> Retorna lista paginada de clientes do tenant, do mais recente para o mais antigo.

Requer escopo `customers:read`.


## 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.

```typescript theme={null}
let cursor: string | undefined
do {
  const res = await fetch(
    `https://admin.kycert.com.br/api/v1/customers?limit=20${cursor ? `&cursor=${cursor}` : ''}`,
    { headers: { 'x-api-key': process.env.KYCERT_API_KEY! } },
  )
  const page = await res.json()
  process(page.data)
  cursor = page.has_more ? page.next_cursor : undefined
} while (cursor)
```

## 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](/api-reference/getCustomer).


## OpenAPI

````yaml GET /api/v1/customers
openapi: 3.0.3
info:
  title: kycert API
  version: '2026-06-03'
  description: >
    API KYC/AML para corretoras de câmbio autorizadas pelo Banco Central do
    Brasil.

    Permite rodar verificações de bureau em CPF ou CNPJ e receber o resultado
    via webhook.


    **Fluxo principal:**

    ```

    POST /runs → 202 (run_id) → [bureau processa 5–30s] → webhook entregue →
    agir

    ```
  contact:
    name: kycert
    url: https://kycert.com.br
  license:
    name: Proprietário
    url: https://kycert.com.br
servers:
  - url: https://admin.kycert.com.br
    description: Produção (sk_live_...)
  - url: https://admin.kycert.com.br
    description: Sandbox (sk_test_...)
security:
  - ApiKeyHeader: []
  - BearerToken: []
tags:
  - name: Runs
    description: Execução de bureau para CPF ou CNPJ
  - name: Customers
    description: Gestão de clientes do tenant
paths:
  /api/v1/customers:
    get:
      tags:
        - Customers
      summary: Listar clientes
      description: >
        Retorna lista paginada de clientes do tenant, do mais recente para o
        mais antigo.


        Requer escopo `customers:read`.
      operationId: listCustomers
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum:
              - pf
              - pj
          description: Filtrar por tipo de pessoa
        - name: status
          in: query
          schema:
            type: string
            enum:
              - em_analise
              - aprovado
              - pendencia
              - recusado
          description: >
            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
        - name: external_id
          in: query
          schema:
            type: string
          description: Filtrar pelo identificador interno
        - name: doc
          in: query
          schema:
            type: string
          description: Filtrar por CPF ou CNPJ (sem formatação) — busca por hash
        - name: created_after
          in: query
          schema:
            type: string
            format: date-time
          description: Retornar apenas clientes criados após esta data (ISO 8601)
        - name: created_before
          in: query
          schema:
            type: string
            format: date-time
          description: Retornar apenas clientes criados antes desta data (ISO 8601)
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Número máximo de clientes por página
        - name: cursor
          in: query
          schema:
            type: string
          description: Cursor de paginação retornado em next_cursor da página anterior
        - name: x-kycert-api-version
          in: header
          required: false
          schema:
            type: string
            example: '2026-06-03'
      responses:
        '200':
          description: Lista de clientes
          headers:
            X-Request-Id:
              schema:
                type: string
                format: uuid
            X-Kycert-Api-Version:
              schema:
                type: string
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerList'
              example:
                data:
                  - customer_id: 661e9511-f3ac-52e5-b827-557766551111
                    object: customer
                    status: em_analise
                    type: pf
                    name: João Silva
                    doc: '***'
                    external_id: cust_abc123
                    created_at: '2026-06-12T14:00:00Z'
                    livemode: true
                has_more: false
                livemode: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |
            curl "https://admin.kycert.com.br/api/v1/customers?limit=20" \
              -H "x-api-key: $KYCERT_API_KEY"
        - lang: Node
          label: Node.js
          source: >
            const res = await fetch(
              'https://admin.kycert.com.br/api/v1/customers?limit=20',
              { headers: { 'x-api-key': process.env.KYCERT_API_KEY } },
            )

            const { data, has_more, next_cursor } = await res.json()

            console.log(data.length, 'clientes', has_more ? `próxima:
            ${next_cursor}` : '')
components:
  schemas:
    CustomerList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CustomerSummary'
        has_more:
          type: boolean
        next_cursor:
          type: string
          nullable: true
          description: Cursor para a próxima página (presente quando has_more=true)
        livemode:
          type: boolean
    CustomerSummary:
      type: object
      properties:
        customer_id:
          type: string
          format: uuid
        object:
          type: string
          enum:
            - customer
        status:
          type: string
        type:
          type: string
          enum:
            - pf
            - pj
        name:
          type: string
        doc:
          type: string
          description: >-
            Sempre '***' na listagem — use GET /customers/:id para versão
            mascarada com dígitos
          example: '***'
        external_id:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        livemode:
          type: boolean
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - authorization_error
                - billing_error
                - server_error
            code:
              type: string
              description: Código específico do erro
            message:
              type: string
              description: Descrição legível do erro
            param:
              type: string
              nullable: true
              description: Campo que causou o erro (quando aplicável)
  responses:
    Unauthorized:
      description: API key ausente ou inválida
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_api_key:
              value:
                error:
                  type: authentication_error
                  code: missing_api_key
                  message: API key ausente.
                  param: null
            invalid_api_key:
              value:
                error:
                  type: authentication_error
                  code: invalid_api_key
                  message: API key inválida ou inativa.
                  param: null
    Forbidden:
      description: Escopo insuficiente para esta operação
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: authorization_error
              code: insufficient_scope
              message: Esta chave não tem permissão para criar runs.
              param: null
    InternalError:
      description: Falha interna — tente novamente com backoff exponencial
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: server_error
              code: internal_error
              message: Erro interno. Tente novamente.
              param: null
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: API key no header x-api-key (recomendado)
    BearerToken:
      type: http
      scheme: bearer
      description: API key como Bearer token no header Authorization

````