Developer documentation

Everything your LinkedIn agent does in the dashboard, it can do over an API. Search for people, add them to campaigns, read and send messages, and get told the moment something happens — plus a hosted MCP server so an AI assistant can drive all of it directly.

What you can build

• Push leads into a campaign from wherever they already live — your CRM, your own enrichment tooling, or a spreadsheet.
• Mirror replies into Slack, a helpdesk or your own database as they arrive.
• Let an AI assistant search LinkedIn and draft outreach without any glue code.
• Trigger downstream automation — a video, an invoice, a task — when a lead is tagged.

Quickstart

Three steps: create a key, confirm it works, then add a lead.

1 · Create a key

Open app.connectzly.com/api-mcp and create a key. Give it a name you'll recognise later — the tool it belongs to is usually the most useful label.

2 · Confirm the key works

Checking your credit balance is the cheapest possible test. It costs nothing and returns instantly.

export CONNECTZLY_API_KEY="sk_live_..."

curl -s https://api.connectzly.com/public/v1/credits \
  -H "X-API-Key: $CONNECTZLY_API_KEY"

{
  "credits": 842,
  "topUpCredits": 200,
  "planId": "pro"
}

3 · Add a lead

You'll need a campaign ID. Fetch one with GET /campaigns, or copy it from the campaign's page in the dashboard.

curl -s https://api.connectzly.com/public/v1/campaigns/CAMPAIGN_ID/leads \
  -H "X-API-Key: $CONNECTZLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedinUrl": "https://www.linkedin.com/in/jane-doe/",
    "fullName": "Jane Doe",
    "jobTitle": "VP Sales",
    "companyName": "Acme"
  }'

A lead that is genuinely new returns "status": "created" and costs one credit. Duplicates and excluded profiles are free — see Credits.

Authentication

Every request carries your key in a header. There is no OAuth flow and no bearer token.

X-API-Key: sk_live_xxxxxxxx
Content-Type: application/json

Key format and limits

Managing keys

The same dashboard page lists every key with the date it was last used, which makes it easy to spot ones nothing is calling any more. Deleting a key revokes it immediately — rotate by creating the replacement first, switching your integration over, then deleting the old one.

A missing or invalid key returns 401 unauthorized.

Credits and rate limits

What costs credits

Almost nothing does. Only creating a new lead consumes a credit — everything else is free to call.

Running out returns 403 insufficient_credits.

Request limits

