Find a customer by name, email or number (fuzzy)
easybill_find_customerFind existing customers by name, email, number, or city. Prevent duplicate records before creating invoices or offers, with fuzzy matching for typos and legal form differences.
Instructions
Search for an existing customer by company name, person name, email, customer number or city.
USE THIS FIRST whenever you need to know whether someone is already a customer — for example before creating an offer or invoice from an inbound inquiry. The easybill API has no full-text search, so this tool combines exact filters with a local fuzzy match over the customer list.
It tolerates the differences that break exact matching: legal forms ('GmbH & Co. KG'), punctuation ('M.B. MUSTERMANN' vs 'MB Mustermann'), umlauts, and word order.
Args:
query (string): what to search for. A company name, surname, email or customer number.
limit (number): max candidates to return, 1-25 (default 5).
min_score (number): 0-1 match threshold (default 0.5). Lower it to cast a wider net.
max_pages (number): how many pages of 1000 customers to scan in the fallback (default 3). Each page is one API request, so keep this low on a plan with a 10 req/min limit.
Returns: { query, match_count, exact_match (boolean), candidates[] } where each candidate has its easybill 'id', 'match_score' (1 = certain) and the usual summary fields.
Next steps based on the result:
Exactly one strong candidate (score 1) -> use its 'id' as customer_id.
Several candidates -> show them to the user and ask which one, do NOT guess.
No candidates -> the customer does not exist yet. Create it with easybill_create_customer, then use the returned 'id'.
Examples:
"Is Mustermann Handels GmbH & Co. KG already a customer?" -> query="Mustermann Handels GmbH & Co. KG"
"Find the customer with email einkauf@example.com" -> query="einkauf@example.com"
"Look up customer number 10023" -> query="10023"
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max candidates to return. | |
| query | Yes | Company name, person name, email address, customer number or city. | |
| max_pages | No | Pages of 1000 customers to scan in the fuzzy fallback. Each costs 1 request. | |
| min_score | No | Minimum match score, 0-1. Lower for a wider net. | |
| response_format | No | Output format: 'markdown' for readable prose, 'json' for machine-readable data | markdown |