Async Person Search: End-to-End Flow

Overview

Synchronous Person Search returns up to 100 PIDs immediately and stops there. Async Person Search defaults to preview materialization, which returns count and statistics without persisting every matching PID. Set materialization_extent to full to build the complete, reusable segment used by the unlock and pagination flow below. The async flow lets you materialize the full audience and inspect its size before requesting record export.

	Synchronous Person Search	Async Person Search
Endpoint	`POST /person-search/v0/search`	`POST /person-search/v0/search-jobs`
Latency	Seconds, one call	Background job, poll for completion
Results	Up to 100 PIDs, one page only	Preview by default; full match set when `full` is requested
See size before paying	No	Yes — `total_count` at completion
Record capacity	PID-only results are free	PID-only results are free
Reusable	`search_id` re-fetch	Persistent segment
API key	Org or user key	Org or user key with Person Search access

Use async preview when you need background processing plus audience count and statistics. Request full materialization only when you need every PID.

Before you start

Use an authorized API key

The key must belong to the organization creating the search and have access to Person Search.

Plan for record export

PID-only results are free. Fetching records through Enrich v2 or an activation uses record capacity once per record per term.

Write the query as an audience description

Describe shared attributes (“Software engineers in Austin who previously worked at a public technology company”), not a specific named person. See Writing good queries for the attribute categories the parser handles well — they are identical for sync and async.

The flow at a glance

POST   /person-search/v0/search-jobs  (extent = full)       → segment_id, 202
GET    /person-search/v0/search-jobs/{segment_id}           → poll until status = completed
       (review total_count and stats)                     → decide whether to retrieve PIDs
POST   /person-search/v0/search-jobs/{segment_id}/results   → unlocks PID pagination, capacity-free page 1
GET    /person-search/v0/search-jobs/{segment_id}/results   → pages 2..n, free

All five steps return or prepare PID-only results without consuming record capacity. Enrichment and record exports are billed separately. Campaign activations to supported ad and direct mail platforms do not consume record allowance or incur record overage.

Step 1 — Submit the search

POST /person-search/v0/search-jobs accepts the query and returns immediately with 202 Accepted. Parsing and materialization continue in the background. The endpoint defaults to preview, so this full-results walkthrough opts into full materialization explicitly.

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",
    "materialization_extent": "full"
  }'

202

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

Store the segment_id. It is the identifier for the job, the segment, and every subsequent call in this flow. The submit response contains no PIDs — that is the key difference from synchronous search.

Full endpoint reference

Request body, headers, and the complete error table for the submit call.

Step 2 — Poll until the segment is built

GET /person-search/v0/search-jobs/{segment_id} reports progress. Poll every 2–5 seconds until the status is terminal. Polling never unlocks PIDs and never bills.

curl --request GET \
  --url 'https://api.minerva.io/person-search/v0/search-jobs/8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77' \
  --header 'x-api-key: <api-key>'

The job walks forward through these states:

Status	Meaning	Terminal?
`created`	Accepted and waiting to begin	No
`initiated`	Processing has started	No
`parsing_search`	The natural-language query is being parsed	No
`building_query`	Structured search filters are being compiled	No
`querying`	Matching PIDs are being materialized into the segment	No
`completed`	Full segment materialization is complete	Yes
`previewed`	Preview count and statistics are ready	Yes
`failed`	Terminal processing failure	Yes
`cancelled`	Processing was cancelled	Yes

Stop polling on every terminal state: previewed, completed, failed, and cancelled.

For failed and cancelled, inspect the response’s error object for its stable code and caller-safe message. error.retryable is always false because the job is terminal; submit a new or revised search to continue. When criteria caused the failure, error_criteria identifies them and suggested_search provides a rephrased query worth trying instead.

Full endpoint reference

Every status field, the criteria tree shape, and completed-job statistics.

Step 3 — Review audience size before unlocking

This is the step that makes the async flow worth using. Once status is completed, the status response tells you exactly the result size and availability:

Field	What it tells you
`total_count`	Exact number of PIDs in the segment
`estimated_billable_count`	`0` for available PID-only results
`billable_count`	`0` after unlock; `null` before unlock
`results_unlocked`	Whether this materialization has already been unlocked
`stats`	Contact coverage and demographic distributions for the segment

estimated_billable_count is 0 for available PID-only results. These results do not license records. Enrich v2 and record exports check your available record capacity and count each returned record once per organization per term. Use stats to qualify contact coverage and demographic distributions before requesting full data.

Step 4 — Unlock the PID results

POST /person-search/v0/search-jobs/{segment_id}/results unlocks the full materialization and returns your first PID page without consuming record capacity.

curl --request POST \
  --url 'https://api.minerva.io/person-search/v0/search-jobs/8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77/results?limit=100&offset=0' \
  --header 'x-api-key: <api-key>'

200

{
  "segment_id": "8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77",
  "pids": ["p-a1b2c3d4e5f6", "p-b2c3d4e5f6a7", "p-c3d4e5f6a7b8"],
  "total": 1284,
  "returned": 3,
  "limit": 100,
  "offset": 0,
  "billable_count": 0,
  "unlocked_at": "2026-07-21T20:02:10.000000Z"
}

billable_count is 0 because this response contains only PIDs. Unlock is idempotent. Repeating POST returns the requested PID page.

Step 5 — Page through the remaining PIDs

After unlock, use GET on the same path for every subsequent page. GET is side-effect-free and never bills.

