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

# Listar Clientes

> Liste os clientes da sua conta, com busca e filtro por status de inadimplência

## Visão Geral

Lista os clientes vinculados à conta autenticada, do mais recente para o mais antigo.

## Headers

<ParamField header="Authorization" type="string" required>
  Sua chave de API (`Bearer sk_live_...`)
</ParamField>

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Página desejada
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Itens por página, máximo 100
</ParamField>

<ParamField query="search" type="string">
  Busca por nome, e-mail ou documento
</ParamField>

<ParamField query="status" type="string">
  `overdue` retorna apenas clientes com pelo menos uma cobrança agendada (avulsa, recorrente ou carnê) em atraso
</ParamField>

## Exemplo de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://garu.com.br/api/v1/customers \
    -H "Authorization: Bearer sk_live_sua_chave_api" \
    -d search=maria \
    -d limit=50
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({ search: 'maria', limit: '50' });

  const response = await fetch(`https://garu.com.br/api/v1/customers?${params}`, {
    headers: { Authorization: `Bearer ${process.env.GARU_API_KEY}` }
  });

  const { data, totalCount } = await response.json();
  console.log(`${data.length} de ${totalCount} clientes`);
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      "https://garu.com.br/api/v1/customers",
      headers={"Authorization": f"Bearer {os.environ['GARU_API_KEY']}"},
      params={"search": "maria", "limit": 50},
  )

  body = response.json()
  print(f"{len(body['data'])} de {body['totalCount']} clientes")
  ```
</CodeGroup>

## Resposta de Sucesso (200 OK)

```json theme={null}
{
  "data": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Maria Silva",
      "email": "maria@exemplo.com.br",
      "phone": "11987654321",
      "document": "12345678909",
      "personType": "fisica",
      "zipCode": null,
      "street": null,
      "number": null,
      "complement": null,
      "neighborhood": null,
      "city": null,
      "state": null,
      "billingEmail": "maria@exemplo.com.br",
      "hasBillingEmailOverride": false,
      "createdAt": "2026-01-15T10:30:00.000Z",
      "updatedAt": "2026-01-15T10:30:00.000Z"
    }
  ],
  "count": 1,
  "totalCount": 42,
  "totalPages": 3
}
```

| Campo        | Significado                                |
| ------------ | ------------------------------------------ |
| `count`      | Itens nesta página                         |
| `totalCount` | Total de clientes que casam com os filtros |
| `totalPages` | Número de páginas com o `limit` informado  |

## Erros

| Código | Quando acontece                  |
| ------ | -------------------------------- |
| `401`  | Chave de API ausente ou inválida |