Skip to main content
GET
/
v1
/
customers
Listar clientes
curl --request GET \
  --url https://api.payle.digital/v1/customers \
  --header 'x-api-key: <api-key>'
{
  "object": "list",
  "url": "/v1/customers",
  "hasMore": false,
  "totalCount": 1,
  "data": [
    {
      "id": "cus_01hr8m2aym6rd0sx2xv5hek0nv",
      "object": "customer",
      "createdAt": "2025-10-21T13:55:21.000Z",
      "updatedAt": "2025-10-21T13:55:21.000Z",
      "name": "Maria Souza",
      "email": "[email protected]",
      "phone": "+55 11 99999-0000",
      "document": "12345678901"
    }
  ]
}

​
Quando usar

Utilize para recuperar clientes existentes, aplicar filtros por email, nome, documento ou faixa de criacao e construir listagens no seu sistema.

​
Cabecalhos obrigatorios

  • x-api-key: <sua-chave>.
  • Accept: application/json.

​
Parametros de consulta

ParametroTipoDescricao
filter[email]stringFiltra clientes cujo email contenha o valor informado (case insensitive).
filter[name]stringFiltra clientes cujo nome contenha o valor informado.
filter[document]stringFiltra por CPF ou CNPJ (parcial).
filter[created][gte]string (date-time)Retorna clientes criados a partir da data UTC informada.
filter[created][lte]string (date-time)Retorna clientes criados ate a data UTC informada.
order[orderBy]stringCampo para ordenacao. Padrao: createdAt.
order[orderDirection]string (asc ou desc)Direcao da ordenacao. Padrao: desc.
pagination[limit]numberQuantidade de itens por pagina (1 a 100, padrao 10).
pagination[page]numberNumero da pagina inicial (padrao 1).

​
Exemplo de chamada

curl "https://api.payle.digital/v1/customers?filter[email]=maria&pagination[limit]=20" \
  -H "x-api-key: pk_test_123"

​
Resposta bem-sucedida

  • Status: 200 OK
  • Corpo segue o esquema ListCustomersResponse.
{
  "object": "list",
  "url": "/v1/customers",
  "hasMore": false,
  "totalCount": 1,
  "data": [
    {
      "id": "cus_01hr8m2aym6rd0sx2xv5hek0nv",
      "object": "customer",
      "createdAt": "2025-10-21T13:55:21.000Z",
      "updatedAt": "2025-10-21T13:55:21.000Z",
      "name": "Maria Souza",
      "email": "[email protected]",
      "phone": "+55 11 99999-0000",
      "document": "12345678901"
    }
  ]
}

​
Tratamento de erros

  • 401 Unauthorized: cabecalhos de autenticacao ausentes ou invalidos.
  • 403 Forbidden: conta autenticada nao aprovada.
  • 429 Too Many Requests: limite de requisicoes excedido.
Use o correlationId retornado para rastrear chamadas em nosso suporte.

Authorizations

​
x-api-key
string
header
required

Chave gerada no dashboard Payle.

Query Parameters

​
filter[email]
string

Filtra por email (match parcial).

​
filter[name]
string

Filtra por nome (match parcial).

​
filter[document]
string

Filtra por documento (match parcial).

​
filter[created][gte]
string<date-time>

Retorna clientes criados a partir da data (UTC).

​
filter[created][lte]
string<date-time>

Retorna clientes criados ate a data (UTC).

​
order[orderBy]
string

Campo para ordenacao (ex.: createdAt, name, email).

​
order[orderDirection]
enum<string>

Direcao da ordenacao.

Available options:
asc,
desc
​
pagination[limit]
integer

Quantidade de registros por pagina (1-100, padrao 10).

Required range: 1 <= x <= 100
​
pagination[page]
integer

Numero da pagina baseado em 1.

Required range: x >= 1

Response

Lista de clientes retornada com sucesso.

​
object
enum<string>
required

Identificador do tipo de retorno.

Available options:
list
Example:

"list"

​
url
string
required

Caminho do recurso listado.

Example:

"/v1/customers"

​
hasMore
boolean
required

Indica se ha mais paginas.

Example:

false

​
data
object[]
required

Clientes retornados.

​
totalCount
integer

Total de registros encontrados.

Example:

1