On this page

POST/campaigns/:campaignId/leads

Purpose

Add a LinkedIn profile to an existing campaign. 1 credit when status is created.

If the campaign is still FAILED (for example a zero-result scrape), a successful insert promotes it to READY_TO_SEND so POST .../start works without creating a new campaign. If the campaign is COMPLETED (or legacy DONE), a successful insert sets it to CAMPAIGN_PAUSED so you can resume outreach — same as adding more leads from the dashboard.


Request

POST /campaigns/search_abc/leads
X-API-Key: sk_live_...
Content-Type: application/json
Idempotency-Key: optional-uuid
{
  "linkedinUrl": "https://www.linkedin.com/in/jane-doe/",
  "fullName": "Jane Doe",
  "jobTitle": "VP Sales",
  "companyName": "Acme"
}
FieldRequiredMax
linkedinUrlYesPersonal /in/… URL
fullNameNo120
firstNameNo120
lastNameNo120
jobTitleNo200
companyNameNo200
emailNo254
locationNo200
headlineNo500
personalizationNo2000
customNo2000
custom1–custom10No2000 each

Unknown fields → 400 validation_error. No live profile fetch on this call.

For many URLs at once, use POST …/leads/batch (up to 100 per request).

{
  "leadId": "lead_xyz",
  "status": "created",
  "creditsCharged": 1
}
statusCredits
created1
duplicate0
excluded0

HTTP is always 200 for these outcomes — branch on status.

Error codeWhen
insufficient_creditsBalance < 1
validation_errorBad URL / fields
not_foundUnknown campaign
conflictIdempotency conflict

MCP

Tool: add_lead — optional idempotencyKey.