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>"
}Person Search
Contact Job Status
Poll the status of an asynchronous contact-append or contact-prospect job
GET
/
person-search
/
v0
/
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>"
}Quick Answer
How do I know when my contact job is done? Poll this endpoint with thejob_id from Contact Append or Contact Prospect until status is completed or failed.Common questions this endpoint answers:- Is my contact-append / contact-prospect job still running?
- How many contacts matched before the size cap?
- Have results already been unlocked for billing?
job_id from a previous submit call.What you get back: Current job status, optional result counts, unlock flag, and error details when failed.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 untilstatus 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 |
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 |
Related
Was this page helpful?