Build on LeadInbox

LeadInbox is a unified multi-channel inbox with a lead CRM behind it. Every message that reaches your business — WhatsApp, LinkedIn, Instagram, Telegram, Messenger, X, Gmail, Outlook or any IMAP mailbox — lands in one threaded inbox, attached to a single contact record, with a visual pipeline, reply templates and optional AI assistance on top.

Everything the web app does, it does through the same public REST API documented here. There is no separate private surface: the inbox you use, the inbox you embed, and the inbox you script all speak to https://www.leadinbox.ai/api/v1.

1. Create a workspace

Sign up at leadinbox.ai/signup. Signup runs email → plan → profile, and the workspace you land in is your tenant: every contact, conversation, lead, template and API credential belongs to it, and nothing is shared between workspaces. Your pipeline is seeded with seven default stages — New Lead, Contacted, Qualified, Proposal Sent, Negotiation, Won and Lost — which you can rename, recolour, reorder or replace.

2. Connect your first channel

Go to Accounts and pick a provider. WhatsApp and Telegram connect by scanning a QR code (WhatsApp also supports a phone pairing code); Instagram, LinkedIn, Messenger and X connect with your credentials, walking you through a 2FA checkpoint if the provider asks for one; IMAP mailboxes connect with host, port and an app password. Gmail and Outlook use a hosted OAuth flow in a popup window. See Channels for the full breakdown.

Once a channel is connected, LeadInbox backfills recent chats and messages, then keeps the inbox live from provider webhooks. Each connected channel counts as one account against your plan.

3. Get your API key

Your workspace API key lives in the app under Settings → Developer, in the API Credentials panel. The same screen generates your embed snippet and a ready-made prompt you can paste into an AI coding assistant. Copy the key, store it in your server environment, and send it as the X-API-KEY header on every request.

curl -H "X-API-KEY: $LEADINBOX_API_KEY" \
  "https://www.leadinbox.ai/api/v1/conversations?limit=5"

A successful call returns JSON with a conversations array and a next_cursor. If you get a 401, the key is wrong or missing; if you get a 403 on an AI or account endpoint, your plan does not include that capability yet.

Every request to /api/v1 is authenticated — there are no public endpoints. External callers use one of two credentials, and they are checked in this order: the X-API-KEY header first, then an Authorization: Bearer token. (The web app itself uses a third path, the Supabase session cookie, which is not something you can use from outside the browser.)

API key — X-API-KEY

This is the credential for server-to-server work: scripts, back-office jobs, automations, data syncs. The key is per-workspace, not per-user. Calls made with it act as the workspace administrator and can read and write every record in that workspace, so treat it like a database password: keep it on your server, never in browser JavaScript, a mobile binary or a public repository, and rotate it if it leaks by contacting support.

GET /api/v1/contacts?limit=25 HTTP/1.1
Host: www.leadinbox.ai
X-API-KEY: your-workspace-api-key
Accept: application/json

Keys shorter than 20 characters are ignored outright, so a truncated copy-paste presents as an unauthenticated request rather than an invalid key.

Embed token — Authorization: Bearer

The Bearer token is a signed JWT carrying a workspace id and a user id. It is what the embedded inbox uses, and the whole /api/v1 surface accepts it, so it also works as a credential for a front end you control. Generate one from Settings → Developer (it is baked into the embed snippet) or by calling GET /settings/embed-token. Tokens issued this way are long lived — a year — which is convenient for a pinned embed and another reason to keep them off public pages.

curl -H "Authorization: Bearer $LEADINBOX_EMBED_TOKEN" \
  "https://www.leadinbox.ai/api/v1/conversations?limit=20"

Which one should I use?

Use the API key when your own server is the caller and no end user is involved. Use the embed token when a browser is the caller — the iframe embed, or a custom UI you have built — because it is scoped to a specific workspace and user and can be reissued without disturbing your server integrations. Never ship the API key to a browser.

Failure responses

Requests and responses

Everything is JSON, in and out. Send Content-Type: application/json on requests with a body — the one exception is sending a message with attachments, which uses multipart/form-data. Responses are always a JSON object, never a bare array: a list of conversations comes back as { "conversations": [...] }, a single lead as { "lead": {...} }. That leaves room for pagination cursors and related records alongside the payload without a breaking change.

