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.