Skip to main content
Reference material for Job Autocomplete: contract vs current behavior, request parameters, autocomplete-enabled fields, implementation tips for UI builders, and errors. For walk-through examples, see Job Autocomplete and Examples.

​
Guaranteed contract vs current behavior

Use this table to separate the parts you can build against with confidence from the observed behavior that may evolve.
TopicKindWhat it means
Endpoint, HTTP method, auth headersContractPOST /job/search/autocomplete, bearer auth, x-api-version: 2025-11-01.
Request body shapeContractfield and query required, limit optional. No filters or count keys on this scope.
Response body shapeContract{ "suggestions": [ { "value" } ] }. Empty results return {"suggestions": []} with status 200.
limit bounds and defaultContractMinimum 1, maximum 100, default 20.
Error status codesContract400 (invalid request), 401 (unauthorized), 500 (internal).
PricingContractAutocomplete does not consume credits.
Suggestion rankingCurrent behaviorSuggestions are ranked by internal frequency — the ranking signal is not exposed in the response.
Empty-query top valuesCurrent behaviorAn empty query returns the most common values for the field, ranked.
Free-text duplicatesCurrent behaviorFor high-cardinality free-text fields like title, an empty query may return repeated values.

​
Request parameters

ParameterTypeRequiredDescription
fieldstringYesMust be an autocomplete-enabled field — see Autocomplete-enabled fields. Unsupported fields return 400.
querystringYesPartial text to match against indexed values. Pass "" to retrieve the top values for the field by frequency.
limitintegerNoMaximum number of suggestions to return. Minimum 1, maximum 100, default 20.
Unlike Person Autocomplete, Job Autocomplete does not accept a filters scope. The request body is just field, query, and limit.

​
Autocomplete-enabled fields

The field in a Job Autocomplete request must come from a fixed allowlist. Many entries are aliases of one another — for example title, job_title, and job_details.title all autocomplete job titles, so you can use whichever spelling matches the filter path you use on Search Jobs.
FieldWhat it discovers
title · job_title · job_details.titleJob titles
category · job_category · job_details.categoryJob categories
workplace_type · job_details.workplace_typeWorkplace types

​
Verify the live list

Call the endpoint with a deliberately invalid field. The 400 response lists every currently accepted field in its error message: 
curl --request POST \
  --url https://api.crustdata.com/job/search/autocomplete \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "field": "not_a_field",
    "query": "",
    "limit": 1
  }'

​
Implementation tips for UI builders

  • Debounce autocomplete calls to avoid one request per keystroke — 150–300 ms on input idle works well for typeahead UIs. - Seed dropdowns with an empty query. For controlled vocabularies like category, an empty query returns the full set in one call. - De-duplicate free-text fields. High-cardinality fields like title can return repeated values — collapse duplicates before rendering. - Expand location variants. A country may have several indexed spellings (for example United States and United States of America); pass all the variants you need to a Search Jobs filter with the in operator. - Cap limit. Most dropdowns need 5–15 options. A lower limit reduces payload size and speeds up responses.

​
Errors

StatusMeaning
400Invalid request — unsupported field, missing query, or limit out of range.
401Unauthorized — the Authorization header is missing, malformed, or contains an invalid API key.
500Internal server error — retry after a short delay.
Every error uses the nested envelope { "error": { "type", "message", "metadata" } }. A query that matches nothing is not an error — the endpoint returns {"suggestions": []} with a 200 status. 
{
    "error": {
        "type": "invalid_request",
        "message": "Field 'not_a_field' is not supported on scope 'job'. Valid fields: category, city, ..., job_details.title, job_title, ..., state, title, workplace_type",
        "metadata": []
    }
}

​
API reference summary

DetailValue
EndpointPOST /job/search/autocomplete
AuthBearer token + x-api-version: 2025-11-01
Required paramsfield, query
Optional paramslimit (default: 20, max: 100)
Response{ "suggestions": [{ "value": "..." }] }
Empty result200 with "suggestions": []
PricingFree — no credits
Errors400 (unsupported field / bad request), 401 (bad auth), 500 (server error)
See the full API reference for the complete OpenAPI schema.