Cursor pagination

List endpoints use keyset pagination rather than offsets, so a page never shifts under you while new messages arrive. Every paginated response carries a next_cursor. Pass it back as the cursor query parameter to fetch the next page, and stop when next_cursor is null, which means the page was not full and you have reached the end.

The cursor is an ISO 8601 timestamp taken from the last item on the page, using whichever column that list is sorted by — last_message_at for conversations, last_contacted_at for contacts, created_at for leads, sent_at for messages. It is opaque in practice: echo it back rather than constructing one yourself.

cursor=""
while : ; do
  resp=$(curl -s -H "X-API-KEY: $LEADINBOX_API_KEY" \
    "https://www.leadinbox.ai/api/v1/conversations?limit=100${cursor:+&cursor=$cursor}")
  echo "$resp" | jq '.conversations[].id'
  cursor=$(echo "$resp" | jq -r '.next_cursor // empty')
  [ -z "$cursor" ] && break
done

Limits

Each list endpoint takes a limit and silently clamps it to its maximum rather than erroring, so asking for 500 conversations returns 100.

Errors

Errors use standard HTTP status codes with a JSON body whose error field is a human-readable sentence. When a request body fails schema validation the response also carries a details array naming the offending fields.

{
  "error": "Invalid request",
  "details": [
    {
      "code": "invalid_type",
      "expected": "string",
      "path": ["display_name"],
      "message": "Required"
    }
  ]
}

Timestamps, ids and casing

All timestamps are ISO 8601 strings in UTC, for example 2026-03-14T09:41:07.812Z. All record ids are UUIDs generated by LeadInbox; where a provider has its own identifier it is exposed separately as unipile_chat_id, unipile_message_id or unipile_account_id. Field names are snake_case. Channel names in provider fields are upper case — WHATSAPP, LINKEDIN, INSTAGRAM, TELEGRAM, MESSENGER, TWITTER, GOOGLE (Gmail), OUTLOOK, MAIL (IMAP). Filters accept either case and are upper-cased for you.

Partial updates

Update endpoints are PATCH and take only the fields you want to change; omitted fields are left alone. Most of them validate strictly, meaning a typo in a field name is a 400 rather than a silently ignored write — a deliberate choice, because a silently dropped update is much harder to debug than a rejected one.

The fastest way to put LeadInbox inside another product is not to rebuild the UI at all. The full inbox — conversation list, thread view, composer, templates, attachments — runs inside an iframe and can be dropped into any page you control.

Getting your snippet

Open Settings → Developer in the app. The Embed panel generates a snippet with your token already in the URL, and offers a preview link so you can confirm the frame renders before you paste it anywhere. The same payload is available from the API:

curl -H "X-API-KEY: $LEADINBOX_API_KEY" \
  "https://www.leadinbox.ai/api/v1/settings/embed-token"

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "embed_url": "https://www.leadinbox.ai/embed/inbox?token=...",
  "snippet": "<iframe src=... ></iframe>"
}

The snippet

<iframe
  src="https://www.leadinbox.ai/embed/inbox?token=YOUR_EMBED_TOKEN"
  style="width: 100%; height: 700px; border: 0; border-radius: 12px;"
  allow="clipboard-write"
  title="LeadInbox"
></iframe>

How the token is handled

The token in the URL is what authenticates the frame. On load, the embed page moves it into sessionStorage, strips it from the visible URL with a history replace, and attaches it as an Authorization: Bearer header to every API request the inbox makes. It is not persisted anywhere else and does not survive the tab being closed. If the frame renders “Missing embed token”, the URL parameter was dropped somewhere between your page and the iframe — usually by a link shortener or a proxy that rewrites query strings.

Sizing and layout

The embedded inbox fills the iframe and manages its own internal scrolling, so the frame does not grow with the content — you set the box, the inbox lays itself out inside it. Give it a real height: a percentage height only works if every ancestor also has one, so a fixed height in pixels, a viewport unit, or a flex or grid cell with a resolved height are all safer choices. Below roughly 600 px of height the two-pane layout becomes cramped; around 700 px is a comfortable default. Width is fluid, and the layout collapses to a single pane on narrow screens, so width: 100% inside your own container is usually right.

