# Search Suggestions `POST https://api.getprospect.com/v2/search/suggest` Typeahead suggestions for the open-ended People Search and Company Search filters, plus person and company lookups by name. Send the text the user has typed so far (or nothing - an empty query browses each vocabulary, most popular first for locations, job titles and company keywords, so a picker can open pre-filled; `person` and `company` are the exceptions and need at least 2 characters) and one vocabulary type - location, job_title, industry, company_keywords, technology, person or company - and get back up to 25 ready-to-use rows. For location, job_title, industry and company_keywords, each row carries a `value` you pass as-is to the matching filter (person_location / company_location, person_job_title, company_industry, company_keywords). For `person`, `value` feeds `person.name` (search everyone with that name) and `id` feeds `person.id` (pin exactly that one person); each row also carries their current job title and company with its logo. For `company`, `value` is the canonical company name and each row carries the id `company.id` (People Search) accepts, a domain attached to the company (its website when none is attached), logo, industry and employee range - matched by a prefix of the name or of any attached domain. Person and company rows carry `saved: true` when your workspace has saved them, and saved matches are listed first. A complete email address as the `person` query finds the person that address is stored on (people your workspace saved or revealed with it come first), and as the `company` query finds the company by its domain. A LinkedIn profile URL as the `person` query finds that person. A LinkedIn company URL as the `company` query finds that company. Every suggestion repeats the requested `type`, so a mixed list stays self-describing. Location suggestions include the structured parts (city, state, country, ISO country code) and a level; job-title suggestions map abbreviations like "ceo" to their canonical title and tolerate a rephrasing ("VP of Marketing" and "Marketing VP" both suggest "Vice President Marketing"); industry suggestions include the category group; company-keyword suggestions carry a `company_count` and match a prefix of any word, so "market" finds both "Marketing" and "Digital Marketing". For `technology`, rows mark technology vs category with `kind`, and `value` is the id the matching filter (company_technologies / company_technology_categories) takes. For the closed vocabularies (departments, seniorities, countries, employee ranges and more) fetch the full lists from GET /v2/enums instead. Free: costs no credits; a person lookup by email address or LinkedIn URL counts against the per-second window of the enrich rate limit (0 units), every other suggestion against no limit. Authenticate with your API key in the x-api-key header. > **How are credits spent?** > > Suggestions are free and consume no credits. Use them as liberally as a > typeahead needs - the endpoint is built to be called on every keystroke. ## One vocabulary per request Send the text the user has typed so far and one `type`; the response is up to 25 ready-to-use filter values, best match first. The query is optional for every vocabulary except `person` - omit it, or send an empty string, to browse a vocabulary rather than search it: locations return top regions and the most popular places, job titles the most-held titles, industries the alphabetical head of the list, and company keywords the most widely declared specialties, so a picker can open pre-filled. `person` is the exception: it has no browse mode and always requires a query. Each suggestion's `value` can be passed as-is to the matching search filter: - **`location`** - suggests places for `person_location` / `company_location` on [People Search](https://getprospect.com/api-docs/people-search.md) and `company_location` on [Company Search](https://getprospect.com/api-docs/company-search.md). Each suggestion carries the unified string (`"Austin, Texas, United States"`), its structured parts (`city`, `state`, `state_code`, `country`, `country_code`), and a `level` of `region`, `country`, `state` or `city`. Regions such as `DACH` or `EMEA` span several countries, so they leave `country` and `country_code` null and carry `country_codes` - their member countries - instead; the full region catalog is `GET /v2/enums/regions` on [Enums](https://getprospect.com/api-docs/enums.md). Typing a common alias works too - `usa` suggests United States, `bombay` suggests Mumbai - and codes match exactly: `gb` suggests United Kingdom, `tx` suggests Texas. - **`job_title`** - suggests canonical titles from our job-title catalog for `person_job_title`. Abbreviations resolve to the canonical spelling: `ceo` suggests "Chief Executive Officer", which the search then matches in both spellings. - **`person`** - suggests specific people for `person.id` / `person.name` on [People Search](https://getprospect.com/api-docs/people-search.md). Unlike the other vocabularies this one needs at least **2 characters** and has no browse mode - "the most popular people" is not a list. Every word you type must appear in the person's name and the last one matches as a prefix, so `Dmytro Shu` and `Shulha Dmy` both suggest the same person. Each row carries `value` (the name, ready for `person.name`), `id` (ready for `person.id`), the person's current `job_title`, their `company` with its `logo`, and `linkedin_url`. Pass `value` to search everyone with that name, or `id` to pin that one person: ```json [ { "value": "Dmytro Shulha", "id": "69cfd8b2cfefb668329bab73", "job_title": "Chief Executive Officer", "company": { "id": "66b1f0a2e4b0c8d9f1a2b3c4", "name": "Four Ages Software", "logo": "https://logos.getprospect.com/4a9f2c1e.jpg" }, "linkedin_url": "https://www.linkedin.com/in/dshulha" } ] ``` - **`industry`** - suggests accepted `company_industry` values, each with its category `group` for building grouped pickers. - **`company_keywords`** - suggests company specialties for the `company_keywords` filter on both [People Search](https://getprospect.com/api-docs/people-search.md) and [Company Search](https://getprospect.com/api-docs/company-search.md). Each suggestion carries a `company_count` - how many companies declare that specialty - and rows come back most-declared first, so the head of the list is the vocabulary that will actually return results. Only specialties declared by enough companies to be useful as a filter are suggested; one-off text a single company wrote about itself is not a keyword: ```json [ { "value": "Email Marketing", "company_count": 57393 }, { "value": "Email Deliverability", "company_count": 539 }, { "value": "Email Automation", "company_count": 1216 } ] ``` For `location`, `job_title`, `industry` and `company_keywords`, matching is case- and diacritic-insensitive, and the query can hit the start of a value or an inner word - `market` suggests both "Marketing Manager" and "Digital Marketing Manager". `person` is case-insensitive too, but diacritics are significant there, exactly as they are for `person.name` on People Search: `Jose Alv` and `José Álv` suggest different people. ## Closed vocabularies Suggestions cover the open-ended fields only. The closed lists - departments, seniorities, countries, employee ranges, company types, business types, revenue streams and keyword *sources* (the list of fields `company_keywords` can search, not the keywords themselves) - are small and fixed; fetch them once from [Enums](https://getprospect.com/api-docs/enums.md) and filter client-side. ## Authentication Pass your API key in the `x-api-key` header. ## Body parameters - `type` (enum, required): Which vocabulary to suggest from. `location` = unified location strings for person_location / company_location, with structured parts and a level (region / country / state / city; regions like EMEA or APAC also carry `country_codes` - their member countries); `job_title` = catalog titles for person_job_title (typing an abbreviation like "ceo" suggests its canonical title); `industry` = accepted company_industry values, each with its category group; `company_keywords` = company specialties for the company_keywords filter on both People Search and Company Search, each row carrying a `company_count`, ordered by popularity when browsing and by relevance when searching; `person` = people matching the typed name, each carrying the id `person.id` accepts, their current job title, and their company with its logo; `company` = companies matching the typed name or domain prefix, each carrying the id `company.id` (People Search) accepts, a domain attached to the company (its website when none is attached), logo, industry and employee range - `value` is the canonical name `company.name` accepts; `technology` = web technologies and technology categories for the company_technologies / company_technology_categories filters (Company Search and People Search): categories first, then technologies, each by how many companies use it; `kind` says which filter `value` (the id) goes to. Allowed values: `location`, `job_title`, `industry`, `company_keywords`, `person`, `company`, `technology`. Example: `{"type":"location"}` - `query` (string, optional, max length: 100): The text typed so far, matched case-insensitively. Location, job_title, industry and company_keywords also ignore diacritics; `person` and `company` do not, so type "Nestlé", not "Nestle". Job-title and industry suggestions also survive a rephrasing: connector words and punctuation are ignored and the words may come in any order, so "VP of Marketing", "VP, Marketing" and "Marketing VP" all suggest "Vice President Marketing" - the same spellings person_job_title treats as that title. Location codes match exactly too: "gb" suggests United Kingdom, "tx" suggests Texas. Omit (or send empty) for browse mode, so a picker can open pre-filled: locations return top regions and the most popular places (the full region catalog lives at GET /v2/enums/regions), job titles the most-held titles, industries the alphabetical head of the list. Max 100 chars. Company-keyword suggestions match a prefix of any word, so "market" finds both "Marketing" and "Digital Marketing". `person` and `company` are the exceptions to browse mode: they need at least 2 characters and answer an empty list below that. Example: `{"type":"location","query":"aust"}` - `limit` (integer, optional, min: 1, max: 25, default: 10): Maximum suggestions to return. ## Example request ```bash curl --request POST \ --url https://api.getprospect.com/v2/search/suggest \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY' \ --data ' { "type": "location", "query": "aust", "limit": 5 } ' ``` ## Response 200 The suggestions, best first; `[]` when nothing matches (still a 200). ```json { "success": true, "data": [ { "value": "DACH", "level": "region", "city": null, "state": null, "state_code": null, "country": null, "country_code": null, "country_codes": [ "DE", "AT", "CH" ] }, { "value": "ANZ", "level": "region", "city": null, "state": null, "state_code": null, "country": null, "country_code": null, "country_codes": [ "AU", "NZ" ] }, { "value": "Australia", "level": "country", "city": null, "state": null, "state_code": null, "country": "Australia", "country_code": "AU" }, { "value": "Austria", "level": "country", "city": null, "state": null, "state_code": null, "country": "Austria", "country_code": "AT" }, { "value": "Western Australia, Australia", "level": "state", "city": null, "state": "Western Australia", "state_code": "WA", "country": "Australia", "country_code": "AU" } ], "metadata": { "timestamp": "2026-10-02T12:27:10.575Z", "type": "location", "query": "aust" } } ``` ## Response 400 Invalid request (`VALIDATION_ERROR`; `payload.code` says which kind of mistake). ```json { "success": false, "data": null, "metadata": { "timestamp": "2026-10-08T09:30:00.000Z" }, "errors": [ { "name": "VALIDATION_ERROR", "message": "type: \"city\" is not an accepted value. Accepted: location, job_title, industry, company_keywords, person, company, technology", "payload": { "field": "type", "code": "value_not_allowed", "received_value": "city", "received_type": "string", "invalid_values": [ "city" ], "allowed_values": [ "location", "job_title", "industry", "company_keywords", "person", "company", "technology" ], "constraints": { "isIn": "type must be one of the following values: location, job_title, industry, company_keywords, person, company, technology" } } } ] } ``` ## Response 401 Missing, unknown or inactive credentials (`UNAUTHORIZED`). ## Response 429 Over the per-second window of the `enrich` rate limit (`RATE_LIMIT`), which only person lookups by email address or LinkedIn URL count against; wait `Retry-After` seconds. Sent only where rate limits are enforced. ## Response 500 Unexpected server error.