Skip to main content
Async Person Search finds an audience in the background. To retrieve every matching PID, submit with materialization_extent: "full", wait for completed, then page the results with GET. Search and PID retrieval do not consume record capacity. To fetch full profiles, send the PIDs to Enrich v2. Record capacity is consumed when records are delivered, with each unique record counted once per organization per billing term across delivery channels.
The 202 Accepted response contains a segment_id. Use it for polling and pagination. Queries can contain up to 500 characters.
The default mode is preview: it returns an audience count and statistics when ready, but does not provide the full PID result set. Set full when submitting a search that you want to page.

​
2. Wait for completion

Poll every 2–5 seconds until status is completed. The response includes total_count, the parsed criteria, and audience statistics. Stop polling on failed or cancelled; inspect error before submitting a revised search. Preview jobs can also finish with completed; materialization_extent identifies whether the job materialized a preview or the full audience. Treat previewed as a successful preview status as well. PID pagination requires completed with materialization_extent: "full". 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. search_timed_out means the processing budget was exhausted; search_worker_lost means a terminated worker was recovered from the failure queue. A nonterminal status alone does not predict completion. When criteria caused the failure, error_criteria identifies them and suggested_search provides a rephrased query worth trying instead.

​
3. Page the PIDs

Each page contains up to 100 PIDs:
Increase offset by returned for the next page. Stop when offset + returned >= total. The page-size limit does not cap the audience. Requests made before a full search completes return 409 Conflict.

​
4. Retrieve full records

Pass the PIDs you need to Enrich v2:
For example, paging 10,000 PIDs consumes no record capacity. Enriching 200 of those records consumes capacity for the records delivered that your organization has not already received in the current term. See the endpoint references for submission, status, and results.

​
Use preview counts before completion

For a third-party preview backed by one Elasticsearch query, polling can return total_count while status is computing_stats and stats is still null. Display the count as soon as it is non-null, then continue polling the same job for demographics and completion. The count is exact; 0 is a valid result. A later failure preserves the count and returns a terminal failure status. Processing statuses include counting, computing_stats, materializing, exporting, and finalizing. Stop only on completed, previewed, failed, or cancelled; not every job passes through every stage.