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
Unlock a completed contact job (billing once) and retrieve a page of matched contacts; GET pages afterward without re-billing
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 once to unlock and bill, then use GET on the same path to page additional results without re-billing.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 (once) and return the first requested page | Yes — on first successful unlock |
GET .../results | Page results after unlock | No |
GET before unlocking, the API returns 409 Conflict telling you to POST first.
Billing
Unlock bills net-new Minerva PIDs for your organization in the current billing year (previously unlocked PIDs are not re-charged). Usage is published as theplatform_records_under_management metric.
- Insufficient credits → unlock fails; retry after adding credits
- Successful unlock is idempotent: later
POST/GETcalls do not re-bill billable_countin the response is the number of PIDs charged for this job
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
Net-new PIDs charged when the job was unlocked.
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": 40,
"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 credits for the estimated billable PIDs (insufficient_credits) |
503 | Billing or delivery initialization failed transiently — safe to retry |
Related
Was this page helpful?