ZenMode REST API

Connect your AI assistant (MCP)

ZenMode also runs an MCP server, so any AI assistant that supports MCP (Claude, ChatGPT, Gemini, Cursor and others) can work with your account directly: check how your campaigns are doing, look people up, read a conversation, add people to a campaign or change who it targets. It can also write messages, build a campaign and start it once you say yes. ZenMode then sends them within your daily limits and business hours, while the desktop app is open. Same plans as the API.

Server address

https://www.zen-mode.io/api/mcp

In claude.ai (and the Claude desktop and mobile apps)

1. Open Customize → Connectors, click +, then Add custom connector.
2. Name it ZenMode, paste the server address above, and click Connect.
3. On the ZenMode page that opens, sign in if asked, choose Read only or Read and change, pick an API key, and click Allow.
4. In a chat, open the + menu, go to Connectors and switch ZenMode on.

In ChatGPT

1. In settings, turn on Developer mode (under Apps → Advanced settings).
2. Create a new app: name it ZenMode, paste the server address, choose OAuth and click Create.
3. On the ZenMode page that opens, sign in if asked, choose what ChatGPT may do, pick an API key, and click Allow.

Developer mode depends on your ChatGPT plan, and OpenAI may limit changes on some plans.

In the Gemini app

1. At gemini.google.com, open Settings → Connected Apps and, under Custom apps, choose Add a custom app.
2. Paste the server address, click Next, then click Allow on the ZenMode page that opens.

Google offers custom apps in the Gemini app for personal Google accounts in the US for now.

In Claude Code, with an API key from the dashboard:

claude mcp add --transport http zenmode https://www.zen-mode.io/api/mcp --header "Authorization: Bearer YOUR_ZENMODE_API_KEY"

In Cursor and other tools that read an mcpServers file, add ZenMode to the tool's MCP settings with an API key. (VS Code and Windsurf use a different file layout, so this block does not paste into them as it is.)

{
  "mcpServers": {
    "zenmode": {
      "url": "https://www.zen-mode.io/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ZENMODE_API_KEY"
      }
    }
  }
}

An assistant using an API key directly can only look things up unless that key was created with Let AI assistants make changes ticked. The full guide, with every tool an assistant can use, its limits and example prompts: Connect ZenMode to Claude.

Signals tools: Signals is included on every plan except Novice. On an account with Signals, an assistant can read what Signals watches, the credits left, and the people it found (by competitor, topic, date and score), and add them to a campaign exactly as the Signals tab does. Finding new people (1 credit each) and researching one (1 credit) take two calls: the first spends nothing and says the cost and the credits left; credits are spent only on the second call, with the confirm token, after you say yes.

Authentication

All API requests require a Bearer token. Generate an API key from your dashboard.

curl -H "Authorization: Bearer zm_your_api_key_here" \
  https://www.zen-mode.io/api/v1/tasks

Scoping: your API key is your identity — every response is scoped to the key's own account. Resource ids passed as parameters (e.g. campaign_id) can only reference your own resources; anything else returns 404.

Plan requirement: the API is on Practitioner and above, and so is the MCP server. A trial counts as the plan being trialled. On the Novice tier (or without an active plan) every endpoint returns:

HTTP 403
{
  "error": "API and MCP access is on Practitioner and above. Upgrade here: https://www.zen-mode.io/dashboard/billing",
  "code": "plan_upgrade_required",
  "hint": "Upgrade here: https://www.zen-mode.io/dashboard/billing"
}

The task, webhook, key and data endpoints all return this same 403 body. Your keys are never deleted: when the account moves to Practitioner or above they work again, with no other step.

Rate Limits

How execution actually works

Creating a lead writes a row. A desktop later reads that row, decides whether it may act, and sends. The two halves authenticate differently: your API key writes, and the desktop's own credential reads. You do not need any additional setup for the send — but you do need a desktop that is actually running.

What has to be true before a queued lead sends

