close.io lead search api 400
Fix Close's 400 on lead search: the query parameter is malformed or uses unsupported syntax. Use when Close lead search calls return 400, when a search works in the UI but fails through the API, or when previously working searches break. Not for authentication errors, lead creation errors, or rate limits.
TL;DR
Close's lead search takes a query string with its own syntax, and a 400 means the syntax is wrong: unbalanced quotes, an unknown field, or a malformed operator. The UI search box is forgiving; the API is not. Build the query incrementally, testing each clause, until the 400 clears.
The query
close.io lead search api 400Use this when
- Close lead search API calls return 400
- A search works in the UI but fails through the API
- Previously working searches start failing
Not for
- Close authentication errors
- Lead creation or update errors
- Close API rate limits
Steps
1. Start with the simplest query
Search with a single bare term and confirm a 200. Then add clauses one at a time. The clause that introduces the 400 is the broken one. Debugging a ten-clause query all at once is hopeless.
Expected output: a minimal query returning 200.
2. Check field names and operators
The API's searchable fields and operators are documented; the UI accepts shortcuts the API doesn't. Verify each field name and operator against the docs. A renamed custom field breaks searches silently into 400s.
Expected output: every field and operator confirmed in the API docs.
3. Fix quoting and escaping
Multi-word values need quotes, and quotes inside values need escaping. URL-encode the whole query parameter. Unencoded special characters arrive mangled and parse as garbage.
Expected output: the query arriving at Close exactly as constructed.
4. Compare against the UI's actual query
Build the search in the Close UI, then inspect what the UI sends (or replicate it clause by clause). The UI's translation of your intent is the reference implementation.
Expected output: API results matching the UI search results.
Variant phrasings
close api search leads bad request
Step 1's incremental build finds the bad clause fast.
close.io query syntax error
Step 2's field and operator check.
Why it happens
Search syntaxes are mini-languages, and Close's UI hides the language behind a friendly box. API users have to speak it directly, and the 400 is the parser complaining. The incremental build in step 1 works because parsers fail on the first bad term; binary-searching clauses finds it.
Edge cases
- Custom field names in search need their exact API names, not display labels.
- Very broad queries can time out instead of 400ing. Paginate and narrow.
- Search indexes lag writes slightly. A lead created seconds ago may not match yet.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_tFNCNPAaiwjeFWF9lBapCQ
Maintainer review
No maintainer verification is recorded for this version.
This records the version a maintainer checked. It does not assert that the version is the latest upstream release.