Build on 8Leads

Base URL

All endpoints live under https://8leads.io/api/v1. Requests and responses are JSON.

Authentication

Create an API key in your workspace settings, then send it as a bearer token. Keys are prefixed 8l_live_ and are scoped to a single workspace. Keep them secret.

Authorization: Bearer 8l_live_xxxxxxxxxxxxxxxx

Scopes

Every key carries scopes. Grant read and/or write, or narrow to a resource like leads:write or campaigns:read.GET needs :read; POST/PATCH/DELETE need :write. A key missing a scope gets 403.

Rate limits

Each key is limited to 120 requests per minute. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; a 429 also sends Retry-After.

Endpoints

The API covers everything the product does:

• Leads: list, create (push), get, update, delete, enrich, tag, and add to lists; plus bulk POST /imports.
• Lists, tags, custom fields: full CRUD.
• Campaigns: create, update, and run the full lifecycle (activate/pause/resume/complete), set the sequence and sending accounts.
• Enrollments: enroll leads (by id or from a list), unenroll, and move between campaigns.
• Accounts: list, pause/resume, run health checks, send a DM from an account to any handle (POST /accounts/{id}/messages), and read an account's full message history (GET /accounts/{id}/messages).
• Inbox: list conversations, read a thread, and send replies.
• Analytics: reply rate, positive rate, sends, funnel, and per-campaign / per-account performance.
• Blocklist: suppress handles you never want contacted.
• Webhooks: create, list, update, test, and delete endpoints, and read each endpoint's delivery log.

List endpoints are paginated. Most use ?page and ?pageSizeand return a pagination object; the inbox uses a cursor.

Example request

curl https://8leads.io/api/v1/campaigns \
  -H "Authorization: Bearer 8l_live_xxxxxxxxxxxxxxxx"

Example response

{
  "data": [
    {
      "id": "cmp_3f9a",
      "name": "Q3 Agency Outbound",
      "status": "ACTIVE",
      "prospectCount": 1240,
      "sentCount": 418,
      "replyCount": 37
    }
  ],
  "pagination": { "page": 1, "pageSize": 25, "total": 8, "pageCount": 1 }
}

Sending from an account

Send a direct message from any connected account to any handle — no existing conversation required. We resolve or create the lead and the thread for you, then record the outbound message. Sends respect the account's safety limits: blocklisted handles are refused, an unavailable or challenged account is refused, and a 429 is returned once the account hits its daily or hourly cap. Read an account's full history — inbound and outbound — from GET /accounts/{id}/messages (filter with ?direction=INBOUND or OUTBOUND).

curl -X POST https://8leads.io/api/v1/accounts/acc_1a2b/messages \
  -H "Authorization: Bearer 8l_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "recipientHandle": "@mayabuilds", "message": "Hey Maya — loved your latest post." }'

Webhooks

Manage webhook endpoints straight from the API (or the dashboard). Create one with POST /webhooks, subscribe it to the events you care about, and we POST each event to your URL as it happens. List, update, and delete endpoints through the same /webhooks routes.

Events now fire across the whole product, including lead.created, reply.received, message.sent, campaign.completed, enrollment.completed, and account.challenged. Fetch the full, current list any time from GET /webhooks/events.

{
  "event": "reply.received",
  "data": {
    "threadId": "thr_9c2e",
    "account": "@growthstudio",
    "prospect": "@mayabuilds",
    "sentiment": "positive"
  }
}

Every delivery is signed so you can trust it came from us. We send an HMAC-SHA256 signature in the x-8leads-signature header. To verify, recompute the HMAC over the raw request body using your whsec_… signing secret and check it matches. You receive that secret once, when you create the endpoint.

If your endpoint is down, we retry with exponential backoff. Every attempt is recorded, so you can pull the delivery log for any endpoint from GET /webhooks/{id}/deliveries to see what we sent and how your server responded.

Connect to Claude (MCP)

Beyond the REST API, 8Leads ships a Model Context Protocol server, so you (and your team) can connect your 8Leads workspace to Claude and work with your data in plain language — ask for your reply rate, pull a campaign, search leads, triage the inbox, send a DM, or launch a campaign.

Add it as a connector with this URL, then sign in with your 8Leads account and approve access:

https://8leads.io/api/mcp

It’s a per-user connection: you sign in as yourself, and everything Claude does runs as you — limited by your role in the workspace, exactly like the dashboard. No API key to share. Revoke access any time from your 8Leads settings. If you belong to more than one workspace, ask Claude to list your workspaces and pick one.

Full reference

Explore every endpoint interactively, or point Postman or a code generator at the machine-readable API spec. In Postman: Import → Link → the spec URL below.