POST/campaigns/:campaignId/leads/batch

Credits: 1 per successfully inserted lead (summed in creditsCharged)
LinkedIn risk: Low (URL-only insert — no live LinkedIn enrich on add)
Rate limit: 10 / minute — default 10 / minute (the documented per-route limit)

Purpose

Insert up to 100 LinkedIn profiles into an existing campaign in one HTTP call. Same credit, dedupe, and exclude rules as POST …/leads.

For CRM / n8n bulk push: chunk lists larger than 100 (e.g. 185 → 100 + 85). Clients must call this route — parallel single-lead POSTs still hit per-key RPM.

Request

POST /campaigns/search_abc/leads/batch
X-API-Key: sk_live_...
Content-Type: application/json
Idempotency-Key: optional-uuid

{
  "leads": [
    {
      "linkedinUrl": "https://www.linkedin.com/in/jane-doe/",
      "fullName": "Jane Doe",
      "jobTitle": "VP Sales",
      "companyName": "Acme"
    }
  ]
}

• Top-level allowlist: only leads. Unknown keys → whole-request 400.
• Per-item unknown keys / bad types / over-length → whole-request 400.
• Invalid LinkedIn URL on one item → that index is validation_error in results; siblings still process.
• Body subject to global 128 KiB cap.

Response 200

Always 200 when the envelope is valid and the campaign exists:

{
  "results": [
    {
      "index": 0,
      "linkedinUrl": "https://www.linkedin.com/in/jane-doe/",
      "leadId": "lead_12",
      "status": "created",
      "creditsCharged": 1
    }
  ],
  "summary": {
    "total": 1,
    "created": 1,
    "duplicate": 0,
    "excluded": 0,
    "validation_error": 0,
    "insufficient_credits": 0,
    "failed": 0
  },
  "creditsCharged": 1
}

On first credit exhaustion, remaining items are marked insufficient_credits without further inserts.

Idempotency-Key is only stored when at least one item is created, duplicate, or excluded. All-insufficient / all-validation batches release the key so retries work after a top-up.

Related

• Single lead: post-add-lead

MCP

Tool: add_leads_batch — optional idempotencyKey.