Clientes
Listar Clientes
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.
/v1/customershttps://api.validapay.com.brhttps://sandbox.validapay.com.brAuthorizations
Authorization
string · header · required
Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.
Escopos requeridos
Query Parameters
| Name | Type | Value | Required | Description |
|---|---|---|---|---|
| limit | - | 15 | Optional | Quantidade de itens por página (default 15) - optional |
| lastKey | - | - | Required | Cursor da próxima página, em base64, retornado em pagination.lastKey - optional |
| search | - | - | Required | Busca parcial por nome, e-mail ou documento - optional |
| document | - | - | Required | Filtro por CPF/CNPJ exato, apenas dígitos - optional |
| status | - | - | Required | ACTIVE | INACTIVE | BLOCKED - optional |
| startDate | - | - | Required | Data inicial de criação (ISO 8601) - optional |
| endDate | - | - | Required | Data final de criação (ISO 8601) - optional |
const url = 'https://sandbox.validapay.com.br/v1/customers?limit=15&lastKey=&search=&document=&status=&startDate=&endDate=?limit=15';
const options = {
method: 'GET',
headers: {
'Authorization': 'Bearer {{token}}'
},
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));Response Examples
{
"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...="
}
}