> ## 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 Results

> Unlock a completed contact job (billing once) and retrieve a page of matched contacts; GET pages afterward without re-billing

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

  **How do I get contacts from a finished contact job?** When status is `completed`, call `POST /person-search/v0/contact-jobs/{job_id}/results` once to unlock and bill, then use `GET` on the same path to page additional results without re-billing.

  **Common questions this endpoint answers:**

  * How do I download contact-append / contact-prospect results?
  * When am I charged for contact jobs?
  * How do I paginate unlocked results?

  **What you need:** A completed `job_id` from your organization.

  **What you get back:** A page of matched contacts (PID, titles, company/NAICS match fields, enrichment jacket), plus `billable_count` and `unlocked_at`.
</div>

## 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

<RequestExample>
  ```bash Unlock (POST) theme={null}
  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>'
  ```

  ```bash Page (GET) theme={null}
  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>'
  ```
</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 a completed contact job owned by your organization.
</ParamField>

### Query Parameters

<ParamField query="limit" type="integer">
  Page size. Defaults to `100`. Range: `1`–`100`.
</ParamField>

<ParamField query="offset" type="integer">
  Number of results to skip. Defaults to `0`.
</ParamField>

## Response

### Success Response (`200 OK`)

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

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

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

<ResponseField name="results" type="object[]">
  Page of matched contacts.
</ResponseField>

<ResponseField name="results[].minerva_pid" type="string">
  Minerva person ID (`p-…`).
</ResponseField>

<ResponseField name="results[].matched_job_title" type="string">
  The requested job title this contact matched.
</ResponseField>

<ResponseField name="results[].current_job_title" type="string">
  Current job title on file, when available.
</ResponseField>

<ResponseField name="results[].matched_company" type="object">
  Input company that matched (contact-append only). May include `name`, `domain`, and/or `linkedin_url`.
</ResponseField>

<ResponseField name="results[].matched_naics_code" type="string">
  Input NAICS code that matched (contact-prospect only).
</ResponseField>

<ResponseField name="results[].jacket" type="object">
  Enrichment payload for the person (lowercased column names from the enrichment dataset).
</ResponseField>

<ResponseField name="total" type="integer">
  Total stored results for the job (`result_count`).
</ResponseField>

<ResponseField name="returned" type="integer">
  Number of results in this page.
</ResponseField>

<ResponseField name="limit" type="integer">
  Echo of the requested `limit`.
</ResponseField>

<ResponseField name="offset" type="integer">
  Echo of the requested `offset`.
</ResponseField>

<ResponseField name="billable_count" type="integer">
  Net-new PIDs charged when the job was unlocked.
</ResponseField>

<ResponseField name="unlocked_at" type="string">
  ISO-8601 timestamp of the successful unlock.
</ResponseField>

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

## Related

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