Build with the Leadpoet API

Create requests, work with saved leads and manage campaigns. The API uses the same records, credits and approvals as the Leadpoet app.

Lead engine

Create requests, track progress and manage your targeting.

Pipeline

Read companies and contacts, enrich records and manage deals.

Outreach

Build audiences, prepare campaigns and manage conversations.

Base URL: https://leadpoet.com/api/v1. The OpenAPI schema lists the current endpoints, fields and permissions.

Request access with a short description of what you want to build. We will enable API access for your workspace.

Once access is enabled, manage keys in Account → Developer → API keys. Each secret is shown once. Choose the permissions and expiry you need; revoke keys here anytime.

Connect Leadpoet to Claude, ChatGPT or another AI assistant that supports MCP, without an API key. Once API access is enabled for your workspace, anyone who manages its API keys can connect.

1. Add a custom connector or MCP server. In Claude, open Connectors and choose Add custom connector. In ChatGPT, open Plugins, choose Add, then add a custom MCP server.
2. Enter https://leadpoet.com/mcp as the server URL.
3. Sign in to Leadpoet, choose Read only or Read and edit, decide whether the app may send messages, and select Allow.

The connector offers the same tools, permissions and credits as the API. Send tools appear only when you allow sending. Tools that send, spend credits or change records are labeled so the assistant asks before each call. Manage connections in Account → Integrations → AI assistants, which lists every connection in the workspace. A disconnected app loses access on its next request, and so does every connection if API access is turned off.

claude mcp add --transport http leadpoet https://leadpoet.com/mcp

Start with the OpenAPI schema for current operations and inputs. For a concise machine-readable guide, request this page with Accept: text/markdown.

1. Connect. Add the AI assistant connector, follow the MCP setup or install the CLI. Supply any key through the host's secret store. The package also includes an agent skill.
2. Discover. Read the available tools and input schemas. In the CLI, run leadpoet operations, then leadpoet describe OPERATION. Do not guess fields.
3. Plan from the playbook. Before building an ICP, planning a request or campaign, or drafting outreach, read the sales playbook (getPlaybook in MCP). It needs no key, and each practice cites its studies.
4. Act and verify. Confirm the credit budget before a paid request. Save returned IDs, poll pending work, and reuse the original retry key after an interrupted write. Prepare campaigns as drafts; sending requires explicit approval.

curl https://leadpoet.com/docs/api \
  --header "Accept: text/markdown"

Start with a read. Supply your key through your secret manager as LEADPOET_API_KEY; never place it in browser code or a committed file.

curl "https://leadpoet.com/api/v1/requests?page=1&limit=25" \
  --header "Authorization: Bearer $LEADPOET_API_KEY"

Before creating a paid request, read GET /credits and GET /requests/contact-settings. Confirm the current allowance and compute the credit budget. Save your request body as request.json; this example assumes one included contact per company and a 100-credit budget for ten companies. The minimum budget is 100 credits, and a request must leave at least 100 credits or less than the request's price per company.

{
  "lead_type": "high_intent",
  "request_description": "Revenue operations leaders at US B2B software companies",
  "product_description": "Pipeline analytics for B2B revenue teams",
  "intent_signals": "Hiring revenue operations leadership in the last 180 days",
  "max_leads": 10,
  "credit_budget": 100,
  "countries": ["United States"],
  "company_sizes": ["50–200 employees"],
  "contacts_per_company": 1,
  "included_contacts_per_company": 1,
  "contact_methods": { "email": true, "linkedin": true, "phone": false },
  "phone_enrichment_included": false,
  "require_phone": false
}

Use the full country names and company-size labels accepted by the workspace schema. Supply a fresh UUID as IDEMPOTENCY_KEY, save it with the body, then submit:

curl --request POST https://leadpoet.com/api/v1/requests \
  --header "Authorization: Bearer $LEADPOET_API_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Keep the returned data.query_id and data.icp_id. Read GET /requests/QUERY_ID with the same workspace key. Submission saves the request and reserves credits; it does not mean that sourcing has completed. See request lifecycle before automating a wait.

