Contact Append

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
  }'

{
  "job_id": "<string>",
  "job_type": "<string>",
  "status": "<string>",
  "created_at": "<string>"
}

POST

person-search

contact-append

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
  }'

{
  "job_id": "<string>",
  "job_type": "<string>",
  "status": "<string>",
  "created_at": "<string>"
}

Overview

Contact Append finds current employees at the companies you specify whose titles approximately match the titles you request. The endpoint is asynchronous:

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

Billing happens on unlock, not on submit. See Contact Job Results.

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
  }'

Request

Headers

string

required

Your API key for authentication.

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.

Body

object[]

required

Target companies (1–25). Each company must include at least one of name, domain, or linkedin_url.

string

Company name (exact, case-insensitive). Max 200 characters.

string

Website domain. Bare domains and full URLs are accepted (for example acme.com or https://www.acme.com/about).

string

Company LinkedIn URL (linkedin.com/company/... or /school/...).

string[]

required

Desired job titles (1–25). Candidate titles are matched approximately.

integer

Maximum contacts to return. Defaults to 100. Range: 1–500.

Response

Success Response (`202 Accepted`)

string

UUID of the queued job. Use it with Contact Job Status and Contact Job Results.

string

Always contact_append for this endpoint.

string

Initial status, typically queued.

string

ISO-8601 timestamp when the job was created.

Response Example

{
  "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

Contact Prospect — NAICS-based prospecting
Contact Job Status — poll job progress
Contact Job Results — unlock and page results
Person Search — natural-language audience search

⌘I

Getting Started

Core Endpoints

Validation Workflows

Person Search

Usage

Storage

Segments

Quick Answer

Overview

Request

Headers

Body

Response

Success Response (`202 Accepted`)

Errors

​Quick Answer

​Overview

​Request

​Headers

​Body

​Response

​Success Response (202 Accepted)

​Errors

​Related

Quick Answer

Overview

Request

Headers

Body

Response

Success Response (`202 Accepted`)

Errors

Related