# Leadpoet API Connect Lead engine, Pipeline and Outreach to your tools and agents. The API uses the same records, credits and approvals as the Leadpoet app. ## Start here 1. Every workspace, Free included, has API access. [Create an account](https://leadpoet.com/auth), then the workspace owner or a team admin manages scoped keys in Settings → Developer → API keys. 2. Use base URL https://leadpoet.com/api/v1 and an Authorization: Bearer header. Keep LEADPOET_API_KEY in your secret store, never in source, arguments or logs. 3. Read the [OpenAPI schema](https://leadpoet.com/api/v1/openapi.json) for current operations, inputs, scopes, pagination and retry rules. Do not guess fields. 4. Start with GET /me, GET /credits and GET /requests/contact-settings. 5. Before you build an ICP, plan a request or campaign, or draft outreach, read the [sales playbook](https://leadpoet.com/api/v1/playbook) (`getPlaybook` in MCP; no key needed). Each practice cites its studies. Add `?topic=target-market` or `?topic=messaging` for one topic. ## Connect an AI assistant Add https://leadpoet.com/mcp as a custom connector or MCP server (in ChatGPT, add a custom MCP server under Plugins; in Cursor, add it to mcp.json as {"mcpServers": {"leadpoet": {"url": "https://leadpoet.com/mcp"}}}), then sign in with Leadpoet as the workspace owner or a team admin. A new user can create a free account on the same sign-in page and returns to the connection without opening the app. Choose read-only or read-and-edit access, and whether the app may send messages. With sending on, Leadpoet tells the assistant to get the user's approval of the recipients and the message before each send; in an app that runs tools without asking, leave sending off. The connector has the same tools, permissions and credits as the API; disconnect in Settings → Integrations → AI assistants. In Claude Code: `claude mcp add --transport http leadpoet https://leadpoet.com/mcp`, or install the plugin with `/plugin marketplace add leadpoet/leadpoet-plugin`, then `/plugin install leadpoet@leadpoet`; then run `/mcp` to sign in. What to ask once connected: https://leadpoet.com/ai-assistants. ## Connect a client Requires Node.js 22 or later. Install the package with `npm install -g @leadpoet/client` and set LEADPOET_API_BASE=https://leadpoet.com/api/v1. - [MCP](https://leadpoet.com/docs/api#mcp): add this stdio server to the host and supply the key through the host's secret store. Send tools stay hidden unless the host also sets LEADPOET_MCP_ALLOW_SEND=1. ```json { "mcpServers": { "leadpoet": { "command": "npx", "args": ["-y", "-p", "@leadpoet/client", "leadpoet-mcp"], "env": { "LEADPOET_API_BASE": "https://leadpoet.com/api/v1", "LEADPOET_API_KEY": "" } } } } ``` - [CLI](https://leadpoet.com/docs/api#cli): run `leadpoet operations`, then `leadpoet describe OPERATION`. Use `leadpoet call OPERATION` with JSON --input, --params and --query as documented. Output is JSON. - [Agent skill](https://leadpoet.com/docs/api#skill): install the package's skill/SKILL.md directory through your agent's skill setup. - [TypeScript](https://leadpoet.com/docs/api#typescript): run `npm install @leadpoet/client` and import LeadpoetClient from it. ## Lead requests Confirm targeting, quantity and credit budget with the user, then call createRequest with a fresh UUID Idempotency-Key saved alongside the body. - Budget: send contacts_per_company and included_contacts_per_company, then the exact total as credit_budget (see Credits). The minimum is 100 credits: ten companies with one included contact each. A request must leave at least 100 credits, or less than the request's price per company. - Countries use full names, such as "United States". Company sizes use the app labels: "<10 employees", "10–50 employees", "50–200 employees", "200–500 employees", "500–1,000 employees", "1,000–5,000 employees", "5,000–10,000 employees" and "10,000+ employees". The /reference/* lists belong to a retired standalone lane; do not use their codes here. - Save data.query_id and data.icp_id. Submission reserves credits; a replay with the same key and body returns the same request without a second charge. - Requests are researched and verified by Leadpoet. Typical turnaround is 1–2 days. Tell the user the request is running, then check getRequest later. data.progress.state is "working", "ready", "failed" or "archived" (won't be fulfilled); while working, wait data.progress.check_again_after_seconds. Do not poll in a tight loop or resubmit. ## Credits Your plan sets your monthly credits, the contacts each company includes and whether mobile numbers are included. GET /credits returns the balance. GET /requests/contact-settings returns included_contacts_per_company, phone_enrichment_included and the unit prices in pricing. - Company: 10 credits, including the included contacts. A request takes 10 to 100 companies (max_leads). - Extra contact: 5 credits per company for each contact above included_contacts_per_company. - Mobile number: 1 credit per requested contact unless phone_enrichment_included is true. ```text 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) ) ``` With contacts_per_company in the body, a budget that does not match this total is rejected. Without it, credit_budget / 10 sets the number of companies, each with only its included contacts, so always send it. Example: 10 companies with 2 contacts each and 1 included cost 150 credits; with mobile numbers, 170. Credits are reserved when the request is accepted. Credits for companies, extra contacts and mobile numbers that are not delivered are refunded. ## ICPs createManualIcp and createIcpDraft return the draft's id and draft_revision. updateIcpDraft needs expected_revision; a stale revision returns 409. When the draft reports storage_schema_version: 2, send a definition with only schema_version: 2, company_fit and buyer_groups. publishIcp needs expected_draft_revision and an Idempotency-Key. ## Pipeline Use getPipeline with the saved ICP ID for companies, and listPipelineContacts with the same icp_id for contact engagements. Preserve partial results and pagination limits; never invent missing data. Leadpoet sets up the contact and deal pipelines when it delivers a request. A 409 PIPELINE_SETUP_REQUIRED means that pipeline is not set up yet; opening Pipeline in the app once also sets it up. ## Outreach Read listSendingAccounts and listAudienceSources. previewAudience and createAudience take the selected sources (for example request_ids) and an Idempotency-Key; createAudience returns snapshot_id. createCampaign with mode: "copilot" and auto_admit: false returns strategy_id, the campaign ID used by every /outreach/campaigns/{id} operation. Creating a campaign does not launch it or send anything. Drop a draft with discardCampaign; archiveCampaign applies to paused or completed campaigns. ## Errors Errors return {error: {code, message, request_id, details}}. A 400 includes details.validation.fieldErrors naming each invalid field. A 409 carries details.reason: reload the record, or reuse the original retry key and body. A 402 means not enough credits: details.credits_remaining and details.credits_needed give the gap. An eligible new Free account also gets details.signup_credit_offer; show its message and claim_url to the user, then resubmit with the same Idempotency-Key and body once they claim it. On 429, honor Retry-After. After a 5xx or timeout a write may have committed: read its saved state before retrying. To report a bug, such as a call that keeps failing with a 5xx or a result that looks wrong, email hello@leadpoet.com with the operation name, the time and the request_id. Leave out keys, contact data and message text. Over MCP, the request ID is in each result's _meta under leadpoet.com/request_id, not in the text the assistant reads, so report the tool name and time. ## Sending and recovery Sending requires the user's explicit approval of recipients and content, current readiness/approval bindings, and outreach:send scope. CLI sends also require --allow-send. MCP send tools are hidden unless the host sets LEADPOET_MCP_ALLOW_SEND=1; each call then requires allowSend: true. Recurring requests also require send permission and consent. After an interrupted write, inspect saved state and preserve the original idempotency key and body. A new key can duplicate work or charges. Read the operation's x-retry-contract before retrying; writes are not automatically retried. Workspace responses contain data and request_id; GET /me returns its identity fields without that envelope. Retain workflow IDs separately from the response's correlation ID. HTTP success does not prove sourcing completion or message delivery. Report the saved status and any pending work. ## Reference - [HTTP quickstart](https://leadpoet.com/docs/api#quickstart) - [Authentication and scopes](https://leadpoet.com/docs/api#authentication) - [Operation reference](https://leadpoet.com/docs/api#reference) - [Responses and errors](https://leadpoet.com/docs/api#responses) - [Availability](https://leadpoet.com/docs/api#availability) - [Webhooks](https://leadpoet.com/docs/webhooks): signed published-lead events. - [HubSpot](https://leadpoet.com/docs/hubspot): connect your CRM. Account connections, file uploads, pipeline setup and CRM management use the app.