curl --request GET \
  --url 'https://api.minerva.io/person-search/v0/search-jobs/8c2a6f71-3d41-4fc5-a2b6-1f53a5c81d77/results?limit=100&offset=100' \
  --header 'x-api-key: <api-key>'

Each response returns at most 100 PIDs. Start at offset=0 and advance by returned until offset + returned >= total. The 100-PID cap applies to the HTTP response only, not to the segment — total reports the full count and you can page all of it.

Full endpoint reference

POST vs GET semantics, pagination parameters, and the complete error table.

Complete working example

The whole flow, end to end, with an audience-size check before the unlock:

import time
import requests

BASE_URL = "https://api.minerva.io"
HEADERS = {"x-api-key": "<api-key>"}
MAX_RESULTS = 5000  # refuse to unlock a segment larger than this

# --- Step 1: submit ------------------------------------------------------
response = requests.post(
    f"{BASE_URL}/person-search/v0/search-jobs",
    headers=HEADERS,
    json={
        "query": "Software engineers in Austin who previously worked at a public technology company",
        "materialization_extent": "full",
    },
)
response.raise_for_status()
segment_id = response.json()["segment_id"]

# --- Step 2: poll until terminal -----------------------------------------
TERMINAL = {"previewed", "completed", "failed", "cancelled"}
while True:
    response = requests.get(
        f"{BASE_URL}/person-search/v0/search-jobs/{segment_id}",
        headers=HEADERS,
    )
    response.raise_for_status()
    job = response.json()
    if job["status"] in TERMINAL:
        break
    time.sleep(3)

if job["status"] != "completed":
    raise RuntimeError(f"Search {segment_id} ended as {job['status']}")

# --- Step 3: check audience size ----------------------------------------
print(f"{job['total_count']} PIDs")
if job["total_count"] > MAX_RESULTS:
    raise SystemExit("Segment too large — refine the query and resubmit")

# --- Step 4: unlock PID pagination --------------------------------------
response = requests.post(
    f"{BASE_URL}/person-search/v0/search-jobs/{segment_id}/results",
    headers=HEADERS,
    params={"limit": 100, "offset": 0},
)
response.raise_for_status()
page = response.json()
pids = list(page["pids"])
print(f"Retrieved {page['returned']} PIDs")

# --- Step 5: page the rest (free) ----------------------------------------
offset = page["returned"]
while offset < page["total"]:
    response = requests.get(
        f"{BASE_URL}/person-search/v0/search-jobs/{segment_id}/results",
        headers=HEADERS,
        params={"limit": 100, "offset": offset},
    )
    response.raise_for_status()
    page = response.json()
    pids.extend(page["pids"])
    offset += page["returned"]

print(f"Retrieved {len(pids)} PIDs")

Troubleshooting

Symptom	Cause	Fix
`409` on `POST .../results`	Job is preview-only, full materialization is unfinished, or unlock is already in progress	Submit with `materialization_extent: "full"`, poll until `completed`, then retry
`409` on `GET .../results`	You paged before unlocking	Call `POST .../results` once first
`404` on status or results	Unknown or deleted `segment_id`, or it belongs to another organization	Confirm the `segment_id` and that the key is for the owning org
`422` on submit	`query` is empty or over 500 characters	Shorten the query
Polling never stops after `previewed`	Polling loop only checks for `completed`	Treat `previewed`, `failed`, and `cancelled` as terminal too

What to do with the PIDs

Async person search returns Minerva PIDs only, with no person attributes attached. Take them somewhere next:

Enrich v2

Fetch full profile data — demographics, work history, contact channels — for the PIDs you unlocked.

Add Members to Segment

Persist the results into a segment you can track and activate.

Person Search Usage

Review daily delivery limits and consumption history.

Contact Append / Prospect

A separate async flow for ABM contacts at target companies.

Endpoint reference

1. Submit Search — POST /person-search/v0/search-jobs
2. Poll Status — GET /person-search/v0/search-jobs/{segment_id}
3. Unlock & Page Results — POST and GET /person-search/v0/search-jobs/{segment_id}/results

Getting Started

Core Endpoints

Validation Workflows

Person Search

Usage

Storage

Segments

Async Person Search: End-to-End Flow

Quick Answer

Overview

Before you start

The flow at a glance

Step 1 — Submit the search

Full endpoint reference

Step 2 — Poll until the segment is built

Full endpoint reference

Step 3 — Review audience size before unlocking

Step 4 — Unlock the PID results

Step 5 — Page through the remaining PIDs

Full endpoint reference

Complete working example

Troubleshooting

What to do with the PIDs

Enrich v2

Add Members to Segment

Person Search Usage

Contact Append / Prospect

Endpoint reference

​Quick Answer

​Overview

​Before you start

​The flow at a glance

​Step 1 — Submit the search

Full endpoint reference

​Step 2 — Poll until the segment is built

Full endpoint reference

​Step 3 — Review audience size before unlocking

​Step 4 — Unlock the PID results

​Step 5 — Page through the remaining PIDs

Full endpoint reference

​Complete working example

​Troubleshooting

​What to do with the PIDs

Enrich v2

Add Members to Segment

Person Search Usage

Contact Append / Prospect

​Endpoint reference

Quick Answer

Overview

Before you start

The flow at a glance

Step 1 — Submit the search

Step 2 — Poll until the segment is built

Step 3 — Review audience size before unlocking

Step 4 — Unlock the PID results

Step 5 — Page through the remaining PIDs

Complete working example

Troubleshooting

What to do with the PIDs

Endpoint reference