> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minerva.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Contact Job Status

> Poll the status of an asynchronous contact-append or contact-prospect job

<div style={{ display: 'none' }} aria-hidden="false">
  ## Quick Answer

  **How do I know when my contact job is done?** Poll this endpoint with the `job_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?

  **What you need:** The UUID `job_id` from a previous submit call.

  **What you get back:** Current job status, optional result counts, unlock flag, and error details when failed.
</div>

## Overview

Returns the current state of a contact job owned by your organization. Use this after [Contact Append](/api-reference/person-search-contact-append) or [Contact Prospect](/api-reference/person-search-contact-prospect).

Recommended polling: every 2–5 seconds until `status` is terminal (`completed` or `failed`). Once `completed`, unlock results with [Contact Job Results](/api-reference/person-search-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.

<RequestExample>
  ```bash Request Example theme={null}
  curl --request GET \
    --url 'https://api.minerva.io/person-search/v0/contact-jobs/550e8400-e29b-41d4-a716-446655440000' \
    --header 'x-api-key: <api-key>'
  ```
</RequestExample>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication.
</ParamField>

### Path Parameters

<ParamField path="job_id" type="string" required>
  UUID of the contact job returned by Contact Append or Contact Prospect.
</ParamField>

## Response

### Success Response (`200 OK`)

<ResponseField name="job_id" type="string">
  Job UUID.
</ResponseField>

<ResponseField name="job_type" type="string">
  `contact_append` or `contact_prospect`.
</ResponseField>

<ResponseField name="status" type="string">
  One of `queued`, `running`, `retrying`, `completed`, `failed`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO-8601 creation timestamp.
</ResponseField>

<ResponseField name="result_count" type="integer">
  Number of stored result rows when the job completed. `null` while in progress.
</ResponseField>

<ResponseField name="total_matched" type="integer">
  Contacts matched in evaluated title batches before applying the size cap. `null` while in progress.
</ResponseField>

<ResponseField name="results_unlocked" type="boolean">
  `true` after a successful unlock via `POST .../results`.
</ResponseField>

<ResponseField name="error_code" type="string">
  Machine-readable failure code when `status` is `failed`.
</ResponseField>

<ResponseField name="message" type="string">
  Public error message when the job failed.
</ResponseField>

<ResponseField name="started_at" type="string">
  When the worker claimed the job, if started.
</ResponseField>

<ResponseField name="completed_at" type="string">
  When the job reached a terminal state, if finished.
</ResponseField>

<ResponseField name="updated_at" type="string">
  Last status update timestamp.
</ResponseField>

```json Response Example (completed) theme={null}
{
  "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

* [Contact Append](/api-reference/person-search-contact-append)
* [Contact Prospect](/api-reference/person-search-contact-prospect)
* [Contact Job Results](/api-reference/person-search-contact-job-results)