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

string

required

Your API key for authentication.

Path Parameters

string

required

UUID of the contact job returned by Contact Append or Contact Prospect.

Response

Success Response (`200 OK`)

string

Job UUID.

string

contact_append or contact_prospect.

string

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

string

ISO-8601 creation timestamp.

integer

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

integer

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

boolean

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

string

Machine-readable failure code when status is failed.

string

Public error message when the job failed.

string

When the worker claimed the job, if started.

string

When the job reached a terminal state, if finished.

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

⌘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