You are viewing the documentation of the new API versions. We would love to hear from you. You can write to use at support@crustdata.co for feedback and clarifications.
Reference for Person Autocomplete: contract vs current behavior, supported operators, request parameters, autocomplete-enabled fields, implementation tips, and errors.
Reference material for Person Autocomplete:
contract vs current behavior, supported filter operators, request
parameters, autocomplete-enabled fields, implementation tips for UI
builders, and errors.For walk-through examples, see
Person Autocomplete and
Recipes.
The type field on every AutocompleteFilterCondition accepts the same
operators as Person Search filters.
The greater-than-or-equal operator is => (not >=) and
less-than-or-equal is =< (not <=). This is intentional — do not
mistype them as the more common <= and >=.
Operator
value shape
Meaning
=
string, number, integer, or boolean
Exact match — the field value equals value.
!=
string, number, integer, or boolean
Not equal — the field value differs from value.
<
number or ISO date string
Less than — numeric or date comparison.
=<
number or ISO date string
Less than or equal — numeric or date comparison.
>
number or ISO date string
Greater than — numeric or date comparison.
=>
number or ISO date string
Greater than or equal — numeric or date comparison.
in
array of strings, numbers, or integers
Membership — field value matches any entry in the array.
not_in
array of strings, numbers, or integers
Negated membership — field value matches none of the entries in the array.
contains
string
Substring match — field value contains value.
Pass values with the JSON type that matches the underlying field:
"value": 10000 for numeric fields, "value": true for booleans, and
strings for text fields. in and not_in require a JSON array — a
comma-separated string will return a 400.
Operator footguns. Use => for greater-than-or-equal and =< for
less-than-or-equal — these are not>= and <=. in / not_in
require JSON arrays (not comma-separated strings).
Parameter
Type
Required
Description
field
string
Yes
Dataset field whose values you want suggested. Must be an autocomplete-enabled field — see Autocomplete-enabled fields. Unsupported fields return 400.
query
string
Yes
Partial text to match against indexed values. Pass "" to retrieve the top values for the field by frequency.
limit
integer
No
Maximum number of suggestions to return. Minimum 1, maximum 100, default 20.
filters
object
No
Optional scope for the autocomplete computation. Pass either a single AutocompleteFilterCondition or a nested AutocompleteFilterConditionGroup.
The top-level field in a Person Autocomplete request (the field whose
values you want suggested) must come from a fixed allowlist of
autocomplete-enabled dataset fields. Not every Person Search field is
autocomplete-enabled.The filters.field is different: it can be any dataset field that
Person Search accepts as a filter, not only the
autocomplete allowlist. So you can filter autocomplete results on a broader
set of fields than you can autocomplete on directly.
The tables below are a documented subset of the autocomplete
allowlist. They cover the fields most useful for building filter
dropdowns, but they are not exhaustive. If a field you need is not
listed, treat its support as unknown until you verify it — the safest
way to confirm is to call the endpoint with that field and check
whether you get a 400 error. See Verify the live list
below for the debug-only live source.
company_name vs name for employers (current behavior). Both
experience.employment_details.current.company_name and
experience.employment_details.current.name are currently accepted
and return the current employer. Prefer company_name for clarity;
name is an alternative spelling retained for backwards compatibility
and may eventually be removed.
Debug fallback only — do not parse this error message in production
code. The 400 error message is a human-readable debugging aid, not
a stable API surface. Its shape, ordering, and field list can change
without notice. Use it during development to confirm whether a
specific field is autocomplete-enabled, then maintain your own
allowlist or rely on the common-fields tables above.
Call the endpoint with a deliberately invalid field. The 400 response
lists every currently accepted field in its error message:
Debounce autocomplete calls to avoid one request per keystroke — 150–300 ms on input idle works well for typeahead UIs.
Drop blank values. If "" is returned as the top suggestion, remove it before rendering the dropdown.
Handle casing variants carefully. Suggestions like "VP" and "vp" are distinct indexed values. Only merge them into a single UI option if you intentionally want normalized grouping — and if you do, preserve the underlying raw values and expand them in the eventual Person Search filter using in, for example {"type": "in", "value": ["VP", "vp"]}. If the UI needs exact-value selection, keep them as separate options.
Cap limit. Most dropdowns need 5–15 options. Lower limit reduces payload size and gives faster responses.
Cache top-values lookups. Empty-query calls that seed filter dropdowns rarely change — cache them client-side or at the edge.
Invalid request — unsupported field, missing required field, a wrong value shape (for example a comma string for in), or a malformed body.
401
Unauthorized — the Authorization header is missing, malformed, or contains an invalid API key.
500
Internal server error — retry after a short delay.
Note: a query that matches nothing is not an error — the endpoint
returns {"suggestions": []} with a 200 status. Only use 4xx/5xx handling
for actual request or server failures.
{ "error": { "type": "invalid_request", "message": "Field 'current_title' is not valid for autocomplete. Available fields are: basic_profile.headline, ..., experience.employment_details.current.function_category, experience.employment_details.current.title, ..., skills.professional_network_skills, social_handles.twitter_identifier.slug", "metadata": [] }}
