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

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

Overview

Async Person Search builds a complete, reusable segment from a natural-language audience description. The submission returns immediately with 202 Accepted; parsing and full result materialization continue in the background. The complete workflow is:

POST /person-search/v0/search-jobs to submit the query.
Poll Async Person Search Status until status is completed.
Inspect total_count and estimated_billable_count before unlocking.
POST .../{segment_id}/results once to unlock the entire segment and return the first requested PID page.
Use GET .../{segment_id}/results for subsequent pages without re-billing.

Unlike synchronous Person Search, the submit response does not contain PIDs. Async search fully materializes the segment first, then returns PIDs only after the explicit results unlock.

Authentication requirement

The API key must be associated with a Minerva user. Organization-only API keys without a user association cannot create or access async person-search jobs and receive 401 Unauthorized.

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

x-api-key

string

required

A user-associated API key.

Content-Type

string

required

application/json

Request Body

query

string

required

Natural-language audience description. Must contain between 1 and 500 characters.

Response

Success Response (`202 Accepted`)

segment_id

string

UUID identifying both the async search job and its materialized segment.

status

string

Initial job status. Normally created.

created_at

string

ISO-8601 submission timestamp.

202

{
  "segment_id": "8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77",
  "status": "created",
  "created_at": "2026-07-21T20:00:00.000000Z"
}

Errors

Status	When
`401`	Missing/invalid credentials, or the API key has no associated user
`403`	The authenticated principal or billing tier cannot use this route
`422`	`query` is missing, empty, longer than 500 characters, or the body is invalid
`429`	Request-rate or plan quota exceeded
`503`	The segment materialization service is temporarily unavailable

Get Person Search Async Person Search Status

⌘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