HuntSales API

Returns your org's HuntSales credit balance.

Scope: credits:read · Cost: free

{ "balance": 1240, "plan_remaining": 1000, "topup_balance": 240 }

Search B2B professionals. Returns up to 50 preview rows per page with no email or phone; the work email is revealed by collect. Each row's people_id is the person's LinkedIn profile URL. A page costs up to 5 credits, charged at 0.1 per person returned. A page fetched in the last 7 days is served from cache at no cost, and an empty page is fully refunded. Page on has_more, which stays true for as long as there are more people to return. Pages come in order, so request page 1, then 2, and so on, and every page is charged: ask for the pages you need rather than walking a broad search to its end. Asking for a page you have not reached yet is refused and charged nothing. Paging stops at page 500, a guard against a runaway client rather than a limit on the search. total_results is an estimate kept for compatibility.

Scope: people:search · Cost: up to 5 credits per page

curl -X POST https://huntsales.io/api/v1/people/search \
  -H "Authorization: Bearer hs_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "job_title": ["founder","ceo"], "country_list": ["Singapore"], "page": 1 }'

{ "results": [ { "people_id": "https://www.linkedin.com/in/...", "full_name": "...", "experience": [...] } ],
  "total_results": 482, "has_more": true, "page": 1, "per_page": 50, "cached": false,
  "credits_remaining": 1235, "credits_charged": 5 }

Add selected people_ids (max 50) to your CRM. 2 credits per person added with an email. No email, no charge. A people_id is the LinkedIn profile URL returned by search; anyone already in your CRM is skipped free, as is an id we cannot match. An email our database already holds is delivered with the contact and charged in credits_charged; if it does not pass its deliverability check, those credits come back and, unless reveal_email is false, we look the person up once more, charged 2 only if a new email is found. Otherwise the included work email lookup runs in the background: the call returns 202 with a job id per lookup, which you poll until the address lands on the contact. Each lookup holds 2 credits (credits_held) and keeps them only if it finds an address; a lookup that finds nothing hands them all back. Any email that comes with a contact, now or when the lookup finds one later, gets a deliverability check at no extra cost, with the verdict on the contact shortly after. Phone numbers are not available, and nothing is charged for phone.

Scope: people:collect · Cost: 2 / contact added with an email

curl -X POST https://huntsales.io/api/v1/people/collect \
  -H "Authorization: Bearer hs_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "people_ids": ["https://www.linkedin.com/in/..."], "reveal_email": true }'

{ "status": "pending",
  "job_ids": ["9f3c1a80-..."],
  "results": [ { "people_id": "https://www.linkedin.com/in/...", "contact_id": "d41f...", "job_id": "9f3c1a80-...", "status": "pending" } ],
  "contacts_added": 1, "credits_charged": 0, "credits_held": 2,
  "warnings": ["phone_reveals_unavailable"],
  "credits_remaining": 1238 }

Poll one submitted email lookup. Returns the found address once it lands (it is written onto the contact, whose deliverability check then runs at no extra cost), or pending while it is still running. credits_charged is what the lookup settled to: 2 when it found an address, 0 when it found none. email_domain_mismatch is true when the address is at a domain that does not match the company it was looked up by: it is still delivered and charged as found, with a note on the contact saying so.

Scope: people:collect · Cost: free

curl "https://huntsales.io/api/v1/people/collect?job_id=9f3c1a80-..." \
  -H "Authorization: Bearer hs_live_xxx"

{ "job_id": "9f3c1a80-...", "status": "found",
  "email": "...", "email_status": "unknown",
  "email_domain_mismatch": false, "credits_charged": 2 }

Companies, deals, tasks, notes and the Suppression List

The same records the app shows, and the same tools MCP offers. Each call is gated exactly as its page in the app is for the key's owner, no more and no less, and every write is recorded in the activity log against the key. One rule is deliberately stricter than the app: the API never reads or changes anything on a contact you cannot open yourself, so a task's contact must be one you may work and notes need a contact you can open. Free: no credits.

Deleting a deal or a task, and adding to or removing from the Suppression List, answer with a preview (dry_run) and change nothing until you send confirm: true. A refusal is a 403 naming the permission to ask for, and a record you may not see is a 404, as if it did not exist. Each address the Suppression List returns counts toward your daily read limit; past it the answer is 429 with code: "daily_read_limit" and a Retry-After header.

curl -X POST https://huntsales.io/api/v1/deals \
  -H "Authorization: Bearer hs_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "deal_size": 12000, "status": "open", "contact_id": "d41f...", "close_date": "2026-11-30" }'

{ "deal": { "id": "7c2e...", "status": "open", "deal_size": 12000,
    "close_date": "2026-11-30", "contact_id": "d41f...", "logged_by_you": true } }

Webhook endpoints

Register a URL of your own and HuntSales POSTs to it when an event happens. Managing endpoints over the API lets a workflow register its own endpoint, as the n8n trigger node does. Needs a key with webhooks:manage. Free.

In the app only a superadmin manages webhooks, under Admin, then Developer, and the API follows the same rule. Only a Super Admin's key manages webhook endpoints, every endpoint in the workspace; any other key gets a 403. An endpoint a key creates is saved as its owner's.

curl -X POST https://huntsales.io/api/webhook-endpoints \
  -H "Authorization: Bearer hs_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/huntsales", "events": ["reply.received", "deal.won"] }'

{ "endpoint": { "id": "5b1e...", "url": "https://example.com/hooks/huntsales",
    "events": ["reply.received", "deal.won"], "active": true, "created_at": "..." },
  "secret": "whsec_..." }

Each delivery is a JSON body { "event", "created_at", "data" } with an X-HuntSales-Event header, an X-HuntSales-Delivery header with the delivery's id, and an X-HuntSales-Signature header of the form sha256= followed by the hex HMAC-SHA256 of the exact body under your secret. Every event is written down before it is sent. A delivery is tried up to 10 times in total: when your endpoint cannot be reached, takes longer than 8 seconds, or answers 429 or a 5xx error, it is retried with growing gaps, from a minute to 8 hours, about a day in all. A redirect is not followed and not retried: the delivery fails at once, and its log says so. Every try sends the same body, byte for byte, and the same delivery id, so skip one you already have. An endpoint whose deliveries keep failing for about a day (23 hours and at least 5 tries) is turned off and the Super Admins are emailed. Read back anything that must not be missed. Adding an endpoint emails the workspace's Super Admins, and adding or deleting one is in the activity log. An endpoint a key adds stops when that key is revoked: it is turned off and the Super Admins are emailed. A Super Admin can turn it back on in the app, after confirming that it then keeps sending as the workspace's own. It also stops sending, without being turned off, while the key's owner is no longer an active Super Admin (their role changed, or they are paused); those events are not kept, and it sends again once the owner is a Super Admin again or is resumed.

To send events into HuntSales (from Zapier, Make, n8n, a form or your own system), give an automation an Incoming webhook trigger and POST JSON to the URL it shows, https://huntsales.io/api/automation-hooks/{token}. It needs no API key: the token is the secret, so keep the URL private. Each automation takes up to 60 starts a minute. A body is at most 64 KB and must be JSON (a larger one gets 413, one that is not JSON 400), and {{ }} in it is removed before any step reads it. Once the workspace's monthly automation run allowance is used up, a call gets 429 and starts nothing.