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

POST

person-search

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

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

If you call 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 the platform_records_under_management metric.

Insufficient credits → unlock fails; retry after adding credits
Successful unlock is idempotent: later POST/GET calls do not re-bill
billable_count in 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

x-api-key

string

required

Your API key for authentication.

Path Parameters

job_id

string

required

UUID of a completed contact job owned by your organization.

Query Parameters

limit

integer

Page size. Defaults to 100. Range: 1–100.

offset

integer

Number of results to skip. Defaults to 0.

Response

Success Response (`200 OK`)

Same shape for POST (unlock) and GET (page).

job_id

string

Job UUID.

job_type

string

contact_append or contact_prospect.

results

object[]

Page of matched contacts.

results[].minerva_pid

string

Minerva person ID (p-…).

results[].matched_job_title

string

The requested job title this contact matched.

results[].current_job_title

string

Current job title on file, when available.

results[].matched_company

object

Input company that matched (contact-append only). May include name, domain, and/or linkedin_url.

results[].matched_naics_code

string

Input NAICS code that matched (contact-prospect only).

results[].jacket

object

Enrichment payload for the person (lowercased column names from the enrichment dataset).

total

integer

Total stored results for the job (result_count).

returned

integer

Number of results in this page.

limit

integer

Echo of the requested limit.

offset

integer

Echo of the requested offset.

billable_count

integer

Net-new PIDs charged when the job was unlocked.

unlocked_at

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

Contact Job Status Endpoint Usage

⌘I

Getting Started

Core Endpoints

Validation Workflows

Person Search

Usage

Storage

Segments

Quick Answer

Overview

Billing

Request

Headers

Path Parameters

Query Parameters

Response

Success Response (`200 OK`)

Errors

​Quick Answer

​Overview

​Billing

​Request

​Headers

​Path Parameters

​Query Parameters

​Response

​Success Response (200 OK)

​Errors

​Related

Quick Answer

Overview

Billing

Request

Headers

Path Parameters

Query Parameters

Response

Success Response (`200 OK`)

Errors

Related