Developers
A REST API (and an MCP server for AI agents) over the same APAC contact data and credit system as the app. Search people, collect their details, and check your balance from your own tools.
Create a key in HuntSales under Admin, then Developer (shown once, copy it then). Every member can create their own key; a key can do exactly what its owner's role allows in the app, and follows the role if it changes. Send it as a bearer token. Base URL: https://huntsales.io/api/v1.
curl https://huntsales.io/api/v1/credits \
-H "Authorization: Bearer hs_live_xxxxxxxxxxxx"A key inherits its owner's role: people search and collect need the Live Search permission on your role (a 403 tells you which permission is missing), while the credit balance is readable by every member's key. API calls draw down the same People Search credits as in-app Live search. Top-up packs run S$0.050 to S$0.040 per credit depending on pack size, and the credits included with Hunter and Apex work out cheaper still:
| Action | Scope | Credits |
|---|---|---|
| People search (per page) | people:search | 1 |
| Collect (per person) | people:collect | 1 + 1/email |
| Credit balance | credits:read | free |
A 402 is returned when your balance can't cover the call. Phone reveals are not available for new lookups yet, and nothing is charged for phone.
/api/v1/creditsReturns your org's HuntSales credit balance.
Scope: credits:read · Cost: free
{ "balance": 1240, "plan_remaining": 1000, "topup_balance": 240 }/api/v1/people/searchSearch business contacts. Returns preview rows; email/phone are revealed by collect. Each row's people_id is the person's LinkedIn profile URL. Recently fetched pages are served from cache at no cost, and an empty page is fully refunded.
Scope: people:search · Cost: 1 credit
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, "credits_remaining": 1239, "credits_charged": 1 }/api/v1/people/collectReveal the work email for selected people_ids (max 50). A people_id is the id returned by search, which is the person's LinkedIn profile URL; LinkedIn URLs you already hold work too. Collect runs in the background: the call returns 202 with a job id per person, which you poll until the email lands. You are only charged the email credit when an address actually comes back. Phone reveals are not available for new lookups yet, and nothing is charged for phone.
Scope: people:collect · Cost: 1 + 1/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/...", "job_id": "9f3c1a80-...", "status": "pending" } ],
"warnings": ["phone_reveals_unavailable"],
"credits_remaining": 1238 }Collect runs in the background and answers 202. Each person comes back with a job_id and a status of pending, or known when the email is already on file, or skipped when there is no matching profile. Poll the job below until its status is no longer pending.
/api/v1/people/collect?job_id=Poll one submitted collect. Returns the found email and its status once the lookup lands, or pending while it is still running. email_status is one of valid, invalid or unknown.
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": "valid", "credits_charged": 2 }HuntSales runs a hosted MCP server at https://huntsales.io/api/mcp, authenticated with your API key, so AI agents (Claude and others) can work with your CRM. For stdio clients like Claude Desktop, bridge to it with the mcp-remote helper:
{
"mcpServers": {
"huntsales": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://huntsales.io/api/mcp",
"--header", "Authorization: Bearer hs_live_xxxxxxxxxxxx"
]
}
}
}Clients that support remote HTTP MCP directly can skip the bridge and point at the same URL with an Authorization: Bearer header.
Every tool is scoped to your own organisation by your API key, and uses the same scopes and credit costs as the REST endpoints above. Read tools never change data. The write tools that spend quota or send mail (claim_prospects, launch_campaign) are dry-run by default: they return a preview, and only execute when you pass confirm: true.
Read
get_credits - your credit balance and plan remaining.query_contacts - search your CRM contacts by name, email, or job title, optionally filtered by pipeline stage.get_pipeline_summary - a count of your contacts in each pipeline stage.count_prospects - count fresh prospects in the HuntSales contact pool that match a profile (job title, country, industry) and are not yet in your CRM.get_campaign_engagement - a campaign's sent, delivered, opened, clicked and replied counts and rates, plus contact progress.Write
claim_prospects - add fresh prospects from the HuntSales contact pool into your CRM (spends 2 People Search credits per contact added, deliverability check included, capped at 500; dry-run by default).create_contact - create a CRM contact (stage defaults to Prospect).update_contact_stage - move a contact to a different pipeline stage, with an optional note.create_list - create an empty named contact list.create_campaign - create a draft email campaign with its sequence steps (never sent automatically).enroll_contacts - enrol contacts, by ids or a list, into a campaign as its audience.launch_campaign - start sending a draft campaign (irreversible; dry-run by default).Requests are rate limited per key. Outbound webhooks are available under Admin, then Developer (and via the n8n trigger node; see the n8n guide). Questions? Contact support from your dashboard.