List customers
Look up customers in your account with filters and cursor pagination.
Looks up customers registered in the company and environment of your API key. Use the filters to find a customer by identifier, name, email, CPF/CNPJ or the external reference from your system.
Start without a cursor, process list and, while page.has_next is true,
copy page.next_after to after, keeping the filters. Copy the entire
cursor without interpreting or calculating its contents. See
Listing and pagination to go back with before.
See how filters and sorting work in List customers.
Query Params
Number of customers per page. Positive integers above the maximum use the maximum. An omitted, empty, zero, negative, or invalid value uses 10.
From 1 to 100
Copy page.next_after from the previous response to move forward. Use the cursor unchanged, keep the same filters, and do not send before together with it.
Up to 128 characters
Copy page.previous_before from the previous response to move back one page. Keep the same filters and do not send after together with it.
Up to 128 characters
The customer's public identifier, with the cus_ prefix.
Up to 100 characters
Searches by customer name, with the most recent records first. Leave empty to ignore this filter.
2 to 120 characters
Filters by the customer's complete email.
Up to 254 characters
Filters by the customer's complete CPF or CNPJ, with or without periods, slash, hyphen, and spaces.
Up to 20 characters
Filters by the customer's current reference in your system, matching the complete value, including letter case and accents. Can be combined with other filters. After creating or editing the customer, the search can take a few seconds to reflect the reference. Keep the value when navigating by cursor.
Up to 120 characters
Responses
For common errors, see HTTP response codes.