For AI Agents
Autocomplete — full reference
All four resources expose GET /v1/{resource}/autocomplete with the same request and response shape. The only per-resource variation is the narrow column= allowlist.
Request
| Param | Required | Notes |
|---|---|---|
query | Yes (or search) | Search string. Minimum 2 characters — 1 char or missing returns 400 VALIDATION_ERROR. |
search | Yes (or query) | Alias of query. Both names accepted by validation; matching behavior is the same except on companies where search= is the more reliable choice. |
column | No | Which column to autocomplete against. Must be on the per-resource allowlist (table below) — otherwise 400 VALIDATION_ERROR. Each resource has a sensible default; you only need this to target a non-default column. |
limit | No | Cap on results. No explicit upper bound, but always set this — omitting it on companies can produce slow/timing-out responses. |
Response
Identical shape across all four resources:
json
{
"ok": true,
"data": [
{
"id": "a804f56c-329f-4c1b-9e8e-839a5c98d4a3",
"label": "Lockton Affinity, LLC - Lockton Affinity, LLC",
"resource": "broker-offices",
"value": "Lockton Affinity, LLC"
}
],
"meta": { "credits_charged": 0, "returned": 1 }
}label— the display string, often a fully-qualified form (e.g. broker name + office location).value— the raw column value, suitable for echoing back into asearch=filter on the list endpoint.id— entity ID when returned. Use lookup or list endpoints when you need a stable full-record enrichment contract.resource— echoes which resource the row came from.
Per-resource matrix
| Resource | column= allowlist | Default column | id populated? | Notes |
|---|---|---|---|---|
companies | company_name, website | company_name | Yes | Use ?search= rather than ?query=. Always pass limit= to avoid timeouts. |
personnel | full_name, title | full_name | Yes | first_name, last_name, email_address, company_name all return 400. |
broker-offices | office_name | office_name | Yes | Returns broker office IDs for direct office lookup and filters. |
brokers | broker_name | broker_name | Yes | For exact enrichment, prefer GET /v1/brokers/lookup?name=... (returns 404 on miss, 400 with suggestions on ambiguous). |
When to use autocomplete vs alternatives
- UI typeahead: always use autocomplete. The free cost + label/value shape is designed for this.
- Name → ID resolution: autocomplete may return an
id, but lookup or list endpoints are the safer contract when an enrichment identifier must be stable. - Full record enrichment: use the resource list endpoint with
?search=<token>&page_size=1plus a narrowing filter, or/lookupfor brokers (exact name match) and companies (exact domain/name/EIN). - "Does this name exist?" probes: autocomplete with
limit=1is the cheapest answer (0 credits).
Related
- AI Agent Guide — pitfalls, the five universal query params, discovery flow.
- Recipe library — copy-paste flows that use autocomplete and its alternatives.
- Endpoint index — every operation the live API exposes today.
Need a key?
Keys are issued by our team, not a signup form. Book a 25-minute walkthrough and you'll leave with sandbox and live credentials.