Search Suggestions

This endpoint allows you to retrieve canonical filter values to use in your search filters.

Use this endpoint to find valid values for filters in our Search Person and Search Company APIs whose values cannot be enumerated upfront — locations, job titles, technologies, industries, NAICS codes, and SIC codes.

This endpoint is FREE and does not consume any credits.

Rate limit

This endpoint has a special rate limit of 15 requests/second per account. This rate limit is the same across all plans (FREE, STARTER, GROWTH, PRO).

Endpoint

URL: https://api.prospeo.io/search-suggestions
Method: POST
Headers:
- X-KEY: your_api_key
- Content-Type: application/json

Parameters

You must provide exactly one of the following parameters. Providing more than one or none will result in an error.

Parameter	Example value	Description
`location_search` ^optional	`united states`	A search query to find location suggestions. Minimum 2 characters.
`job_title_search` ^optional	`software engineer`	A search query to find job title suggestions. Minimum 2 characters.
`technology_search` ^optional	`snow`	A search query to find technology suggestions. Minimum 2 characters.
`industry_search` ^optional	`software`	A search query to find company industry suggestions. Minimum 2 characters.
`naics_search` ^optional	`5132` or `software`	A search query to find NAICS code suggestions. Digit-only queries match against the code prefix; text queries match against the human-readable label. Minimum 2 characters.
`sic_search` ^optional	`7371` or `software`	A search query to find SIC code suggestions. Digit-only queries match against the code prefix; text queries match against the human-readable label. Minimum 2 characters.

Request examples

Location search


curl --location 'https://api.prospeo.io/search-suggestions' \
--header 'X-KEY: your_api_key' \
--header 'Content-Type: application/json' \
--data '{
    "location_search": "united states"
}'

Job title search


curl --location 'https://api.prospeo.io/search-suggestions' \
--header 'X-KEY: your_api_key' \
--header 'Content-Type: application/json' \
--data '{
    "job_title_search": "software engineer"
}'

Technology search


curl --location 'https://api.prospeo.io/search-suggestions' \
--header 'X-KEY: your_api_key' \
--header 'Content-Type: application/json' \
--data '{
    "technology_search": "snow"
}'

Industry search


curl --location 'https://api.prospeo.io/search-suggestions' \
--header 'X-KEY: your_api_key' \
--header 'Content-Type: application/json' \
--data '{
    "industry_search": "software"
}'

NAICS search


curl --location 'https://api.prospeo.io/search-suggestions' \
--header 'X-KEY: your_api_key' \
--header 'Content-Type: application/json' \
--data '{
    "naics_search": "5132"
}'

SIC search


curl --location 'https://api.prospeo.io/search-suggestions' \
--header 'X-KEY: your_api_key' \
--header 'Content-Type: application/json' \
--data '{
    "sic_search": "7371"
}'

Response: Location search

When searching for locations, the response contains an array of location suggestions with their type.


{
    "error": false,
    "location_suggestions": [
        {"name": "United States", "type": "COUNTRY"},
        {"name": "California, United States", "type": "STATE"},
        {"name": "Los Angeles, California, United States", "type": "CITY"},
        {"name": "Greater Los Angeles Area", "type": "ZONE"}
    ],
    "job_title_suggestions": null,
    "technology_suggestions": null,
    "industry_suggestions": null,
    "naics_suggestions": null,
    "sic_suggestions": null
}

Location types

Type	Description	Examples
`COUNTRY`	Countries	”United States”, “France”, “Germany”
`STATE`	States, provinces, or regions	”California”, “Ontario”, “Bavaria”
`CITY`	Cities	”New York”, “Paris”, “Tokyo”
`ZONE`	Metropolitan or greater areas	”Greater Toronto Area”, “San Francisco Bay Area”

Response: Job title search

When searching for job titles, the response contains an array of job title suggestions as plain strings.


{
    "error": false,
    "location_suggestions": null,
    "job_title_suggestions": [
        "software engineer",
        "senior software engineer",
        "software engineering manager",
        "software developer",
        "lead software engineer"
    ],
    "technology_suggestions": null,
    "industry_suggestions": null,
    "naics_suggestions": null,
    "sic_suggestions": null
}

Job title suggestions return up to 25 results, ordered by popularity (most common titles first).

Response: Technology search

When searching for technologies, the response contains an array of technology name strings.


{
    "error": false,
    "location_suggestions": null,
    "job_title_suggestions": null,
    "technology_suggestions": [
        "Social Snowball",
        "Snowplow Analytics"
    ],
    "industry_suggestions": null,
    "naics_suggestions": null,
    "sic_suggestions": null
}

Up to 10 results ordered by exact-prefix match first, then substring match.

Response: Industry search

When searching for industries, the response contains an array of industry name strings.


{
    "error": false,
    "location_suggestions": null,
    "job_title_suggestions": null,
    "technology_suggestions": null,
    "industry_suggestions": [
        "Software Development",
        "IT Services and IT Consulting"
    ],
    "naics_suggestions": null,
    "sic_suggestions": null
}

Up to 25 results ordered by exact-prefix match first, then substring match.

Response: NAICS / SIC search

When searching for NAICS or SIC codes, the response contains an array of {code, label} objects.


{
    "error": false,
    "location_suggestions": null,
    "job_title_suggestions": null,
    "technology_suggestions": null,
    "industry_suggestions": null,
    "naics_suggestions": [
        {"code": "5132", "label": "Software Publishers"},
        {"code": "51321", "label": "Software Publishers"},
        {"code": "513210", "label": "Software Publishers"}
    ],
    "sic_suggestions": null
}

Up to 25 results. Numeric queries match against the code prefix (e.g. "5132" returns every code starting with 5132). Text queries match against the human-readable label (substring, case-insensitive). SIC responses have the same shape under sic_suggestions.

Response details

The response always includes every suggestion field; the field matching your requested search type contains the results, all other fields are null.

Property	Type	Description
`error`	boolean	Indicates if an error has occurred. If `false`, the request was successful. If `true`, an `error_code` property is present.
`location_suggestions`	list \| null	Location suggestions when using `location_search`. Each item has `name` and `type`.
`job_title_suggestions`	list \| null	Job title strings when using `job_title_search`.
`technology_suggestions`	list \| null	Technology name strings when using `technology_search`.
`industry_suggestions`	list \| null	Industry name strings when using `industry_search`.
`naics_suggestions`	list \| null	NAICS code/label pairs when using `naics_search`. Each item has `code` and `label`.
`sic_suggestions`	list \| null	SIC code/label pairs when using `sic_search`. Each item has `code` and `label`.

Error codes

HTTP code	`error_code` property	Meaning
`400`	`INVALID_REQUEST`	Invalid request. You must provide exactly one of the supported search parameters (not more than one, not none), and the query must be at least 2 characters.
`401`	`INVALID_API_KEY`	Invalid API key, check your `X-KEY` header.
`429`	`RATE_LIMITED`	You hit the rate limit (15 requests/second).
`400`	`INTERNAL_ERROR`	An error occurred on our side, please contact the support.