• A desktop is running and its LinkedIn session is alive.
• The campaign is active — re-checked continuously, so pausing stops work mid-run.
• A campaign is running on that desktop for the campaign's LinkedIn account. Someone has to click Run: opening the app does not start a campaign. On desktop 1.3.204 and later, a running campaign's regular check also works through the other active campaigns on the same LinkedIn account, so your lead is picked up even if a different campaign on that account was the one started. On older versions only the started campaign is worked.
• The LinkedIn account is not disabled and not in a cooldown.
• The per-account daily send limit has not been reached.
• If the campaign uses warm-up, a brand-new lead is not eligible to be invited until warm-up has run for it. This is silent — the lead simply is not picked up yet.

Timing. If a desktop is already running a campaign on that LinkedIn account, it re-reads the queue on a cycle — expect up to about two hours before a freshly pushed lead is picked up. A campaign switched to active after the run started may not be picked up until the desktop reloads its campaign list (for example after Stop and Run). If nothing is running on that account, the lead waits until someone clicks Run: nothing on our side wakes a desktop up. Sends are then paced at roughly one action every 90–180 seconds.

Things that can quietly reduce what you pushed

• A target location can fail your leads. If the campaign has a target location, the desktop checks each lead's location before inviting and marks the ones that do not match as failed (failure_reason: location_mismatch). This applies to leads you push, and not only when you send a location: warm-up visits the profile and fills the location in. Leave the target location empty on an API-fed campaign if you want every pushed lead tried. A failed lead does not block a push, so pushing the same person to a different campaign creates a new lead that will fail the same way; pushing them to the same campaign again returns 409 already_exists without a lead object.
• A target job title does not filter leads you push (desktop 1.3.198 and later). On older versions a pushed lead whose title did not match was removed, and a removed lead cannot be pushed into that campaign again: re-pushing it there returns 409 already_exists with removed: true.
• A campaign with targeting set may add its own contacts. When the queue runs low and the campaign has targeting configured, the desktop can search LinkedIn and import more people, mixing them into your curated list. Leave targeting empty on an API-fed campaign if you want only the contacts you pushed.

Endpoints

{
  "action_type": "connect",
  "linkedin_account_id": "acc_abc123",
  "payload": {
    "profile_url": "https://linkedin.com/in/jane-doe",
    "message": "Hi Jane, I'd love to connect!"
  },
  "priority": 0,
  "max_retries": 3
}

{
  "task": {
    "id": "task_m1abc_x7k2p9qr",
    "action_type": "connect",
    "status": "pending",
    "linkedin_account_id": "acc_abc123",
    "payload": { ... },
    "priority": 0,
    "created_at": "2026-04-02T10:30:00.000Z"
  }
}

curl -H "Authorization: Bearer zm_..." \
  "https://www.zen-mode.io/api/v1/tasks?status=completed&limit=10"

curl -H "Authorization: Bearer zm_..." \
  https://www.zen-mode.io/api/v1/tasks/task_m1abc_x7k2p9qr

{
  "task": {
    "id": "task_m1abc_x7k2p9qr",
    "action_type": "connect",
    "status": "completed",
    "result": {
      "success": true,
      "note_sent": false,
      "note_dropped": true,
      "note_dropped_reason": "free_or_unconfirmed_plan"
    }
  }
}

curl -X PATCH -H "Authorization: Bearer zm_..." \
    -H "Content-Type: application/json" \
    -d '{"status":"completed","result":{"note":"sent"}}' \
    https://www.zen-mode.io/api/v1/tasks/task_m1abc_x7k2p9qr

curl -X DELETE -H "Authorization: Bearer zm_..." \
  https://www.zen-mode.io/api/v1/tasks/task_m1abc_x7k2p9qr

{
  "url": "https://your-server.com/zenmode-webhook",
  "events": ["task.completed", "task.failed", "lead.replied", "lead.accepted", "lead.sent"]
}

{
  "event": "task.completed",
  "data": {
    "task_id": "task_m1abc_x7k2p9qr",
    "action_type": "connect",
    "status": "completed",
    "result": { "success": true, "note_sent": true, "note_dropped": false },
    "linkedin_account_id": "acc_abc123"
  },
  "timestamp": "2026-04-02T10:35:00.000Z"
}

