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

# Buscar cliente

> Retorna os dados completos de um cliente, incluindo o run de bureau mais recente.

Requer escopo `customers:read`.


## Campo `doc`

O CPF ou CNPJ é retornado mascarado, com dígitos parciais visíveis:

* CPF: `***456789**`
* CNPJ: `**34567890****`

O documento nunca é retornado em claro pela API.

## Campo `latest_run`

Retorna o run de bureau mais recente associado ao cliente, ou `null` se nenhum run foi executado ainda.

```json theme={null}
{
  "latest_run": {
    "run_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "decision": "approved",
    "risk_band": "baixo",
    "completed_at": "2026-06-12T14:00:18Z"
  }
}
```

Para o resultado completo com todos os checks, use [GET /runs/:id/analysis](/api-reference/getRunAnalysis).


## OpenAPI

````yaml GET /api/v1/customers/{id}
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/{id}:
    get:
      tags:
        - Customers
      summary: Buscar cliente por ID
      description: >
        Retorna os dados completos de um cliente, incluindo o run de bureau mais
        recente.


        Requer escopo `customers:read`.
      operationId: getCustomer
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID do cliente retornado pelo POST /customers
        - name: x-kycert-api-version
          in: header
          required: false
          schema:
            type: string
            example: '2026-06-03'
      responses:
        '200':
          description: Dados completos do cliente
          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/CustomerDetail'
              example:
                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
                birth_date: '1990-05-15'
                latest_run:
                  run_id: 550e8400-e29b-41d4-a716-446655440000
                  status: completed
                  decision: approved
                  risk_band: baixo
                  completed_at: '2026-06-12T14:00:18Z'
                created_at: '2026-06-12T14:00:00Z'
                updated_at: '2026-06-12T14:00:18Z'
                livemode: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/CustomerNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |
            curl "https://admin.kycert.com.br/api/v1/customers/CUSTOMER_ID" \
              -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/${customerId}`,
              { headers: { 'x-api-key': process.env.KYCERT_API_KEY } },
            )

            const customer = await res.json()

            console.log(customer.name, customer.doc,
            customer.latest_run?.decision)
components:
  schemas:
    CustomerDetail:
      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
        email:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        doc:
          type: string
          description: CPF/CNPJ mascarado com dígitos parciais visíveis
          example: '***456789**'
        external_id:
          type: string
          nullable: true
        birth_date:
          type: string
          nullable: true
          format: date
          description: Apenas PF
        address:
          type: object
          nullable: true
          description: Apenas PF
        latest_run:
          type: object
          nullable: true
          description: Run de bureau mais recente associado ao cliente
          properties:
            run_id:
              type: string
              format: uuid
            status:
              type: string
            decision:
              type: string
              nullable: true
            risk_band:
              type: string
              nullable: true
            completed_at:
              type: string
              nullable: true
              format: date-time
        created_at:
          type: string
          format: date-time
        updated_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
    CustomerNotFound:
      description: Cliente não encontrado ou não pertence ao tenant
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: invalid_request_error
              code: customer_not_found
              message: Cliente não encontrado.
              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

````