All /public/v1/* routes share a ceiling of 120 requests per minute. Some routes are tighter, because they touch LinkedIn rather than only our own systems.

Backing off correctly

A rate-limited response tells you exactly how long to wait, in two places — the standard Retry-After header and error.details.retryAfterSeconds in the body. Honour whichever your HTTP client makes easier to read.

Errors

Every failure returns the same shape, so you can parse errors once and reuse that code everywhere.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to add this lead.",
    "details": {}
  }
}

Status codes

Error codes

Endpoints

Base URL https://api.connectzly.com/public/v1. Every request needs the X-API-Key header.

GET /credits
X-API-Key: sk_live_...

{
  "credits": 642,
  "topupCredits": 200,
  "planId": "pro"
}

GET /accounts
X-API-Key: sk_live_...

{
  "accounts": [
    {
      "id": "acc_abc",
      "name": "Jane Doe",
      "status": "connected",
      "active": true,
      "hasSalesNavigator": false,
      "today": {
        "connectionRequestsSent": 12,
        "connectionRequestsAccepted": 5,
        "connectionRequestsLimit": 20,
        "messagesSent": 8,
        "messageLimit": 30
      }
    }
  ]
}

GET /campaigns?limit=50&cursor=
X-API-Key: sk_live_...

{
  "campaigns": [
    {
      "id": "search_abc",
      "name": "Q3 outbound",
      "status": "CAMPAIGN_IN_PROGRESS",
      "totalLeads": 120,
      "assignedTemplateId": "tpl_...",
      "stats": {
        "connectionRequestsSent": 80,
        "connectionRequestsAccepted": 20,
        "acceptanceRate": 25.0,
        "messagesSent": 40,
        "repliesReceived": 8,
        "replyRate": 10.0
      }
    }
  ],
  "cursor": null
}

GET /campaigns/search_abc
X-API-Key: sk_live_...

{
  "id": "search_abc",
  "name": "Q3 outbound",
  "status": "CAMPAIGN_IN_PROGRESS",
  "totalLeads": 120,
  "assignedTemplateId": "tpl_...",
  "stats": {
    "connectionRequestsSent": 80,
    "connectionRequestsAccepted": 20,
    "acceptanceRate": 25.0,
    "messagesSent": 40,
    "repliesReceived": 8,
    "replyRate": 10.0
  }
}

POST /campaigns/search_abc/start
X-API-Key: sk_live_...
Content-Type: application/json

{}

{
  "campaignId": "search_abc",
  "action": "started",
  "status": "CAMPAIGN_IN_PROGRESS",
  "campaign": {
    "id": "search_abc",
    "name": "Q3 outbound",
    "status": "CAMPAIGN_IN_PROGRESS",
    "totalLeads": 120,
    "assignedTemplateId": "tpl_...",
    "stats": {
      "connectionRequestsSent": 80,
      "connectionRequestsAccepted": 20,
      "acceptanceRate": 25.0,
      "messagesSent": 40,
      "repliesReceived": 8,
      "replyRate": 10.0
    }
  }
}

POST /campaigns/search_abc/pause
X-API-Key: sk_live_...
Content-Type: application/json

{}

{
  "campaignId": "search_abc",
  "action": "paused",
  "status": "CAMPAIGN_PAUSED",
  "campaign": {
    "id": "search_abc",
    "name": "Q3 outbound",
    "status": "CAMPAIGN_PAUSED",
    "totalLeads": 120,
    "assignedTemplateId": "tpl_...",
    "stats": {
      "connectionRequestsSent": 80,
      "connectionRequestsAccepted": 20,
      "acceptanceRate": 25.0,
      "messagesSent": 40,
      "repliesReceived": 8,
      "replyRate": 10.0
    }
  }
}

GET /campaigns/search_abc/leads?limit=50
X-API-Key: sk_live_...

{
  "leads": [
    {
      "id": "lead_xyz",
      "fullName": "Jane Doe",
      "firstName": "Jane",
      "lastName": "Doe",
      "linkedinUrl": "https://www.linkedin.com/in/jane-doe/",
      "jobTitle": "VP Sales",
      "location": "Austin, TX",
      "companyName": "Acme",
      "companyLinkedin": null,
      "website": null,
      "email": null,
      "tag": null,
      "replied": false,
      "needsReply": false,
      "stage": "connection_sent"
    }
  ],
  "cursor": null
}

GET /campaigns/search_abc/leads/lead_xyz
X-API-Key: sk_live_...

{
  "id": "lead_xyz",
  "fullName": "Jane Doe",
  "linkedinUrl": "https://www.linkedin.com/in/jane-doe/",
  "jobTitle": "VP Sales",
  "companyName": "Acme",
  "tag": "interested",
  "replied": true,
  "needsReply": false,
  "stage": "engaged",
  "headline": "VP Sales at Acme",
  "workExperience": [
    {
      "company": "Acme",
      "position": "VP Sales",
      "location": null,
      "description": null,
      "start": "2022-01",
      "end": null
    }
  ],
  "connectionRequestAccepted": true,
  "messageSent": true
}

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

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

{
  "leadId": "lead_xyz",
  "status": "created",
  "creditsCharged": 1
}

PATCH /campaigns/search_abc/leads/lead_xyz
X-API-Key: sk_live_...
Content-Type: application/json

{
  "tag": "interested",
  "excluded": false
}

{
  "leadId": "lead_xyz",
  "tag": "interested",
  "excluded": false
}

POST /inbox/messages
X-API-Key: sk_live_...
Content-Type: application/json

{
  "campaignId": "search_abc",
  "leadId": "lead_xyz",
  "text": "Hi Jane — following up on our conversation.",
  "accountId": "acc_abc"
}

{
  "ok": true,
  "sentAt": "2026-08-13T09:31:00Z",
  "messageId": "msg_..."
}

POST /linkedin/profiles/lookup
X-API-Key: sk_live_...
Content-Type: application/json

{
  "accountId": "acc_abc",
  "linkedinUrl": "https://www.linkedin.com/in/jane-doe/",
  "depth": "basic"
}

{
  "fullName": "Jane Doe",
  "firstName": "Jane",
  "lastName": "Doe",
  "headline": "VP Sales at Acme",
  "jobTitle": "VP Sales",
  "companyName": "Acme",
  "companyLinkedin": "https://www.linkedin.com/company/acme",
  "website": null,
  "location": "Austin, TX",
  "linkedinUrl": "https://www.linkedin.com/in/jane-doe/",
  "providerId": "...",
  "profilePictureUrl": "https://..."
}

POST /linkedin/search
X-API-Key: sk_live_...
Content-Type: application/json

{
  "accountId": "acc_abc",
  "type": "classic",
  "query": "VP Sales SaaS Austin",
  "limit": 25
}

{
  "results": [
    {
      "fullName": "Jane Doe",
      "headline": "VP Sales at Acme",
      "jobTitle": "VP Sales",
      "companyName": "Acme",
      "location": "Austin, TX",
      "linkedinUrl": "https://www.linkedin.com/in/jane-doe/",
      "providerId": "...",
      "profilePictureUrl": "https://..."
    }
  ],
  "cursor": "opaque-next-page-cursor-or-null"
}

Sending a message

The lead must already exist in the campaign. The call is synchronous — you'll know whether it sent before the response returns.

curl -s https://api.connectzly.com/public/v1/inbox/messages \
  -H "X-API-Key: $CONNECTZLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "search_abc",
    "leadId": "lead_xyz",
    "text": "Hi Jane — following up on our conversation."
  }'

text accepts up to 8,000 characters. accountId is optional; leave it out and the account already associated with the lead is used. Once a message is sent, the conversation follows the same agent and human-handoff rules as the dashboard inbox.

Tagging a lead

Tags are a fixed set — anything outside it is rejected with validation_error.

PATCH /campaigns/search_abc/leads/lead_xyz

{ "tag": "Interested", "excluded": false }

Accepted values: Meeting request, Interested, Information request, Not interested, Wrong person, To be defined. Pass null or an empty string to clear a tag. Tagging may fire a webhook — see below.

Webhooks

Rather than polling, let Connectzly tell you. Point us at an HTTPS URL and we'll POST JSON to it when something happens.

Setting one up

1. Go to app.connectzly.com/api-mcp → Webhooks.
2. Give it a name, an HTTPS URL, and the events you want. You can scope it to a single campaign.
3. Optionally set a signing secret so your endpoint can verify the call came from us.

Five webhooks per workspace by default. Subscriptions are managed in the dashboard rather than over the API.

Events

Payload

{
  "id": "evt_...",
  "type": "reply.received",
  "createdAt": "2026-07-24T05:00:00.000Z",
  "data": {
    "campaignId": "search_abc",
    "leadId": "lead_xyz",
    "accountId": "acc_...",
    "linkedinUrl": "https://www.linkedin.com/in/jane-doe/",
    "fullName": "Jane Doe",
    "messageText": "Thanks, interested in learning more.",
    "tag": null
  }
}

Which data fields are populated depends on the event — messageText appears on replies, tag on tag events, and so on. Very long messages may be truncated at around 4,000 characters.

Verifying the sender

If you set a signing secret, every delivery carries it in a header:

X-Webhook-Signature: your-secret-value

Leave the secret blank and deliveries arrive unsigned.

Delivery guarantees

We attempt each delivery up to three times with a growing gap between tries. Delivery is at-most-once: if the worker fails mid-flight an event can be lost, so treat webhooks as a fast path rather than the only path. If an event absolutely must not be missed, reconcile periodically against GET /campaigns/:id/leads.

A failing endpoint on your side never blocks anything inside Connectzly — the inbox and tagging keep working regardless.

MCP server

MCP — the Model Context Protocol — is how an AI assistant discovers and calls tools. We host a server for you, so Claude, ChatGPT or Cursor can operate LinkedIn through your Connectzly account without you writing an integration.

It is a thin one-to-one wrapper over /public/v1 for a single workspace. Every tool maps to a REST route you can already see above — there are no extra product, billing or documentation tools hiding in it.

URL

Use the origin URL in client config rather than /mcp. The /mcp path is kept as a compatibility alias for the same transport, but the bare origin is what you want.

MCP clients must send Accept: application/json, text/event-stream — that is what the Streamable HTTP transport requires. Any compliant client does this for you.

Which client are you using?

This is the fork in the road, and getting it wrong is the most common setup failure.

Connect Cursor

{
  "mcpServers": {
    "connectzly": {
      "url": "https://mcp.connectzly.com",
      "headers": {
        "X-API-Key": "sk_live_..."
      }
    }
  }
}

For search, lookup and send you'll also need an accountId — copy it from Accounts in the dashboard, or call GET /accounts.

Look before you connect

You can inspect the server with no key at all. Open the URL in a browser, or paste it into an AI assistant, and you'll get a short overview of what the server is and what its tools do.

Public discovery is deliberately thin — tool names and one-line summaries only. It does not expose full JSON schemas, REST paths or request bodies, and it never returns workspace data. Full argument schemas arrive only once a real client connects and runs initialize then tools/list.

Tools mapped to REST

Thirteen tools, each a direct equivalent of a route. If you know the API, you already know the tools.

Cost and safety

Read this row by row before letting an agent run unsupervised. Some tools are free and reversible; two are neither.

What needs a key

The same plan requirements and rate limits apply as on REST. MCP is a different door into the same building, not a way around the locks.

Connect Claude or ChatGPT

Claude.ai, Claude Desktop and ChatGPT all use OAuth. Your API key is not entered in Claude's Advanced settings — you paste it on our consent page after clicking Connect.

Before you start

• Create a key at app.connectzly.com/api-mcp and keep it to hand — it is shown once.
• The MCP URL is https://mcp.connectzly.com.

What to type in each field

In Claude: Customize → Connectors → Add custom connector.

Click Add, then Connect.

After you click Connect

1. A Connectzly page opens asking you to connect your AI assistant.
2. Paste your sk_live_… key.
3. Click Authorize. You're returned to Claude and the connector is live.

What not to do

Cursor is different

Cursor does not use this OAuth flow at all. Use the mcp.json snippet above with headers.X-API-Key instead.

If something goes wrong

Changelog

Public API v1 Current

• REST under /public/v1 — credits, accounts, campaigns, leads, messaging, and LinkedIn lookup and search.
• Outbound webhooks covering four events, with subscriptions managed on the API & MCP page.
• MCP tools mapped one-to-one with REST at https://mcp.connectzly.com.
• Key-free discovery on the MCP host at GET /, /.well-known/mcp.json and /llms.txt — tool names and summaries only; full schemas come from tools/list.
• Optional webhook signing. Set a secret and it is sent back verbatim in X-Webhook-Signature, which works directly with n8n Header Auth.