listCustomers
listCustomersRetrieve a paginated list of customers with options to search, filter by ID, email, phone, or status, and control sorting.
Instructions
Retrieve a paginated list of customers, with options for searching, filtering by ID, external ID, email, phone number, communication status, auto-charge status, creation date, customer name, and business entity ID.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | The cursor for pagination to fetch the next or previous set of records. | |
| limit | No | Maximum number of customers to return per page (defaults to 10). | |
| search | No | Advanced key-value search query. Format: 'field=value' or 'field1=value1,field2=value2'. Supports any customer field including nested JSON paths. Examples: 'customer_name=Acme', 'email=john@example.com', 'customer_name=Acme,external_id=EXT-100', 'custom_data.users=abc@dev.in'. String fields use case-insensitive contains matching. Do NOT pass plain text — always use field=value format. | |
| search_name_external_id | No | Quick relevance-ranked search across customer_name and external_id. Accepts plain text (e.g., 'Acme'). Results are ranked: exact match first, then starts-with, then contains. Simpler alternative to the 'search' parameter when you only need to find customers by name or external ID. | |
| order | No | Order of results (e.g., '-created_at' for descending creation date). | -created_at |
| sort_key | No | Key to sort the results by (e.g., 'id'). | |
| sort_type | No | Sort order type (e.g., 'asc' for ascending). | |
| expand | No | Fields to expand in the response (e.g., 'contacts'). | |
| id | No | Filter by customer ID (exact match). | |
| id__in | No | Filter by a comma-separated list of customer IDs. | |
| external_id | No | Filter by external ID (exact match). | |
| external_id__ilike | No | Case-insensitive partial match for external ID. | |
| No | Filter by email (exact match). | ||
| email__ilike | No | Case-insensitive partial match for email. | |
| phone_number__ilike | No | Case-insensitive partial match for phone number. | |
| communications_enabled | No | Filter by communications enabled status. | |
| auto_charge_enabled | No | Filter by auto-charge enabled status. | |
| created_at__gte | No | Filter by creation date greater than or equal to (ISO 8601 format). | |
| created_at__lte | No | Filter by creation date less than or equal to (ISO 8601 format). | |
| customer_name__ilike | No | Case-insensitive partial match for customer name. | |
| business_entity_id | No | Filter by business entity ID (exact match). | |
| invoice__customer_id | No | Filter by invoice customer ID. | |
| invoice__status | No | Filter by invoice status. | |
| __userContext | No | Internal user context for multi-tenant authentication and approval workflow |