{
  "event": "lead.replied",
  "data": {
    "lead_id": 37110,
    "campaign_id": 42,
    "name": "Omar Molina",
    "linkedin_url": "https://www.linkedin.com/in/example",
    "replied_at": "2026-07-20T15:12:40.000Z",
    "reply_text": "Thanks for reaching out, but I'm not interested.",
    "reply_subject": "Quick question about outreach at Audere",
    "linkedin_account_id": 12,
    "linkedin_account_name": "Sales seat 1"
  },
  "timestamp": "2026-07-20T15:12:41.000Z"
}

{
  "event": "lead.accepted",
  "data": {
    "lead_id": 37110,
    "campaign_id": 42,
    "name": "Omar Molina",
    "linkedin_url": "https://www.linkedin.com/in/example",
    "accepted_at": "2026-07-18T09:02:11.000Z",
    "linkedin_account_id": 12,
    "linkedin_account_name": "Sales seat 1"
  },
  "timestamp": "2026-07-18T09:02:12.000Z"
}

const crypto = require('crypto');

// rawBody: the request body exactly as received (a Buffer or string), not re-serialised JSON.
function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  const a = Buffer.from(String(signature || ''), 'utf8');
  const b = Buffer.from(expected, 'utf8');
  // timingSafeEqual throws on different lengths, so check that first.
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: keep the raw body for this route.
// app.post('/zenmode-webhook', express.raw({ type: 'application/json' }), (req, res) => {
//   if (!verifyWebhook(req.body, req.get('X-ZenMode-Signature'), process.env.ZENMODE_WEBHOOK_SECRET)) {
//     return res.sendStatus(401);
//   }
//   const event = JSON.parse(req.body.toString('utf8'));
//   res.sendStatus(200);
// });

import hashlib, hmac

def verify_webhook(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")

Code Examples

# Create a connection request task
curl -X POST https://www.zen-mode.io/api/v1/tasks \
  -H "Authorization: Bearer zm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "connect",
    "linkedin_account_id": "acc_abc123",
    "payload": {
      "profile_url": "https://linkedin.com/in/jane-doe",
      "message": "Hi Jane, would love to connect!"
    }
  }'

# Check task status
curl https://www.zen-mode.io/api/v1/tasks/task_m1abc_x7k2p9qr \
  -H "Authorization: Bearer zm_your_api_key"

# List completed tasks
curl "https://www.zen-mode.io/api/v1/tasks?status=completed&limit=20" \
  -H "Authorization: Bearer zm_your_api_key"

import requests

API_KEY = "zm_your_api_key"
BASE_URL = "https://www.zen-mode.io/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Create a task
task = requests.post(f"{BASE_URL}/tasks", headers=headers, json={
    "action_type": "connect",
    "linkedin_account_id": "acc_abc123",
    "payload": {
        "profile_url": "https://linkedin.com/in/jane-doe",
        "message": "Hi Jane, would love to connect!"
    }
}).json()

print(f"Task created: {task['task']['id']}")

# Poll for completion
import time
while True:
    status = requests.get(
        f"{BASE_URL}/tasks/{task['task']['id']}", headers=headers
    ).json()
    if status["task"]["status"] in ("completed", "failed"):
        print(f"Task {status['task']['status']}: {status['task'].get('result')}")
        break
    time.sleep(10)

const API_KEY = "zm_your_api_key";
const BASE_URL = "https://www.zen-mode.io/api/v1";

async function createTask(actionType, profileUrl, message) {
  const res = await fetch(`${BASE_URL}/tasks`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      action_type: actionType,
      payload: { profile_url: profileUrl, message },
    }),
  });
  return res.json();
}

// Send a connection request
const { task } = await createTask(
  "connect",
  "https://linkedin.com/in/jane-doe",
  "Hi Jane, would love to connect!"
);
console.log("Task ID:", task.id);

// Register a webhook to get notified
await fetch(`${BASE_URL}/webhooks`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://your-server.com/webhook",
    events: ["task.completed", "task.failed"],
  }),
});

