> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crustdata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Person Autocomplete
> Discover valid field values for Person Search filters using the autocomplete API.
**Use this when** you need to discover exact indexed values before building
a Person Search query — for filter dropdowns, input validation, dataset
exploration, or guided query builders.
The Person Autocomplete API returns ranked field-value suggestions so you
can feed the result straight into a [Person Search](/person-docs/search/introduction)
filter without guessing at valid values.
This endpoint returns **field values, not person profiles**. It also has
**no pagination or cursor** — the `limit` parameter (max `100`) is the
only way to control result size. For a full list of distinct values you
need to combine Autocomplete with progressively narrower `filters`
scopes. To fetch person records, use
[Person Search](/person-docs/search/introduction) or
[Person Enrich](/person-docs/enrichment/introduction) instead.
**Mental model.** The top-level **`field`** is the field whose values
you want suggested — the autocomplete target. **`filters.field`** is
different: it's any Person Search filter field you use to narrow the
population that autocomplete runs over. Autocomplete targets come from a
fixed allowlist; filter fields come from the broader Person Search
filter vocabulary.
Replace `YOUR_API_KEY` in each example with your actual API key. All
requests require the `x-api-version: 2025-11-01` header.
### At a glance
| Detail | Value |
| --------------- | -------------------------------------------------------------------------------------- |
| **Endpoint** | `POST https://api.crustdata.com/person/search/autocomplete` |
| **Auth** | `Authorization: Bearer YOUR_API_KEY` |
| **API version** | `x-api-version: 2025-11-01` header (required) |
| **Required** | `field` (string) · `query` (string, may be empty) |
| **Optional** | `limit` (integer, 1–100, default 20) · `filters` (single condition or condition group) |
| **Response** | `{ "suggestions": [ { "value": string } ] }` |
| **Errors** | `400` invalid request · `401` unauthorized · `500` internal |
| **Pricing** | Free — see [Pricing](/general/pricing#person-apis). |
Default `rate-limit` is 45 requests per minute. Send an email to
[gtm@crustdata.co](mailto:gtm@crustdata.co) to discuss higher limits if
needed for your use case.
Most-common values, narrow with filters, multi-value, numeric
comparisons, Autocomplete → Search workflow.
Contract, operators, request parameters, autocomplete-enabled
fields, implementation tips, and errors.
***
## When to use Autocomplete vs Search
| You want to… | Use |
| ------------------------------------------------------ | ----------------------------------------------------- |
| Discover valid filter values for a field | **Autocomplete** (this page) |
| See the distinct values a field takes, ranked by count | **Autocomplete** with an empty `query` |
| Return actual person profiles matching filters | [**Person Search**](/person-docs/search/introduction) |
| Build a type-ahead dropdown for a filter UI | **Autocomplete** with a partial `query` |
| Build a live multi-field query that returns full rows | [**Person Search**](/person-docs/search/introduction) |
***
## Quick start: discover job title values
Type-ahead lookup on a single field. Pass the user's partial input as
`query` and cap the dropdown size with `limit`.
```bash curl theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/person/search/autocomplete \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"field": "experience.employment_details.current.title",
"query": "VP",
"limit": 5
}'
```
```python Python theme={"theme":"vitesse-black"}
import os
import requests
response = requests.post(
"https://api.crustdata.com/person/search/autocomplete",
headers={
"Authorization": f"Bearer {os.environ['CRUSTDATA_API_KEY']}",
"Content-Type": "application/json",
"x-api-version": "2025-11-01",
},
json={
"field": "experience.employment_details.current.title",
"query": "VP",
"limit": 5,
},
)
response.raise_for_status()
suggestions = response.json()["suggestions"]
```
```javascript Node.js theme={"theme":"vitesse-black"}
const response = await fetch(
"https://api.crustdata.com/person/search/autocomplete",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CRUSTDATA_API_KEY}`,
"Content-Type": "application/json",
"x-api-version": "2025-11-01",
},
body: JSON.stringify({
field: "experience.employment_details.current.title",
query: "VP",
limit: 5,
}),
},
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { suggestions } = await response.json();
```
```json Response theme={"theme":"vitesse-black"}
{
"suggestions": [
{ "value": "VP" },
{ "value": "VP of Sales" },
{ "value": "vp" },
{ "value": "VP Sales" },
{ "value": "VP Operations" }
]
}
```
Each suggestion includes:
* **`value`** — the exact **indexed value**: the raw string stored against `field` in Crustdata's person index. Use it verbatim as a Person Search filter value — two distinct indexed values (for example `"VP"` and `"vp"`) are different filter keys, and substituting one for the other will return different results.
Suggestions are returned ranked by internal frequency within the
(optionally filtered) population. The ranking signal itself is not returned
in the response.
When no values match the `query` (or no values exist within the `filters`
scope), the response returns an empty array — not a 404:
```json No results theme={"theme":"vitesse-black"}
{
"suggestions": []
}
```
***
## What to do next
* **Try more patterns** — see [Examples](/person-docs/autocomplete/examples) for most-common values, filtered suggestions, and the Autocomplete → Search workflow.
* **Reference** — see [Autocomplete reference](/person-docs/autocomplete/reference) for operators, request parameters, autocomplete-enabled fields, implementation tips, and errors.
* **Search for people** — use discovered values in [Person Search](/person-docs/search/introduction).
* **Enrich matches** — use [Person Enrich](/person-docs/enrichment/introduction) to get full profiles.