Send Authorization: Bearer <API_KEY> over HTTPS. A key stays bound to its original workspace, and the creator's current membership and access are checked on each call. IDs from another workspace do not grant access.

Read, write and send permissions are independent. A write scope does not grant read access, and preparing a campaign does not grant permission to send it. Use separate keys for different workflows.

credits:read

Read the workspace credit balance.

lead_engine:read

Read requests, contact allowances, ICPs and recurring request status.

lead_engine:write

Create requests and manage ICPs or recurring requests. Recurring writes also require outreach:send.

pipeline:read

Read saved companies, contacts, deals, notes and pipeline analytics.

pipeline:write

Request contact enrichment and manage pipeline records, stages and notes.

outreach:read

Read accounts, audiences, campaigns, conversations, review queues and analytics; preview campaign contracts.

outreach:write

Prepare audiences and campaigns, edit held work, pause campaigns and inspect delivery evidence.

outreach:send

Authorize launch, resume, approvals, replies and other operations that can enable delivery.

Check the operation's full scope list. A one-time createRequest needs lead_engine:write; including recurrence also needs outreach:send. The OpenAPI x-body-scopes extension describes this conditional permission. Workspace roles, entitlements, evidence and approval checks still apply.

Use /requests for the same requests shown in Lead engine. Use /icps for saved targeting, drafts, publication and version history, and /recurring-requests for supported recurring workflows.

When an ICP draft reports storage_schema_version: 2, it saves targeting only. Send updateIcpDraft a definition with schema_version: 2, company_fit and buyer_groups.

1. Check credits, contact allowances and targeting before submission. Credit reservation happens when the request is accepted.
2. Save the returned IDs. Typical turnaround is 1–2 days; while a request runs, its progress.message says so. Check back periodically rather than polling in a tight loop.
3. Continue until progress.state is ready, failed or archived. An HTTP success confirms the read succeeded; it does not mean the request is ready. A client timeout leaves the saved request intact.
4. Read the saved result in Pipeline and compare its IDs, evidence and delivered counts with the application. On failure, use the safe status message and inspect the request in Lead engine.

Retries with the original identity reuse the saved request and its credit reservation. A replay does not purchase another batch. Contact enrichment follows its own readiness, allowance and credit checks; a company result does not imply that every contact field is available.

Requests use credits from your workspace balance. Your plan sets your monthly credits, how many contacts each company includes and whether mobile numbers are included. GET /credits returns your balance. GET /requests/contact-settings returns included_contacts_per_company, phone_enrichment_included and the unit prices in pricing.

Company

10 credits each, including your included contacts. A request takes 10 to 100 companies.

Extra contact

5 credits per company for each contact above included_contacts_per_company.

Mobile number

1 credit per requested contact when phone_enrichment_included is false. Included when it is true.

Send contacts_per_company and included_contacts_per_company with every request. The server then requires credit_budget to equal this total exactly and max_leads to be between 10 and 100. Without contacts_per_company, the budget divided by 10 sets the number of companies, each with only its included contacts.

credit_budget = max_leads × (
    pricing.credits_per_company
  + pricing.credits_per_extra_contact × max(0, contacts_per_company − included_contacts_per_company)
  + pricing.credits_per_mobile_contact × contacts_per_company   (only when contact_methods.phone is true)
)

10 companies, 1 contact each, 1 included

100 credits

10 companies, 2 contacts each, 1 included

150 credits (100 + 50)

The same request with mobile numbers

170 credits (100 + 50 + 20)

Credits are reserved when the request is accepted. Credits for companies, extra contacts and mobile numbers that are not delivered are refunded. A retry with the same Idempotency-Key reuses the reservation.

Read GET /pipeline?icp_id=ICP_ID for saved companies. The API also supports contact and deal lists, individual and bulk stage changes, deal attribution, pins, company notes and revenue insights. Use the returned resource IDs for subsequent operations.

