Contact Job Status

curl --request GET \
  --url 'https://api.minerva.io/person-search/v0/contact-jobs/550e8400-e29b-41d4-a716-446655440000' \
  --header 'x-api-key: <api-key>'

{
  "job_id": "<string>",
  "job_type": "<string>",
  "status": "<string>",
  "created_at": "<string>",
  "result_count": 123,
  "total_matched": 123,
  "results_unlocked": true,
  "error_code": "<string>",
  "message": "<string>",
  "started_at": "<string>",
  "completed_at": "<string>",
  "updated_at": "<string>"
}

GET

person-search

contact-jobs

{job_id}

curl --request GET \
  --url 'https://api.minerva.io/person-search/v0/contact-jobs/550e8400-e29b-41d4-a716-446655440000' \
  --header 'x-api-key: <api-key>'

{
  "job_id": "<string>",
  "job_type": "<string>",
  "status": "<string>",
  "created_at": "<string>",
  "result_count": 123,
  "total_matched": 123,
  "results_unlocked": true,
  "error_code": "<string>",
  "message": "<string>",
  "started_at": "<string>",
  "completed_at": "<string>",
  "updated_at": "<string>"
}

Overview

Returns the current state of a contact job owned by your organization. Use this after Contact Append or Contact Prospect. Recommended polling: every 2–5 seconds until status is terminal (completed or failed). Once completed, unlock results with Contact Job Results.

Status values

Status	Meaning
`queued`	Accepted; waiting for a worker
`running`	Worker is computing matches
`retrying`	Transient failure; will be retried
`completed`	Results are ready to unlock
`failed`	Terminal failure — see `error_code` / `message`

This endpoint does not bill. Billing occurs only on the first successful POST .../results unlock.

curl --request GET \
  --url 'https://api.minerva.io/person-search/v0/contact-jobs/550e8400-e29b-41d4-a716-446655440000' \
  --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 the contact job returned by Contact Append or Contact Prospect.

Response

Success Response (`200 OK`)

job_id

string

Job UUID.

job_type

string

contact_append or contact_prospect.

status

string

One of queued, running, retrying, completed, failed.

created_at

string

ISO-8601 creation timestamp.

result_count

integer

Number of stored result rows when the job completed. null while in progress.

total_matched

integer

Contacts matched in evaluated title batches before applying the size cap. null while in progress.

results_unlocked

boolean

true after a successful unlock via POST .../results.

error_code

string

Machine-readable failure code when status is failed.

message

string

Public error message when the job failed.

started_at

string

When the worker claimed the job, if started.

completed_at

string

When the job reached a terminal state, if finished.

updated_at

string

Last status update timestamp.

Response Example (completed)

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_type": "contact_append",
  "status": "completed",
  "created_at": "2026-07-21T13:54:00.123456+00:00",
  "result_count": 42,
  "total_matched": 58,
  "results_unlocked": false,
  "error_code": null,
  "message": null,
  "started_at": "2026-07-21T13:54:02.000000+00:00",
  "completed_at": "2026-07-21T13:54:45.000000+00:00",
  "updated_at": "2026-07-21T13:54:45.000000+00:00"
}

Errors

Status	When
`404`	Unknown `job_id`, or the job belongs to another organization

Contact Prospect Contact Job Results

⌘I

Getting Started

Core Endpoints

Validation Workflows

Person Search

Usage

Storage

Segments

Quick Answer

Overview

Status values

Request

Headers

Path Parameters

Response

Success Response (`200 OK`)

Errors

​Quick Answer

​Overview

​Status values

​Request

​Headers

​Path Parameters

​Response

​Success Response (200 OK)

​Errors

​Related

Quick Answer

Overview

Status values

Request

Headers

Path Parameters

Response

Success Response (`200 OK`)

Errors

Related