<div style="height: calc(100vh - 64px);">
  <iframe
    src="https://www.leadinbox.ai/embed/inbox?token=YOUR_EMBED_TOKEN"
    style="width: 100%; height: 100%; border: 0;"
    allow="clipboard-write"
    title="LeadInbox"
  ></iframe>
</div>

Keep allow="clipboard-write" — copying a phone number or a message body from inside the thread depends on it.

Building your own UI instead

If the embed is not the right fit, the same embed token authenticates the whole REST API, so you can build a bespoke interface against the endpoints below and keep LeadInbox as the messaging backend.

A conversation is one thread on one channel: a WhatsApp chat, a LinkedIn conversation, an email thread. It links a contact to the connected account that received it, and carries the counters the inbox list renders — unread count, last message preview, direction and timestamp.

curl -H "X-API-KEY: $LEADINBOX_API_KEY" \
  "https://www.leadinbox.ai/api/v1/conversations?provider=WHATSAPP&is_read=false&limit=20"

{
  "conversations": [
    {
      "id": "6f1c...",
      "provider": "WHATSAPP",
      "status": "active",
      "is_read": false,
      "unread_count": 3,
      "message_count": 14,
      "last_message_at": "2026-03-14T09:41:07.812Z",
      "last_message_preview": "Can you send the proposal today?",
      "last_message_direction": "inbound",
      "contact": { "id": "b2e0...", "display_name": "Maya Osei", "company": "Northwind" },
      "connected_account": { "id": "0a9d...", "provider": "WHATSAPP" },
      "lead": { "stage": { "name": "Qualified" }, "ai_score": 78 }
    }
  ],
  "next_cursor": "2026-03-14T09:41:07.812Z"
}

curl -H "X-API-KEY: $LEADINBOX_API_KEY" \
  "https://www.leadinbox.ai/api/v1/conversations/CONVERSATION_ID?message_limit=50"

curl -X PATCH -H "X-API-KEY: $LEADINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "archived", "is_read": true}' \
  "https://www.leadinbox.ai/api/v1/conversations/CONVERSATION_ID"

Messages are read as part of a conversation and written with a single send endpoint. Sending is real: the message goes out on the underlying channel to the actual recipient. There is no test mode, so guard automated sending carefully.

curl -X POST -H "X-API-KEY: $LEADINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body": "Thanks — the proposal is on its way this afternoon."}' \
  "https://www.leadinbox.ai/api/v1/conversations/CONVERSATION_ID/messages"

HTTP/1.1 201 Created
{
  "message": {
    "id": "9c33...",
    "direction": "outbound",
    "body_text": "Thanks — the proposal is on its way this afternoon.",
    "has_attachments": false,
    "attachment_count": 0,
    "status": "sent",
    "sent_at": "2026-03-14T10:02:44.301Z"
  }
}

curl -X POST -H "X-API-KEY: $LEADINBOX_API_KEY" \
  -F "body=Here is the proposal and the case study." \
  -F "files=@proposal.pdf" \
  -F "files=@case-study.pdf" \
  "https://www.leadinbox.ai/api/v1/conversations/CONVERSATION_ID/messages"

curl -L -H "X-API-KEY: $LEADINBOX_API_KEY" \
  -o invoice.pdf \
  "https://www.leadinbox.ai/api/v1/attachments/ATTACHMENT_ID"

A contact is one person across every channel. When someone who emails you also messages on WhatsApp, both threads hang off the same contact record, and provider_identities records which handle belongs to which channel. Contacts also carry free-form tags and a custom_fields object you can use for your own attributes.

curl -H "X-API-KEY: $LEADINBOX_API_KEY" \
  "https://www.leadinbox.ai/api/v1/contacts?search=acme&limit=50"

curl -X POST -H "X-API-KEY: $LEADINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "display_name": "Maya Osei",
        "email": "maya@northwind.example",
        "company": "Northwind",
        "job_title": "Head of Ops",
        "tags": ["inbound", "webinar"]
      }' \
  "https://www.leadinbox.ai/api/v1/contacts"

curl -X PATCH -H "X-API-KEY: $LEADINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["inbound", "priority"], "custom_fields": {"crm_id": "AC-4471"}}' \
  "https://www.leadinbox.ai/api/v1/contacts/CONTACT_ID"

