curl --request POST \
--url 'https://api.minerva.io/person-search/v0/contact-jobs/550e8400-e29b-41d4-a716-446655440000/results?limit=100&offset=0' \
--header 'x-api-key: <api-key>'
curl --request GET \
--url 'https://api.minerva.io/person-search/v0/contact-jobs/550e8400-e29b-41d4-a716-446655440000/results?limit=100&offset=100' \
--header 'x-api-key: <api-key>'
{
"job_id": "<string>",
"job_type": "<string>",
"results": [
{}
],
"results[].minerva_pid": "<string>",
"results[].matched_job_title": "<string>",
"results[].current_job_title": "<string>",
"results[].matched_company": {},
"results[].matched_naics_code": "<string>",
"results[].jacket": {},
"total": 123,
"returned": 123,
"limit": 123,
"offset": 123,
"billable_count": 123,
"unlocked_at": "<string>"
}Person Search
Contact Job Results
Retrieve matched contacts using record capacity once per unique record per contract term
POST
/
person-search
/
v0
/
contact-jobs
/
{job_id}
/
results
curl --request POST \
--url 'https://api.minerva.io/person-search/v0/contact-jobs/550e8400-e29b-41d4-a716-446655440000/results?limit=100&offset=0' \
--header 'x-api-key: <api-key>'
curl --request GET \
--url 'https://api.minerva.io/person-search/v0/contact-jobs/550e8400-e29b-41d4-a716-446655440000/results?limit=100&offset=100' \
--header 'x-api-key: <api-key>'
{
"job_id": "<string>",
"job_type": "<string>",
"results": [
{}
],
"results[].minerva_pid": "<string>",
"results[].matched_job_title": "<string>",
"results[].current_job_title": "<string>",
"results[].matched_company": {},
"results[].matched_naics_code": "<string>",
"results[].jacket": {},
"total": 123,
"returned": 123,
"limit": 123,
"offset": 123,
"billable_count": 123,
"unlocked_at": "<string>"
}Quick Answer
How do I get contacts from a finished contact job? When status iscompleted, call POST /person-search/v0/contact-jobs/{job_id}/results to unlock the result view, then use GET on the same path to page additional results. Each returned record counts once per contract term.Common questions this endpoint answers:- How do I download contact-append / contact-prospect results?
- When am I charged for contact jobs?
- How do I paginate unlocked results?
job_id from your organization.What you get back: A page of matched contacts (PID, titles, company/NAICS match fields, enrichment jacket), plus billable_count and unlocked_at.Overview
Contact job results are locked until you unlock them.| Method | Purpose | Bills? |
|---|---|---|
POST .../results | Unlock the result view and return the requested page | New records in this page use record capacity |
GET .../results | Page results after unlock | New records in this page use record capacity |
GET before unlocking, the API returns 409 Conflict telling you to POST first.
Billing
Records count once per organization per contract term across every delivery channel. Repeated reads within that term consume no additional capacity. A read in a new term counts the returned records again, even when the result view was unlocked earlier.- If the page exceeds available plan allowance and overage capacity, the request returns
402without records. Increase the monthly spend limit or upgrade before retrying. billable_countis the number of records newly counted by this response. It includes records funded by allowance, not only paid overage.- Unlimited Enterprise delivery does not consume record capacity.
curl --request POST \
--url 'https://api.minerva.io/person-search/v0/contact-jobs/550e8400-e29b-41d4-a716-446655440000/results?limit=100&offset=0' \
--header 'x-api-key: <api-key>'
curl --request GET \
--url 'https://api.minerva.io/person-search/v0/contact-jobs/550e8400-e29b-41d4-a716-446655440000/results?limit=100&offset=100' \
--header 'x-api-key: <api-key>'
Request
Headers
string
required
Your API key for authentication.
Path Parameters
string
required
UUID of a completed contact job owned by your organization.
Query Parameters
integer
Page size. Defaults to
100. Range: 1–100.integer
Number of results to skip. Defaults to
0.Response
Success Response (200 OK)
Same shape for POST (unlock) and GET (page).
string
Job UUID.
string
contact_append or contact_prospect.object[]
Page of matched contacts.
string
Minerva person ID (
p-…).string
The requested job title this contact matched.
string
Current job title on file, when available.
object
Input company that matched (contact-append only). May include
name, domain, and/or linkedin_url.string
Input NAICS code that matched (contact-prospect only).
object
Enrichment payload for the person (lowercased column names from the enrichment dataset).
integer
Total stored results for the job (
result_count).integer
Number of results in this page.
integer
Echo of the requested
limit.integer
Echo of the requested
offset.integer
Records newly counted in this response under the current contract term.
string
ISO-8601 timestamp of the successful unlock.
Response Example
{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"job_type": "contact_append",
"results": [
{
"minerva_pid": "p-abc123",
"matched_job_title": "Chief Technology Officer",
"current_job_title": "CTO",
"matched_company": {"domain": "acme.com"},
"matched_naics_code": null,
"jacket": {
"full_name": "Ada Lovelace",
"linkedin_url": "https://www.linkedin.com/in/ada"
}
}
],
"total": 42,
"returned": 1,
"limit": 100,
"offset": 0,
"billable_count": 1,
"unlocked_at": "2026-07-21T13:55:10.000000+00:00"
}
Errors
| Status | When |
|---|---|
404 | Unknown job_id, or job belongs to another organization |
409 | Job not completed yet; unlock already in progress; or GET before unlock |
402 | Insufficient plan allowance and overage capacity (insufficient_record_capacity) |
503 | Billing or delivery initialization failed transiently — safe to retry |
Related
Was this page helpful?