Async 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"
  }'

{
  "segment_id": "<string>",
  "status": "<string>",
  "created_at": "<string>",
  "materialization_extent": "<string>"
}

POST

person-search

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 with 202 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 later unlock and 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 only after the explicit results unlock.

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/json

Request 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 unlock and 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

⌘I

Getting Started

Core Endpoints

Validation Workflows

Person Search

Usage

Storage

Segments

Quick Answer

Overview

Authentication requirement

Request

Headers

Request Body

Response

Success Response (`202 Accepted`)

Errors

​Quick Answer

​Overview

​Authentication requirement

​Request

​Headers

​Request Body

​Response

​Success Response (202 Accepted)

​Errors

​Related

Quick Answer

Overview

Authentication requirement

Request

Headers

Request Body

Response

Success Response (`202 Accepted`)

Errors

Related