Developers

HuntSales API

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.

Authentication

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"

Permissions & credit costs

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 + 7/phone
Credit balance	`credits:read`	free

A 402 is returned when your balance can't cover the call. Every response includes credits_remaining.

get/api/v1/credits

Returns your org's HuntSales credit balance.

Scope: credits:read · Cost: free

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

post/api/v1/people/search

Search 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 }

post/api/v1/people/collect

Reveal email and/or phone 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. You are only charged a reveal when the field actually comes back.

Scope: people:collect · Cost: 1 + 1/email + 7/phone

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, "reveal_phone": false }'

{ "results": [ { "people_id": "https://www.linkedin.com/in/...", "experience": [ { "work_email": "...", "contact_number": null } ] } ],
  "credits_remaining": 1238, "credits_charged": 2 }

MCP (connect your AI)

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 People Search database 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 People Search database into your CRM (spends 1 People Search credit per contact added, 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.