Use filters to retrieve only the customers that match your criteria (name, external reference, customer type, ledger account, etc.).

Filtering customers is a common operation in integrations involving CRM systems, billing tools, POS, or ERP platforms.

It helps reduce dataset size, improve performance, and reliably match customers across systems.

This guide explains how to use the filters[] parameter with the /customers endpoint and lists all supported fields and operators.

📘

Reminder: Filters use a JSON array passed as the filters query parameter. See Filter API Data for the general filtering syntax.

How Filtering Works

Customer filtering relies on the API’s standard filters[] format.

Example filter array:

[
  { "field": "name", "operator": "start_with", "value": "Tes" }
]

Example request:

GET /customers?filters=[{"field":"name","operator":"start_with","value":"Tes"}]

You can combine multiple filters in a single request.

Common Use Cases

Developers typically filter customers to:

• Search customers by name (autocomplete or lookup)
• Match customers using an external reference from another system
• Retrieve customers linked to a specific ledger account
• Sync customer lists incrementally
• Power customer selectors in internal tools

Examples

Filter by customer name (autocomplete)

GET /customers?filters=[
  {"field":"name","operator":"start_with","value":"Tes"}
]

Filter by external reference

GET /customers?filters=[
  {"field":"external_reference","operator":"eq","value":"CRM-CUST-445"}
]

Filter by customer type

GET /customers?filters=[
  {"field":"customer_type","operator":"eq","value":"company"}
]

Filter by multiple customer IDs

GET /customers?filters=[
  {"field":"id","operator":"in","value":["cust_123","cust_456"]}
]

Available Fields and Operators

💡

Tip: The start_with operator is ideal for search-as-you-type or autocomplete interfaces.

Tips & Troubleshooting

• URL-encode the filter array to avoid 400 errors.
• Combine filters with pagination when retrieving large datasets (using the pagination mechanism supported by the endpoint).
• Filtering by name is prefix-based, not a full-text search.
• External references and registration numbers use exact matching.
• Trim leading or trailing spaces in filter values.
• Use in / not_in when syncing or reconciling multiple customers at once.
• For incremental updates, combine filters with the Changelog API.