Read API — Analytics, Status & Leads

Read your own campaign data programmatically. Same Bearer-key authentication as the task endpoints; every response is scoped to the API key's account.

curl -H "Authorization: Bearer zm_your_api_key_here" \
  "https://www.zen-mode.io/api/v1/analytics?days=30"

{
  "window": { "days": 30 },
  "campaign_id": null,
  "summary": {
    "total_contacts": 412,
    "sent": 305,
    "accepted": 121,
    "replied": 38,
    "meetings_booked": 6,
    "acceptance_rate_pct": 40,
    "acceptance_rate_basis": { "campaign_type": "connect", "sent": 305, "accepted": 121 },
    "reply_rate_pct": 31,
    "reply_rate_denominator": "accepted"
  },
  "funnel": { "sent": 305, "accepted": 121, "replied": 38, "meetings_booked": 6 },
  "daily": [
    { "date": "2026-07-28", "connections_sent": 18, "connections_accepted": 7,
      "replies_received": 3, "meetings_booked": 0 }
  ],
  "campaigns": [
    { "id": 42, "name": "UK SaaS Founders", "status": "active",
      "total_contacts": 180, "sent_count": 140, "connected_count": 61,
      "replied_count": 19, "meeting_count": 3 }
  ]
}

curl -H "Authorization: Bearer zm_your_api_key_here" \
  "https://www.zen-mode.io/api/v1/analytics/outreach-volume?from=2026-09-16&to=2026-09-22"

{
  "from": "2026-09-16",
  "to": "2026-09-22",
  "time_zone": "UTC",
  "campaign_id": null,
  "totals": { "connection_requests": 112, "follow_up_1": 43, "follow_up_2": 24,
              "follow_up_3": 12, "follow_ups_total": 79, "reconstructed": 0 },
  "campaigns": [
    { "campaign_id": 42, "campaign_name": "UK SaaS Founders", "campaign_type": "connect",
      "connection_requests": 84, "follow_up_1": 31, "follow_up_2": 18, "follow_up_3": 9,
      "follow_ups_total": 58, "reconstructed": 0 }
  ],
  "recorded_from": "2026-09-23"
}

curl -H "Authorization: Bearer zm_your_api_key_here" \
  https://www.zen-mode.io/api/v1/status

{
  "desktop_active": true,
  "desktop_state": "active",
  "last_seen": "2026-07-29T14:58:12.000Z",
  "phase": "connecting",
  "linkedin_status": "normal",
  "active_campaign_count": 2,
  "connections_sent_today": 14,
  "accounts": [
    { "display_name": "Jane Doe", "is_running": true, "phase": "connecting",
      "campaign_id": 42, "daily_actions": 14, "daily_limit": 30,
      "weekly_actions": 61, "weekly_limit": 100, "linkedin_status": "normal",
      "started_at": "2026-07-29T13:02:44.000Z",
      "last_action_at": "2026-07-29T14:55:03.000Z" }
  ]
}

{ "desktop_active": false, "desktop_state": "went_quiet", "last_seen": "2026-07-29T12:40:02.000Z", "accounts": [] }
{ "desktop_active": false, "desktop_state": "never_seen", "last_seen": null, "accounts": [] }

curl -H "Authorization: Bearer zm_your_api_key_here" \
  "https://www.zen-mode.io/api/v1/leads?status=replied&limit=100"

{
  "leads": [
    { "id": 37110, "campaign_id": 42, "name": "Omar Molina",
      "title": "COO", "company": "Acme Ops", "location": "Mexico City, Mexico",
      "linkedin_url": "https://www.linkedin.com/in/example",
      "status": "replied", "follow_up_number": 1, "calendar_clicked": false,
      "connection_sent_at": "2026-07-16T19:02:11.000Z",
      "connection_accepted_at": "2026-07-17T17:58:25.000Z",
      "replied_at": "2026-07-20T15:12:40.000Z",
      "created_at": "2026-07-15T18:04:41.000Z",
      "updated_at": "2026-07-20T15:12:40.000Z" }
  ],
  "pagination": { "limit": 100, "offset": 0, "returned": 1 }
}

