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"
}
| Field | Required | Max |
|---|---|---|
linkedinUrl | Yes | Personal /in/… URL |
fullName | No | 120 |
firstName | No | 120 |
lastName | No | 120 |
jobTitle | No | 200 |
companyName | No | 200 |
email | No | 254 |
location | No | 200 |
headline | No | 500 |
personalization | No | 2000 |
custom | No | 2000 |
custom1–custom10 | No | 2000 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
}
status | Credits |
|---|---|
created | 1 |
duplicate | 0 |
excluded | 0 |
HTTP is always 200 for these outcomes — branch on status.
| Error code | When |
|---|---|
insufficient_credits | Balance < 1 |
validation_error | Bad URL / fields |
not_found | Unknown campaign |
conflict | Idempotency conflict |
MCP
Tool: add_lead — optional idempotencyKey.