On this page
POST/campaigns/lookalike
Create a new Lookalike campaign, or add more Lookalike leads to an existing campaign (campaignId), from a LinkedIn profile URL or identifier. Reserves Lookalike allowance (not normal lead credits), enqueues the worker, then poll campaign/leads until ready. Website/domain seeds are not accepted.
Same-seed extend continues from the last cursor when job title keywords and countries also match; exhausted same-seed+filters returns lookalike_exhausted. Different seed or different titles/countries on the same campaign starts fresh.
Not available for isolated white-label workspaces (plan_required).
Credits: Lookalike allowance (not normal lead credits).
Rate class: 6 / minute per key (still subject to the global 120 / minute).
Request
POST /campaigns/lookalike
X-API-Key: sk_live_...
Content-Type: application/json
Idempotency-Key: optional-uuid
{
"seed": "https://www.linkedin.com/in/jane-doe/",
"jobTitleKeywords": ["Chief Revenue Officer", "CRO"],
"countries": ["us", "gb"],
"numberOfLeads": 50,
"leadDuplicateProtectionAcrossCampaigns": true
}
Extend (add more):
{
"seed": "https://www.linkedin.com/in/jane-doe/",
"jobTitleKeywords": ["Chief Revenue Officer", "CRO"],
"countries": ["us", "gb"],
"numberOfLeads": 50,
"campaignId": "lookalike_abc123"
}
| Field | Required | Notes |
|---|---|---|
seed | yes | LinkedIn profile URL or identifier (e.g. linkedin.com/in/…) |
jobTitleKeywords | no | Include titles (string or string[], max 15 × 80 chars). Partial match. Strongly recommended for role-accurate lookalikes. |
countries | no | Person countries (ISO 3166-1 alpha-2 string[], max 25). Omit for worldwide. |
numberOfLeads | no | Default 50, hard cap 10_000, clamped to available Lookalike |
campaignId | no | Existing campaign to extend |
leadDuplicateProtectionAcrossCampaigns | no | Default true |
Create mints campaignId server-side. Do not send a client-generated id for new campaigns.
Response 200
{
"campaignId": "lookalike_…",
"status": "PENDING",
"extended": false,
"extensionBatchId": null,
"requestedLeadTarget": 50,
"lookalikeReserved": 50,
"resume": null,
"message": "Lookalike campaign queued."
}
resume is fresh or continue on extend; null on create. Unused reserved Lookalike is refunded by the worker after insert.
202 may be returned if extend enqueue outcome is ambiguous — check campaign progress before retrying.
Request logs keep creditsCharged at 0 (normal lead-credit flag only). The reserved Lookalike amount is only in lookalikeReserved.
Errors
error.code | HTTP | When |
|---|---|---|
validation_error | 400 | Bad body / seed |
lookalike_exhausted | 400 | No more results for this profile + titles/locations on this campaign |
insufficient_lookalike_credits | 403 | Lookalike balance too low (details.available / required) |
plan_required | 403 | Ineligible plan, inactive plan without Lookalike top-up, or Lookalike blocked for workspace |
not_found | 404 | Extend campaignId missing |
conflict | 409 | Idempotency / extend in progress |
rate_limited | 429 | Per-key Lookalike RPM |
upstream_unavailable | 503 | Pipeline/queue failure or idempotency store down |
MCP
Tool: create_lookalike_campaign → same REST route. Optional idempotencyKey.
Related
- GET /credits —
lookalikeCredits/lookalikeTopUpCredits - Credits & rate limits