# Listar Clientes
`GET /v1/customers`
**Área:** Clientes

**Scopes necessários:** `customers/read`

Lista os clientes cadastrados na sua conta, com busca por texto e paginação por cursor.

O parâmetro search faz busca parcial simultânea em nome, e-mail e documento — é o filtro indicado para uma tela de seleção de cliente, onde o usuário pode digitar qualquer um dos três. Já document faz correspondência exata e deve ser usado quando o CPF/CNPJ completo já é conhecido.

A paginação é por cursor: quando houver mais páginas, pagination.lastKey vem preenchido; repita a chamada enviando esse valor em lastKey, mantendo os mesmos filtros. Quando lastKey vier null, não há mais páginas.

Case de uso:

_Como integrador, quero buscar um cliente já cadastrado por nome, e-mail ou CPF/CNPJ, para preencher automaticamente os dados na hora de criar uma nova cobrança._

### Query parameters

| Campo | Obrigatório | Descrição |
|---|---|---|
| `lastKey` | **sim** | Cursor da próxima página, em base64, retornado em pagination.lastKey - optional |
| `search` | **sim** | Busca parcial por nome, e-mail ou documento - optional |
| `document` | **sim** | Filtro por CPF/CNPJ exato, apenas dígitos - optional |
| `status` | **sim** | ACTIVE \| INACTIVE \| BLOCKED - optional |
| `startDate` | **sim** | Data inicial de criação (ISO 8601) - optional |
| `endDate` | **sim** | Data final de criação (ISO 8601) - optional |
| `limit` | não | Quantidade de itens por página (default 15) - optional |

### Resposta 200 — 200

```json
{
  "items": [
    {
      "customerId": "cus_xxx",
      "name": "Alexandre Souza",
      "document": "11144477735",
      "email": "alexandre@exemplo.com.br",
      "phone": "5511987654321",
      "status": "ACTIVE",
      "createdAt": "2026-08-28T12:00:00.000Z",
      "subscriptions": []
    }
  ],
  "pagination": {
    "total": 128,
    "totalPages": 9,
    "limit": 15,
    "hasMore": true,
    "lastKey": "eyJQSyI6...="
  }
}
```

---
Página: https://docs.validapay.com.br/documentacao-validapay2/get-listar-clientes
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json