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

> Queue an asynchronous ABM contact-append job that finds current employees at target companies matching desired job titles

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

  **How do I find contacts at specific companies by job title?** Use Contact Append to submit companies and job titles. Minerva queues an asynchronous job and returns a `job_id` you poll until completion, then unlock to retrieve billed results.

  **Common questions this endpoint answers:**

  * How do I find CTOs / VPs at a list of target accounts?
  * How do I run ABM contact append without blocking on a long search?
  * How do I safely retry a contact-append request?

  **What you need:** One or more company identifiers (name, domain, and/or LinkedIn URL) and one or more job titles.

  **What you get back:** HTTP `202` with a `job_id`, `job_type`, `status`, and `created_at`. Poll [Contact Job Status](/api-reference/person-search-contact-job), then unlock via [Contact Job Results](/api-reference/person-search-contact-job-results).
</div>

## Overview

Contact Append finds current employees at the companies you specify whose titles approximately match the titles you request.

The endpoint is **asynchronous**:

1. `POST /person-search/v0/contact-append` → `202` + `job_id`
2. Poll `GET /person-search/v0/contact-jobs/{job_id}` until `status` is `completed` (or `failed`)
3. `POST /person-search/v0/contact-jobs/{job_id}/results` once to unlock and bill
4. Page further results with `GET .../results` (no additional billing)

Billing happens on unlock, not on submit. See [Contact Job Results](/api-reference/person-search-contact-job-results#billing).

<RequestExample>
  ```bash Request Example theme={null}
  curl --request POST \
    --url 'https://api.minerva.io/person-search/v0/contact-append' \
    --header 'x-api-key: <api-key>' \
    --header 'Content-Type: application/json' \
    --header 'Idempotency-Key: append-acme-cto-2026-07-21' \
    --data '{
      "companies": [
        {"domain": "acme.com"},
        {"name": "Globex", "linkedin_url": "https://www.linkedin.com/company/globex"}
      ],
      "job_titles": ["Chief Technology Officer", "VP Engineering"],
      "size": 100
    }'
  ```
</RequestExample>

## Request

### Headers

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

<ParamField header="Idempotency-Key" type="string">
  Optional client-supplied key (max 200 characters). Reusing the same key with the same org and an identical request returns the existing job. Reusing it with a different request body returns `409 Conflict`.
</ParamField>

### Body

<ParamField body="companies" type="object[]" required>
  Target companies (1–25). Each company must include at least one of `name`, `domain`, or `linkedin_url`.
</ParamField>

<ParamField body="companies[].name" type="string">
  Company name (exact, case-insensitive). Max 200 characters.
</ParamField>

<ParamField body="companies[].domain" type="string">
  Website domain. Bare domains and full URLs are accepted (for example `acme.com` or `https://www.acme.com/about`).
</ParamField>

<ParamField body="companies[].linkedin_url" type="string">
  Company LinkedIn URL (`linkedin.com/company/...` or `/school/...`).
</ParamField>

<ParamField body="job_titles" type="string[]" required>
  Desired job titles (1–25). Candidate titles are matched approximately.
</ParamField>

<ParamField body="size" type="integer">
  Maximum contacts to return. Defaults to `100`. Range: `1`–`500`.
</ParamField>

## Response

### Success Response (`202 Accepted`)

<ResponseField name="job_id" type="string">
  UUID of the queued job. Use it with [Contact Job Status](/api-reference/person-search-contact-job) and [Contact Job Results](/api-reference/person-search-contact-job-results).
</ResponseField>

<ResponseField name="job_type" type="string">
  Always `contact_append` for this endpoint.
</ResponseField>

<ResponseField name="status" type="string">
  Initial status, typically `queued`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO-8601 timestamp when the job was created.
</ResponseField>

```json Response Example theme={null}
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_type": "contact_append",
  "status": "queued",
  "created_at": "2026-07-21T13:54:00.123456+00:00"
}
```

## Errors

| Status | When                                                                                   |
| ------ | -------------------------------------------------------------------------------------- |
| `400`  | Invalid body (missing companies/titles, out-of-range `size`, empty company identifier) |
| `409`  | `Idempotency-Key` reused with a different request body                                 |
| `503`  | Job could not be queued for processing                                                 |

## Related

* [Contact Prospect](/api-reference/person-search-contact-prospect) — NAICS-based prospecting
* [Contact Job Status](/api-reference/person-search-contact-job) — poll job progress
* [Contact Job Results](/api-reference/person-search-contact-job-results) — unlock and page results
* [Person Search](/api-reference/person-search) — natural-language audience search