Skip to main content
Build a contact-ready list: discover companies, find decision-makers at each account, enrich emails, push to your CRM or sequencer.

​
When to use it

  • Outbound campaigns from an ICP definition
  • Nightly jobs that refresh prospect lists
  • Internal tools that replace manual list building

​
Endpoint sequence

StepEndpointCost
Preview companiesPOST /company-search-countFree
CompaniesPOST /company-searchPer company returned
Preview peoplePOST /person-search-countFree
PeoplePOST /person-searchPer person returned
EmailPOST /person-emailWhen email found — see GET /pricing

​
Step 1 — Build the company list

Follow ICP list build through pagination. Each company row should include a domain you can pass to person search. Prefer domains from search results over company names.

​
Step 2 — Find people per company

Scope to one employer with currentCompanyWebsite: 
curl --request POST \
  --url "${HUNTR_BASE_URL}/person-search" \
  --header 'content-type: application/json' \
  --header "x-api-key: ${HUNTR_API_KEY}" \
  --data '{
    "query": {
      "currentJobTitle": {
        "include": ["VP Engineering", "Head of Engineering", "Director of Engineering"]
      },
      "currentCompanyWebsite": { "include": ["linear.app"] },
      "location": { "include": ["US"] }
    },
    "pagination": { "size": 50 }
  }'

​
Title matching

currentJobTitle uses contains match. List variants explicitly: 
{ "include": ["CTO", "Chief Technology Officer", "Chief Technical Officer"] }

​
Never use linkedin.com as employer

currentCompanyWebsite: ["linkedin.com"] matches broadly — always use the target company’s domain.

​
Step 3 — Enrich emails

For each selected person: 
curl --request POST \
  --url "${HUNTR_BASE_URL}/person-email" \
  --header 'content-type: application/json' \
  --header "x-api-key: ${HUNTR_API_KEY}" \
  --data '{
    "first_name": "Dylan",
    "last_name": "Field",
    "company_domain": "figma.com"
  }'
Prefer company_domain over company name. You are charged when an email is found.

​
Engineering notes

​
Cost control

  1. company-search-count and person-search-count before paid calls
  2. Cap companies per run (e.g. top 500 by fit score)
  3. Limit people per company (e.g. 3–5 by title priority)
  4. Call person-email only for rows passing your scoring rules

​
Concurrency

Stay under 5 req/s. For production, use a queue with:
  • Max concurrency 3–4
  • 200–500ms between Huntr calls
  • Exponential backoff on 429

​
Do not loop /research

“Find 200 CTOs and their emails” must use this pipeline. /research returns 422 BULK_ENRICHMENT_REQUIRED — not charged. See Errors.

​
Buyer brief vs email only

NeedUse
Email for sequencingperson-email
Role, angles, risks on one buyer/research tier deep

​
Output shape (typical)

{
  "company_domain": "linear.app",
  "company_name": "Linear",
  "first_name": "Karri",
  "last_name": "Saarinen",
  "title": "CEO",
  "email": "karri@linear.app",
  "linkedin_url": "https://www.linkedin.com/in/karrisaarinen"
}
Map fields to your CRM or warehouse schema.

​
Next step