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>"
}Person Search
Contact Append
Queue an asynchronous ABM contact-append job that finds current employees at target companies matching desired job titles
POST
/
person-search
/
v0
/
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>"
}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 ajob_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?
202 with a job_id, job_type, status, and created_at. Poll Contact Job Status, then unlock via Contact Job Results.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}untilstatusiscompleted(orfailed) POST /person-search/v0/contact-jobs/{job_id}/resultsonce to unlock and bill- Page further results with
GET .../results(no additional billing)
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 |
Related
- Contact Prospect — NAICS-based prospecting
- Contact Job Status — poll job progress
- Contact Job Results — unlock and page results
- Person Search — natural-language audience search
Was this page helpful?