curl -H "Authorization: Bearer zm_your_api_key_here" \
  "https://www.zen-mode.io/api/v1/leads/37110/activity"

{
  "lead": { "id": 37110, "campaign_id": 42, "name": "Omar Molina",
            "linkedin_url": "https://www.linkedin.com/in/example", "status": "replied" },
  "activity": [
    { "id": 90114, "direction": "sent", "text": "Hi Omar — saw you lead ops at Acme...",
      "source": "automation", "read_by_you": null,
      "created_at": "2026-07-17T18:20:04.000Z" },
    { "id": 90562, "direction": "received", "text": "Thanks for reaching out — what does onboarding look like?",
      "source": "voyager-sync", "read_by_you": false,
      "created_at": "2026-07-20T15:12:40.000Z" }
  ],
  "pagination": { "limit": 100, "offset": 0, "returned": 2 }
}

curl -X PATCH -H "Authorization: Bearer zm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"status": "not_interested"}' \
  "https://www.zen-mode.io/api/v1/leads/37110"

{
  "changed": true,
  "lead": { "id": 37110, "campaign_id": 42, "name": "Omar Molina",
            "status": "not_interested", "replied_at": null,
            "updated_at": "2026-08-27T09:14:02.000Z" },
  "previous_status": "connected"
}

{
  "error": "This lead is already 'replied', which is further along than 'connected'. Refusing to demote it.",
  "code": "promote_only_guard",
  "changed": false,
  "requested_status": "connected",
  "lead": { "id": 37110, "status": "replied" }
}

curl -X PUT -H "Authorization: Bearer zm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"messages": {"connection_request": "Hi {{first_name}}, saw your post on onboarding at {{company}}.",
                    "follow_up_1": "Thanks for connecting. Worth a look? {{calendar_link}}"}}' \
  "https://www.zen-mode.io/api/v1/leads/37110/messages"

{
  "lead_id": 37110,
  "campaign_id": 42,
  "messages": {
    "connection_request": "Hi Omar, saw your post on onboarding at Acme.",
    "follow_up_1": "Thanks for connecting. Worth a look? https://www.zen-mode.io/api/calendar/redirect?c=37110"
  }
}

400  invalid_messages                 Not an object of the four keys with non-empty text (max 8000 characters each)
404  lead_not_found                   Not your lead, or it was removed from its campaign
409  unsupported_campaign_type        Only connect and nurture campaigns send these messages
409  message_already_sent             A step you sent has already gone out (or the lead is past it)
409  concurrent_update                The lead's messages changed during the request; read it again and retry
422  campaign_sends_no_connection_note  The campaign sends no connection request
422  follow_up_step_not_configured    The campaign has no such follow-up step, so it would never be sent
422  missing_variables                A variable the lead has no value for (missing_variables lists them)
422  connection_note_over_limit       The note is too long for this account (length, limit)
422  empty_message                    The message is empty once its variables are filled in

Create a lead — POST /api/v1/leads

Adds one contact to a campaign you own. It writes a single row and does nothing else — no invite is sent, no message is queued, no task is created, and the campaign is not started. Execution is the desktop app's job; see How execution actually works below.

POST /api/v1/leads
Authorization: Bearer zm_your_api_key
Content-Type: application/json

{
  "campaign_id": 42,            // required, positive integer
  "linkedin_url": "https://www.linkedin.com/in/some-person",  // required
  "name": "Some Person",        // optional
  "title": "Head of Ops",       // optional
  "company": "Acme",            // optional
  "location": "London, UK",     // optional
  "messages": {                 // optional: this lead's own text (see PUT /api/v1/leads/{id}/messages)
    "connection_request": "Hi {{first_name}}, ...",
    "follow_up_1": "..."
  }
}

The URL must contain either /in/<slug> or /sales/lead/<id> — those are the only two identities a lead can be keyed on. It is stored normalised: query strings and trailing slashes are stripped. The four optional fields are best-effort: a non-string value is stored as null rather than rejected, and there is no length limit.

