Endpoint responsible for querying customers registered in the account in a paginated way, with support for filters.

This request is mainly used to locate existing records, validate duplicates, and support synchronization routines between Asaas and external systems.

How pagination works

Customer listing is paginated.

The API returns records in blocks, respecting the navigation parameters sent in the request, ensuring efficiency even in accounts with a large volume of data.

Main request parameters

offset — Defines the starting point of the list
limit — Defines the maximum number of records returned (maximum of 100)
name — Filters by name
email — Filters by email
cpfCnpj — Filters by document number
groupName — Filters by group
externalReference — Filters by source system identifier

Most common use cases

validating whether a customer exists before creation
locating customers by document number or internal reference
synchronizing data between systems
displaying customer lists in administrative interfaces

Use for duplicate prevention

Since the API does not prevent duplicate records, this endpoint is one of the main tools for prior validation before creation.

🚧
Attention
It is recommended to perform this query before creating a customer in order to avoid multiple records representing the same customer.

Recommended use in synchronizations

The combination of externalReference and cpfCnpj tends to produce more reliable results than searches based only on name.

200Ok

400Bad Request

401Unauthorized