curl "https://leadpoet.com/api/v1/pipeline?icp_id=$ICP_ID" \
  --header "Authorization: Bearer $LEADPOET_API_KEY"

Reads return saved configuration and evidence. They do not initialize stages, backfill imported records or run enrichment. Leadpoet sets up the contact and deal pipelines when it delivers a request, so delivered results are readable without opening the app. A 409 with reason PIPELINE_SETUP_REQUIRED means that pipeline is not set up yet. Opening Pipeline in the app once also sets it up.

Keep source attribution and partial-result markers. Follow each operation's pagination contract; a bounded snapshot is not a complete workspace export. Contact enrichment requests can be polled through their returned company and request IDs.

Prepare a campaign from saved, eligible contacts. Connected sending accounts and the normal evidence, consent and readiness requirements are prerequisites.

1. Read listSendingAccounts and listAudienceSources. Preview the selection with previewAudience, using an idempotency key. Even an audience preview saves a replay receipt and requires write scope.
2. Call createAudience with the selected request IDs and destination requirement. Inspect admitted and excluded contacts, then retain the returned snapshot_id. Pending requests or a selection with no eligible contacts can return a conflict.
3. Create a held campaign with createCampaign. Set mode: "copilot" and auto_admit: false, choose connected account IDs, and keep the returned strategy_id.
4. Read the campaign in the API or application. Draft creation does not launch the campaign or send a message. Review its audience, content, sender allocation and limits. To drop a draft, use discardCampaign; archiveCampaign applies to paused or completed campaigns.

{
  "name": "API campaign draft",
  "audience_snapshot_id": "<returned-snapshot-uuid>",
  "allowed_account_ids": ["<connected-account-uuid>"],
  "mode": "copilot",
  "auto_admit": false,
  "max_unique_contacts": 1,
  "daily_unique_contact_cap": 1
}

Launch and delivery

When ready to send, use proposeCampaignContract and previewCampaign, review the current result, then supply the required version and approval bindings to launchCampaign. Resolve readiness failures first. Send scope does not bypass approval or fit checks.

The API supports pause and resume, campaign schedules and modes, review and bulk review, queue controls, conversations and replies, and delivery outcomes. Active campaign edits, approvals, resumes and replies may authorize sending and require outreach:send.

Adding contacts to an existing campaign uses previewCampaignAudience followed by addCampaignAudience with the returned preview hash and the same idempotency key. For an unknown delivery, read its saved outcome before considering recovery; never turn an uncertain result into an automatic resend.

Install the @leadpoet/client package from npm. It requires Node.js 22 or later. All clients use the same API and key permissions.

Command line

Install the package globally, then set LEADPOET_API_BASE to the base URL and provide LEADPOET_API_KEY through your shell's secret manager.

npm install -g @leadpoet/client
export LEADPOET_API_BASE=https://leadpoet.com/api/v1

leadpoet operations
leadpoet call getCredits
leadpoet call getContactAllowance
leadpoet describe createRequest
leadpoet call createRequest --input request.json --idempotency-key "$IDEMPOTENCY_KEY"
leadpoet call getRequest --params "{"id":"$QUERY_ID"}"
leadpoet call getPipeline --query '{"icp_id":"<saved-icp-uuid>"}'

--input - reads JSON from stdin; --params supplies path parameters and --query supplies query fields. describe returns the current operation schema. Output is JSON; errors go to stderr. Writes are never automatically retried.

Exit codes: 0 success, 1 transport or server failure, 2 invalid input, 3 credentials or permissions, 4 conflict, 5 throttled, 6 pending timeout or failed request, 130 interrupted. Requests usually take about a day, so check status with getRequest rather than holding a short leadpoet wait. A wait timeout does not cancel fulfillment.

TypeScript client

Install it in your project with npm install @leadpoet/client and import @leadpoet/client. Operation names and envelopes are typed; use OpenAPI for workflow field schemas.