curl -X POST -H "X-API-KEY: $LEADINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"primary_id": "KEEP_ID", "secondary_id": "DUPLICATE_ID"}' \
  "https://www.leadinbox.ai/api/v1/contacts/merge"

The pipeline is a set of ordered stages; a lead is a contact moving through them. Stages carry a name, colour, position and three behavioural flags — is_default (where new leads land), is_won and is_lost — which drive the kanban board and the won/lost reporting.

Stages

curl -H "X-API-KEY: $LEADINBOX_API_KEY" "https://www.leadinbox.ai/api/v1/pipeline/stages"

{
  "stages": [
    { "id": "1f2a...", "name": "New lead", "slug": "new-lead", "color": "#6B7280",
      "position": 0, "is_default": true, "is_won": false, "is_lost": false }
  ]
}

curl -X POST -H "X-API-KEY: $LEADINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Demo booked", "color": "#2563EB", "position": 3}' \
  "https://www.leadinbox.ai/api/v1/pipeline/stages"

Leads

curl -H "X-API-KEY: $LEADINBOX_API_KEY" \
  "https://www.leadinbox.ai/api/v1/leads?ai_classification=hot&min_score=70&limit=50"

curl -X POST -H "X-API-KEY: $LEADINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "contact_id": "CONTACT_ID",
        "stage_id": "STAGE_ID",
        "title": "Northwind — 40 seats",
        "value": 12000,
        "currency": "GBP",
        "source": "webinar"
      }' \
  "https://www.leadinbox.ai/api/v1/leads"

curl -X PATCH -H "X-API-KEY: $LEADINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "won", "value": 12000}' \
  "https://www.leadinbox.ai/api/v1/leads/LEAD_ID"

curl -X POST -H "X-API-KEY: $LEADINBOX_API_KEY" \
  "https://www.leadinbox.ai/api/v1/leads/LEAD_ID/score"

{
  "lead": { "ai_score": 78, "ai_classification": "hot", "ai_scored_at": "..." },
  "scoring": {
    "score": 78,
    "classification": "hot",
    "reasons": ["Asked for pricing", "Decision-maker job title"],
    "nextAction": "Send the proposal and offer two call slots this week"
  }
}

A connected account is one channel login: a WhatsApp number, a LinkedIn profile, a mailbox. Accounts are the unit your plan counts, and their status tells you whether messages are still flowing — ok, connecting, credentials_expired, checkpoint_required, disconnected or error.

curl -H "X-API-KEY: $LEADINBOX_API_KEY" "https://www.leadinbox.ai/api/v1/accounts"

{
  "accounts": [
    {
      "id": "0a9d...",
      "provider": "WHATSAPP",
      "provider_user_name": "+44 7700 900123",
      "status": "ok",
      "last_sync_at": "2026-03-14T09:12:00.000Z"
    }
  ]
}

curl -X POST -H "X-API-KEY: $LEADINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"providers": ["GMAIL"], "callback_url": "https://app.example.com/settings"}' \
  "https://www.leadinbox.ai/api/v1/accounts"

{ "auth_link": { "url": "https://..." } }

# Disconnect, keep history
curl -X DELETE -H "X-API-KEY: $LEADINBOX_API_KEY" \
  "https://www.leadinbox.ai/api/v1/accounts/ACCOUNT_ID"

# Remove entirely
curl -X DELETE -H "X-API-KEY: $LEADINBOX_API_KEY" \
  "https://www.leadinbox.ai/api/v1/accounts/ACCOUNT_ID?mode=remove"

Reply templates are saved snippets with a shortcode, a category and optional channel restrictions. Shared templates are visible to the whole workspace; private ones only to their author. Lists are returned most-used first and are not paginated.

curl -X POST -H "X-API-KEY: $LEADINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Follow up",
        "category": "follow_up",
        "body_text": "Hi {{contact.first_name}}, just following up on our conversation — would a call this week work?",
        "providers": ["LINKEDIN", "GOOGLE"],
        "is_shared": true
      }' \
  "https://www.leadinbox.ai/api/v1/templates"

Variables

