curl --request POST \
--url 'https://api.minerva.io/person-search/v0/search-jobs' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"query": "Software engineers in Austin who previously worked at a public technology company"
}'
{
"segment_id": "<string>",
"status": "<string>",
"created_at": "<string>",
"materialization_extent": "<string>"
}Async Person Search
Async Person Search
Submit a natural-language person search for preview or full asynchronous materialization
POST
/
person-search
/
v0
/
search-jobs
curl --request POST \
--url 'https://api.minerva.io/person-search/v0/search-jobs' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"query": "Software engineers in Austin who previously worked at a public technology company"
}'
{
"segment_id": "<string>",
"status": "<string>",
"created_at": "<string>",
"materialization_extent": "<string>"
}Overview
Async Person Search builds a segment from a natural-language audience description. The submission returns immediately with202 Accepted, and
processing continues in the background. It defaults to a fast preview that
computes the match count, statistics, and a bounded internal preview. Set
materialization_extent to full to persist every matching PID for pagination.
This page documents step 1 of the flow in isolation. For the whole flow with
worked examples, see the
Async Person Search walkthrough.
Unlike synchronous Person Search, the submit
response does not contain PIDs. Preview jobs do not expose PIDs through the
public results endpoint. Full jobs return PIDs through GET results once processing completes.
Authentication requirement
The API key must belong to the organization creating the search and have access to Person Search.curl --request POST \
--url 'https://api.minerva.io/person-search/v0/search-jobs' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"query": "Software engineers in Austin who previously worked at a public technology company"
}'
Request
Headers
string
required
An API key authorized to use Person Search for the organization.
string
required
application/jsonRequest Body
string
required
Natural-language audience description. Must contain between
1 and 500
characters.string
default:"preview"
preview computes the match count and statistics without persisting every
matching PID. full materializes every PID so the results endpoint can
page them.Response
Success Response (202 Accepted)
string
UUID identifying both the async search job and its segment-backed search.
string
Initial job status. Normally
created.string
ISO-8601 submission timestamp.
string
Effective materialization mode applied to the job:
preview or full.202
{
"segment_id": "8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77",
"status": "created",
"created_at": "2026-07-21T20:00:00.000000Z",
"materialization_extent": "preview"
}
Errors
| Status | When |
|---|---|
401 | Missing or invalid credentials |
403 | The authenticated principal or billing tier cannot use this route |
422 | query or materialization_extent is invalid |
429 | Request-rate or plan quota exceeded |
503 | The segment materialization service is temporarily unavailable |
Related
Was this page helpful?