import { LeadpoetClient } from '@leadpoet/client';

const client = new LeadpoetClient({
  baseUrl: process.env.LEADPOET_API_BASE!,
  apiKey: process.env.LEADPOET_API_KEY!,
});
const result = await client.call('getPipeline', {
  query: { icp_id: savedIcpId },
});
const status = await client.call('getRequest', {
  params: { id: savedQueryId },
});
// status.data.progress.state is working, ready, failed or archived.

MCP

Run leadpoet-mcp as a local stdio server in your MCP host; the configuration below starts it with npx, so nothing else needs installing. It discovers the deployment's schemas and exposes the supported operation catalog. Supply the key through your host's secret store; the value below is a placeholder.

{
  "mcpServers": {
    "leadpoet": {
      "command": "npx",
      "args": ["-y", "-p", "@leadpoet/client", "leadpoet-mcp"],
      "env": {
        "LEADPOET_API_BASE": "https://leadpoet.com/api/v1",
        "LEADPOET_API_KEY": "<supply-through-host-secret-store>"
      }
    }
  }
}

Send tools are hidden by default. To enable them deliberately, set LEADPOET_MCP_ALLOW_SEND=1; each send-capable call also needs allowSend: true and the appropriate server scopes. The CLI requires --allow-send, and the TypeScript client requires allowSend: true. This also applies to a request containing recurrence.

Agent skill

The package includes skill/SKILL.md. Install that directory through your agent's normal skill setup. It explains sourcing, saved results, held campaign preparation and recovery from uncertain writes. Installing the skill does not grant API access or permission to send.

Save an unpredictable UUID for each logical write, together with its exact body and acting workspace. Operations using Idempotency-Key reuse the owning workflow's durable identity. Other operations use a body identity, current state, or approval and revision bindings.

After a timeout or interrupted response, inspect the saved outcome before retrying. Keep the original identity and body. A new key may create a second request or campaign. A changed body or an in-progress claim can return 409; resolve the reported conflict rather than retrying blindly.

Read x-retry-contract and x-retry-identity in OpenAPI, or use leadpoet describe OPERATION. The reference labels distinguish header identities, body identities, state changes and bound approvals. An operation labeled none does not gain write-retry protection from an arbitrary header. Respect Retry-After when present.

Workspace successes use { data, request_id }. Keep workflow IDs from data separately from the response's correlation ID. Error responses include a safe code, message and request ID. Validation errors also name each invalid field:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request",
    "request_id": "<request-correlation-id>",
    "details": {
      "validation": {
        "formErrors": [],
        "fieldErrors": { "countries": ["Expected array, received string"] }
      }
    }
  }
}

Follow the rate limit information returned by the API. Preserve details.reason and safe validation details when present. Share the request ID with support, never keys, raw lead data or provider payloads.

Lists use the operation's page, cursor or bounded-snapshot contract in x-pagination. Request history supports page and limit; the SDK also offers requestPages. Advance other cursors explicitly. Preserve results_limited, enrollment_counts_limited and partial or degraded markers; a successful response can still be incomplete.

Paths below are relative to /api/v1. This directory is generated from the same workspace operation catalog as the clients. Open a workflow to browse its operations, then consult OpenAPI for its request body, query fields, response and retry requirements.

Account helpers: GET /me reads API identity and returns its fields without the data envelope; GET /credits reads credits with credits:read. The lists below cover all 128 workspace operations.

Connect accounts, upload files, set up your pipeline and manage CRM integrations in the app. These actions are not available through the workspace API.

Sending-account reads return saved status; they do not reconnect accounts or refresh provider identity. Review holds and unknown delivery states remain visible until resolved through their supported workflow. Available features depend on your account access.

For published-lead delivery, use the webhook guide. Webhook destination management uses the account settings workflow and session-authorized management routes, rather than workspace API keys. Webhook signatures use a separate signing secret.