Template bodies may contain {{variable}} placeholders, which the composer fills in from the open conversation at the moment you insert the template. A placeholder with no value resolves to an empty string rather than leaving the raw token in the message. The API stores and returns the template text verbatim — substitution happens where the template is used, so if you send a template body through the messages endpoint yourself, substitute the values first.

Day to day, LeadInbox stays current from provider webhooks — you should not need to poll. These endpoints cover the exceptions: a manual backfill, and the workspace-level settings behind the developer tools.

curl -X POST -H "X-API-KEY: $LEADINBOX_API_KEY" "https://www.leadinbox.ai/api/v1/sync"

{
  "success": true,
  "synced": { "contacts": 12, "conversations": 31, "messages": 428 },
  "accounts_found": 3,
  "chats_fetched": 31
}

curl "https://www.leadinbox.ai/api/v1"

{ "name": "LeadInbox API", "version": "1.0.0" }

LeadInbox connects nine channel types across messaging and email. Each connection is one account against your plan, and you can connect several of the same type — two WhatsApp numbers and three mailboxes is four accounts, all landing in the same inbox.

In-app connection flows

Most channels connect natively inside the app, with no third-party wizard and no redirect away from LeadInbox.

Hosted connection flow

Gmail and Outlook connect through a hosted OAuth flow, which opens in a popup because their OAuth consent must be granted to the messaging platform's own application. Click Connect on those cards, complete Google's or Microsoft's consent screen, and you are returned to your accounts page. The same flow is available over the API via POST /accounts, which returns a link to open.

After connecting

Recent chats and messages are backfilled so the inbox is not empty, contacts are created or matched, and from then on inbound activity arrives by webhook. Sending is symmetrical: a reply on a messaging channel goes out as a chat message, and a reply on an email channel goes out as a threaded reply to the most recent inbound message in that thread. If a channel's credentials expire, its account status changes and it is flagged in the app so you can reconnect.

AI in LeadInbox runs on your own provider key. You supply a key from Anthropic, OpenAI or Google under Settings → AI; it is live-tested before it is stored, and every AI call is billed by that provider to you directly. Nothing is resold, and there are no opaque credit packs. AI features are part of the Growth plan — on other plans the AI endpoints return 403 with upgrade: true.

Each feature can also be switched off for the whole workspace, in which case its endpoint returns a 403 or an empty suggestion rather than calling your provider. AI usage is logged per workspace so you can reconcile it against your provider bill.

It is worth separating two things that both get called “webhooks”.

Inbound: how LeadInbox stays live

LeadInbox receives webhooks from the messaging platform that fronts your connected channels. Those deliveries are what make the inbox real time: a new WhatsApp message, an email arriving or being sent, an account status change, a new LinkedIn relation, and email tracking events (opens and link clicks) are all pushed to LeadInbox, verified by signature, and turned into conversation and message records. Every delivery is recorded in a webhook event log, and the ten most recent are visible in the app under Settings and returned by GET /settings. You do not configure this — connecting an account sets it up — but it is why you rarely need to poll or call POST /sync.

Outbound: notifying your systems

Your workspace has a webhook_url and a webhook_secret, set under Settings → Developer or with PATCH /settings. These fields configure the destination for outbound notifications and the shared secret that will be used to sign them.

curl -X PATCH -H "X-API-KEY: $LEADINBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "webhook_url": "https://api.example.com/hooks/leadinbox",
        "webhook_secret": "a-long-random-string"
      }' \
  "https://www.leadinbox.ai/api/v1/settings"

Reading settings back never echoes the secret in full — it is masked to its last four characters, so store your own copy when you set it.

There is no official SDK package for LeadInbox yet — no npm or PyPI client, and no published OpenAPI document. The REST API described on this page is the supported integration route, and it is deliberately plain: JSON over HTTPS, one header for authentication, cursor pagination. Any HTTP client in any language works, and Settings → Developer includes a copy-paste prompt that gives an AI coding assistant your embed snippet, your key and the endpoint reference in one go.

For anything else — an endpoint behaving unexpectedly, a channel that will not connect, a key you need rotated, or a capability you need that is not here — email contact@desklink.ai. Include your workspace name, the endpoint and method, the approximate time of the request and the status code you saw; never include your API key or an embed token in an email.