201 returns the created lead in the same shape GET /api/v1/leads uses, an identity object carrying whichever of linkedin_slug / sales_lead_id was extracted, and a delivery object (below). A lead in a nurture campaign is created with status: "connected"; every other campaign type starts at "pending".

"delivery": {
  "state": "queued_running",
  "reasons": ["warmup_first"],
  "campaign": { "status": "active", "approval_state": "not_required", "linkedin_account_id": 12 },
  "desktop": {
    "state": "active", "last_seen_at": "2026-09-15T11:31:02.000Z", "age_seconds": 1740,
    "app_version": "1.3.210", "account_running": true, "running_campaign_id": 42,
    "works_all_active_campaigns_on_account": true
  },
  "checked_at": "2026-09-15T12:00:02.000Z"
}

{
  "error": "This person is already in one of your campaigns.",
  "code": "already_exists",
  "lead": { "id": 41200, "campaign_id": 17, "status": "sent", "removed": false },
  "scope": "all_campaigns"
}

409 suppressed is returned when the person is on your do-not-contact list. It carries code: "suppressed", the normalised linkedin_url and the identity. Remove the suppression first if it was intentional — see DELETE /api/v1/suppressions.

409 campaign_exclusion is returned when the campaign's own exclusion list (set in the dashboard) matches the person, the same list a CSV upload honours. matched_on is company or url. Company matching is deliberately loose: after dropping punctuation and suffixes such as Inc or Ltd, either name containing the other counts as a match.

409 csv_message_campaign is returned for a campaign whose messages come from columns of an uploaded CSV when the lead carries no messages. Those messages are filled from each contact's own CSV row, which a pushed lead does not have, so the API refuses rather than add a lead that would be sent a placeholder. Send the lead's own text in messages, or push into a campaign that uses message templates instead.

messages is checked exactly as PUT /api/v1/leads/{id}/messages checks it, before anything is written: a lead whose messages fail is not added (400 invalid_messages, a 409 or a 422 with the same codes). The text is stored with the lead, so no desktop ever sees it without its messages. POST /api/v1/leads/bulk takes the same field on each item.

Other responses

400  invalid_campaign_id  campaign_id is required and must be a positive integer
400                       linkedin_url is required
400  invalid_url          linkedin_url must be a linkedin.com profile URL
400  no_identity          URL has no /in/<slug> or /sales/lead/<id> path
400  inmail_requires_sn_url  The campaign is InMail and the URL is not a Sales Navigator lead URL
404                       Campaign not found (also returned for a campaign you do not own)
409  campaign_exclusion   The campaign's exclusion list matches this person (matched_on: company | url)
409  csv_message_campaign The campaign's messages come from CSV columns and the lead has no messages
4xx  (messages codes)     See PUT /api/v1/leads/{id}/messages
503  approval_check_failed  The campaign's approval state could not be confirmed; nothing was added
500                       Failed to create lead

URL validation runs before the ownership check, so a malformed URL aimed at a campaign you do not own returns 400, not 404.

Create leads in bulk — POST /api/v1/leads/bulk

