Skip to content

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.

2 min read · Updated November 18, 2026

You need an API key first. See Create an API key. Replace YOUR_API_KEY below with yours.

  1. See who can send

    Lists your connected LinkedIn accounts with live status. Needs a Member key or above.

  2. Create a campaign

    This makes a draft. Nothing is sent yet.

  3. Put leads in it

    Up to 5,000 rows per call. People already in HeyLeads are skipped, not duplicated.

  4. Launch it

    Needs an Admin key. It's refused while billing is paused.

The four calls
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.

Add leads to a list
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 fullName and linkedinUrl. Send Content-Type: application/json on requests with a body.
  • Lists come back as { "items": [...] }. Leads are cursor-paged: pass the nextCursor you 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.

Was this article helpful?