Skip to main content
POST

​
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, 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:
  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.

​
Request

​
Headers

​
x-api-key
string
required
Your API key for authentication.
​
Idempotency-Key
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

​
companies
object[]
required
Target companies (1–25). Each company must include at least one of name, domain, or linkedin_url.
​
companies[].name
string
Company name (exact, case-insensitive). Max 200 characters.
​
companies[].domain
string
Website domain. Bare domains and full URLs are accepted (for example acme.com or https://www.acme.com/about).
​
companies[].linkedin_url
string
Company LinkedIn URL (linkedin.com/company/... or /school/...).
​
job_titles
string[]
required
Desired job titles (1–25). Candidate titles are matched approximately.
​
size
integer
Maximum contacts to return. Defaults to 100. Range: 1–500.

​
Response

​
Success Response (202 Accepted)

​
job_id
string
UUID of the queued job. Use it with Contact Job Status and Contact Job Results.
​
job_type
string
Always contact_append for this endpoint.
​
status
string
Initial status, typically queued.
​
created_at
string
ISO-8601 timestamp when the job was created.
Response Example

​
Errors