Adds up to 500 contacts to one campaign you own in a single request, with a result for each. Every item is judged exactly as POST /api/v1/leads would judge it on its own (validation, do-not-contact, the campaign's exclusion list, duplicates), plus one outcome only a batch can have: duplicate_in_request, for a person who appears earlier in the same request. Like the single endpoint, it writes rows and sends nothing.

POST /api/v1/leads/bulk
Authorization: Bearer zm_your_api_key
Content-Type: application/json

{
  "campaign_id": 42,
  "items": [
    { "linkedin_url": "https://www.linkedin.com/in/first-person", "name": "First Person", "company": "Acme" },
    { "linkedin_url": "https://www.linkedin.com/in/second-person" }
  ]
}

The response is 200 whenever the request itself is valid, even if every item was refused. results has one entry per item, in the order you sent them:

{
  "campaign_id": 42,
  "summary": { "received": 2, "created": 1, "duplicate": 1, "duplicate_in_request": 0,
               "suppressed": 0, "excluded": 0, "refused": 0, "invalid": 0 },
  "results": [
    { "index": 0, "outcome": "created", "http_status": 201,
      "lead": { "id": 51001, "campaign_id": 42, "status": "pending", ... },
      "identity": { "linkedin_slug": "first-person", "sales_lead_id": null } },
    { "index": 1, "outcome": "duplicate", "http_status": 409, "code": "already_exists",
      "error": "This person is already in one of your campaigns.", "hint": "...",
      "lead": { "id": 41200, "campaign_id": 17, "status": "sent", "removed": false },
      "scope": "all_campaigns" }
  ],
  "delivery": { "state": "queued_running", ... }
}

• outcome is one of created, duplicate, duplicate_in_request (carries first_index), suppressed, excluded (code campaign_exclusion), refused (code csv_message_campaign) or invalid.
• http_status is the status the single endpoint would have returned for that item. The other fields match that endpoint's body for the same case.
• One delivery covers the whole request, because every item is in the same campaign.
• A duplicate with lead: null means the row appeared between our check and the write, or the same URL is already in this campaign as a failed lead.

Retries are safe. There is no idempotency key because none is needed: an item that already landed comes back as duplicate. The approval side effect described above runs once per request, and only when at least one item is about to be added.

Limits and errors

400  invalid_json               Body is not a JSON object
400  invalid_campaign_id        campaign_id is required and must be a positive integer
400  items_required             items is missing, not an array, or empty
400  too_many_items             More than 500 items; split the list
404  campaign_not_found         Campaign not found (also returned for a campaign you do not own)
429  rate_limit_exceeded        Over 100 requests/minute for this key (every v1 route)
429  item_rate_limit_exceeded   Over 2,000 items/minute for this key; nothing in the request was processed
503  approval_check_failed      Approval state could not be confirmed; nothing in the request was added
500  lead_create_failed         Our fault; some items may have been added, and retrying is safe

Both rate limits are counted in memory on each server instance, so treat them as the contract rather than as an exact ceiling. Sending volume is limited by the desktop's LinkedIn caps, not by how fast you push.

Suppressions — do-not-contact

Add a person to your do-not-contact list, and take them off it again. Suppression is keyed on the person (their /in/ slug and /sales/lead/ id), not on a single campaign row, so both URL forms of the same person are covered and every future import skips them.

curl -H "Authorization: Bearer zm_your_api_key_here" \
  "https://www.zen-mode.io/api/v1/suppressions?limit=100&offset=0"

{
  "suppressions": [
    {
      "id": 4821,
      "linkedin_url": "https://www.linkedin.com/in/example",
      "name": "Example Person",
      "reason": "api_suppression",
      "identity": { "linkedin_slug": "example", "sales_lead_id": null },
      "created_at": "2026-08-26T10:00:00.000Z"
    }
  ],
  "pagination": { "limit": 100, "offset": 0, "returned": 1 }
}

curl -X POST -H "Authorization: Bearer zm_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"linkedin_url": "https://www.linkedin.com/in/example"}' \
  https://www.zen-mode.io/api/v1/suppressions

{
  "suppressed": true,
  "already_suppressed": false,
  "linkedin_url": "https://www.linkedin.com/in/example",
  "identity": { "linkedin_slug": "example", "sales_lead_id": null },
  "leads_stopped": 1,
  "stopped_lead_ids": [37110]
}

curl -X DELETE -H "Authorization: Bearer zm_your_api_key_here" \
  "https://www.zen-mode.io/api/v1/suppressions?linkedin_url=https://www.linkedin.com/in/example"

{
  "unsuppressed": true,
  "linkedin_url": "https://www.linkedin.com/in/example",
  "identity": { "linkedin_slug": "example", "sales_lead_id": null },
  "exclusions_removed": 1,
  "leads_restored": 1,
  "restored_lead_ids": [37110]
}

Task Lifecycle

Error Codes