Introduction
The People Search by prompt endpoint takes one sentence, such as VP Sales at software companies with 51 to 200 employees in Paris, reads it into People search filters, runs that search and returns the matching full profiles. You do not build the filters yourself: the response tells you which ones were applied, in data.interpretation.
Every result is a complete profile, the same shape People search returns, with the same cursor pagination. Results are drawn from our cache-based search index. This endpoint never triggers a live fetch.
Use it when the request comes from a person typing what they want, or when you prefer not to map criteria to filter names. To control every filter yourself, use People search.
Authorization
apikey
string
required
Authorization: Bearer YOUR_API_KEY header.Request body
prompt
string
required
cursor
string
metadata.nextCursor; request the next page with the same promptperPage
number
25)Prompt length: the 1000 token limit is about 4000 characters of English text. It is counted conservatively: four plain ASCII characters count as one token, and every other character (an accented letter, a non-Latin script) counts as one token on its own. A longer prompt returns HTTP
422witherror.codeINVALID_PROMPTand costs 0 credits.
No filters: the filters come from the prompt, so the request takes no search filter. Any other field, such as
locationorcurrentSeniority, returns HTTP422witherror.codePROMPT_FILTERS_NOT_SUPPORTEDand the offending fields inerror.details.fields, and costs 0 credits. A filter is refused rather than ignored, because an ignored filter would return results you did not ask for. Describe it in the prompt instead, or send explicit filters to People search.
What a prompt can express
A prompt is read into these People search filters:
| What you describe | Filters it becomes |
|---|---|
| A current or past job title, to include or exclude | currentPositionTitle, positionTitle and their exclude... counterparts |
| A current or past company, to include or exclude | currentCompanyName, companyName and their exclude... counterparts |
| An industry | currentCompanyIndustry, companyIndustry, excludeCompanyIndustry, from the industry list |
| A company size | currentCompanyEmployeeCountRange |
| A place | location (country, region, city or area) |
| A career length or an audience size | totalExperienceMonths, followersCount |
| A person’s name or headline keywords | firstName, lastName, headline |
| Open to work, currently employed, Premium, verified | isOpenToWork, isCurrentlyEmployed, isPremium, isVerified |
| How recent the data must be | maxDataAgeDate |
Job titles and company names are matched as written, with the same token-based matching as People search, so write a title the way it appears on profiles. A seniority word such as VP or Director is matched inside the job title: the position taxonomy filters (currentFunction, currentSubFunction, currentSeniority and experience) are not read from a prompt yet. To filter on them, use People search.
Anything the prompt asks for that no filter covers, such as skills, schools or spoken languages, is left out of the search and reported in data.interpretation.warnings, so you can see what the results do not take into account.
Pagination and credits
People search by prompt uses cursor pagination, like People search. Each response returns up to perPage profiles (1 to 100, default 25) and a metadata.nextCursor value. To get the following page, send the same prompt again with that value as cursor; nextCursor is null on the last page. The cursor is opaque: send it back unchanged, without parsing or altering it. There is no page parameter, and perPage may change from one page to the next.
The cursor does not expire, and a long pause between two pages is fine: the next page picks up where the previous one stopped. If profiles were refreshed in the meantime, one of them can occasionally repeat or be skipped at the page boundary. What a cursor needs is the same filters. A prompt keeps the filters it was first read into for 24 hours in your workspace, so resending it unchanged, from any of your API keys, always runs the same search. Spaces and line breaks do not count as a change. If you edit the prompt, or come back after 24 hours, the prompt is read again, and a cursor sent with filters other than the ones that produced it returns HTTP 400 and costs 0 credits: start again from the first page, without cursor.
perPage above 100 returns HTTP 422 with error.code PAGINATION_LIMIT_EXCEEDED, and a perPage that is not a whole number returns HTTP 422 with error.code INVALID_PAGINATION.
People search by prompt costs 1 credit per page for the search itself, plus 1 credit per profile delivered. The search credit is charged on every page, including when no profile matches. Compliance-blocked profiles are removed before the response and are not billed. A page that returns 25 profiles costs 26 credits, and a page that returns no profile costs 1 credit. A request refused before the search runs, for any of the reasons listed under Errors, costs 0 credits. Lower perPage to control how many credits a single request can spend.
Tip:
data.interpretation.filtersis a valid People search body. Send it to the free People search count endpoint to know how many people match in total, or to People search to adjust a filter by hand.
Errors
Every error below answers before the search runs, and costs 0 credits. When the prompt was read, error.details.interpretation carries the filters and warnings it produced, so you can see why it could not run.
| HTTP | error.code |
What happened | What to do |
|---|---|---|---|
422 |
INVALID_PROMPT |
prompt is missing, is not a string, is shorter than 3 characters or longer than 1000 tokens |
Send a prompt within the limits |
422 |
PROMPT_FILTERS_NOT_SUPPORTED |
The body carries a field other than prompt, cursor and perPage. error.details.fields lists them |
Describe those criteria in the prompt, or use People search |
422 |
NO_FILTERS_INTERPRETED |
No filter could be read from the prompt, and a search without filters would scan the whole database. error.details.interpretation.warnings says what was not understood |
Name a job title, a company, a place or an industry |
422 |
PROMPT_FILTERS_REJECTED |
The filters read from the prompt cannot run together, for example the same title both included and excluded. error.details.errors lists each problem with its field, as in Search filter validation |
Rephrase the prompt, or use People search |
422 |
INVALID_PAGINATION, PAGINATION_LIMIT_EXCEEDED |
perPage is not a whole number, or is above 100 |
Send a perPage from 1 to 100 |
400 |
REQUEST_ERROR |
The cursor does not belong to the filters the prompt was read into (Invalid or expired cursor) |
Start again from the first page, without cursor |
502 |
PROMPT_INTERPRETATION_FAILED |
The prompt could not be read this time | Retry, or rephrase the prompt |
504 |
PROMPT_INTERPRETATION_TIMEOUT |
Reading the prompt took too long | Retry with backoff |
503 |
PROMPT_SEARCH_UNAVAILABLE |
Search by prompt is temporarily unavailable | Retry later, or use People search with explicit filters |
Response structure
Note: This endpoint uses a nested envelope. The top-level V2
datafield wraps an inner search payload that contains the actual results array (data.data), the pagination info (data.metadata) and the filters read from the prompt (data.interpretation). See the example response for the exact shape.
success
boolean
true if the request was processed successfullyerror
null
null on success