API quickstart: add leads and launch a campaign
Four calls to see who can send, create a draft campaign, put leads in it and start it. Plus the one idea to understand first: queued, not sent.
You need an API key first. See Create an API key. Replace YOUR_API_KEY below with yours.
See who can send
Lists your connected LinkedIn accounts with live status. Needs a Member key or above.
Create a campaign
This makes a draft. Nothing is sent yet.
Put leads in it
Up to 5,000 rows per call. People already in HeyLeads are skipped, not duplicated.
Launch it
Needs an Admin key. It's refused while billing is paused.
export KEY=YOUR_API_KEY
BASE=https://app.heyleads.so/api/v1
# 1. who can send?
curl -s $BASE/accounts -H "Authorization: Bearer $KEY"
# 2. create a campaign (a draft)
curl -s $BASE/campaigns -H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" -d '{"name":"Founders, Q4"}'
# 3. put leads in it (queued, never sent immediately)
curl -s $BASE/campaigns/CAMPAIGN_ID/leads -H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"rows":[{"fullName":"Ada Lovelace","linkedinUrl":"https://www.linkedin.com/in/ada-lovelace"}]}'
# 4. launch it
curl -s -X POST $BASE/campaigns/CAMPAIGN_ID/launch -H "Authorization: Bearer $KEY"#Add leads to a list instead
To collect leads without a campaign, add them to a list. This is what Zapier, Make and n8n do.
curl -s $BASE/lists/LIST_ID/leads -H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"rows":[{"fullName":"Ada Lovelace","linkedinUrl":"https://www.linkedin.com/in/ada-lovelace","company":"Analytical Engines","email":"ada@example.com"}]}'#Conventions
- JSON in and out, with camelCase field names such as
fullNameandlinkedinUrl. SendContent-Type: application/jsonon requests with a body. - Lists come back as
{ "items": [...] }. Leads are cursor-paged: pass thenextCursoryou get back as?cursor=. - The add-leads and webhook calls reject fields they don't know, so a typo is an error. Other calls ignore unknown fields, so check spelling.
- Every response has an
X-Request-Id. Quote it when you ask support for help. - Bodies can be up to 5 MB.
Every endpoint, with examples you can try, is in the developer reference. Anything you can do in the app can't necessarily be done through the API; see What the API can and can't do.