SDRPilot Docs

Using the API and MCP Tools

Everything you do in SDRPilot can also be done from a script or an AI assistant: your leads, the connection request queue, your ICP rules, your inbox, your agents and your settings.

The API and the MCP tools are included on every plan.

Create an API key

  1. In SDRPilot, open Settings → API.
  2. Choose Create key.
  3. Copy the key straight away. It starts with key_live_ and is shown only once. If you lose it, create a new one. Keys created earlier with a different prefix keep working.

Keys created at app.sdrpilot.ai start with sdrp_live_; keys created on a white-label agency’s own app address start with key_live_. Both work the same way, on the API and on the MCP server.

The key acts as you, with the same permissions you have in the app, so treat it like a password. You can revoke a key at any time on the same page, and every script or assistant using it is cut off at once.

Champions Circle members can also use the API key of their DM Champ account.

Calling the API directly

  • Base URL: https://app.sdrpilot.ai/api/v1
  • Header: X-API-Key: YOUR_API_KEY or Authorization: Bearer YOUR_API_KEY
  • Machine readable description: https://app.sdrpilot.ai/api/v1/docs/openapi.yaml, also available as .json

The OpenAPI document is public and describes every route, so most API tools and code generators can import it without a key. Route by route details live on the API Reference page.

Both headers work the same way. What you cannot do is send a wrong key and hope it falls through to something else: once a key is presented, the answer is based on that key.

What comes back when something is wrong:

Response What it means
401 The key is missing, invalid or revoked, or api_access_disabled: API access is switched off for this client workspace, or the workspace is paused.
402 subscription_required: the workspace has no active plan or trial. Starting or resuming an agent and actions that reach LinkedIn are refused until a plan is active; the message points you to Settings → Billing.
403 The key is valid, but its workspace is not allowed to make this call.
429 Too many rejected attempts in a minute for that key. Slow down.
502 We could not check your key just then. It is never treated as a pass. Retry.

Connecting an AI assistant

The SDRPilot tools live on the MCP endpoint https://mcp.sdrpilot.ai/mcp, authenticated with the same API key in the X-API-Key header. Settings → API shows the same address next to your keys.

The tools are all prefixed linkedin_, so they are easy to spot in your assistant’s tool list and easy to ask for by name. There is one per API operation, and there are no per tool permissions: a tool can do whatever you can do in the app. When a tool takes a request body, the fields go under a single body argument.

The plugin for Claude Code

On Claude Code the quickest way is the plugin. It sets up the connection and adds a skill, a playbook Claude reads first: how SDRPilot is put together (your ICP, scoring, the connection queue, conversations), the common workflows step by step, and what it must ask you before it acts, such as anything that reaches a real person on LinkedIn.

claude plugin marketplace add sdrpilot/claude-plugin
claude plugin install sdrpilot@sdrpilot

Then start claude, run /plugin configure sdrpilot@sdrpilot and paste your API key (see Create an API key). It is stored in your system keychain, not in a file. Restart Claude Code and run /mcp to see the server connected.

Any MCP client

Add a remote MCP server in your assistant with the address https://mcp.sdrpilot.ai/mcp and the header X-API-Key: YOUR_API_KEY. In Claude Code that is one command:

claude mcp add --transport http outreach https://mcp.sdrpilot.ai/mcp --header "X-API-Key: YOUR_API_KEY"

Restart the assistant, or reconnect the server, and the tools appear in its tool list.

The help docs are built in

The MCP endpoint also gives your assistant this documentation. Three tools, docs_search, docs_read and docs_list, read the help docs live, so the assistant can look up how a feature works instead of guessing. There is nothing to set up, and the docs tools never touch your account data.

Client workspaces

When an agency runs your workspace for you, you get the API and the MCP tools too, under the agency’s brand:

  • Keys are created in Settings. Open Settings → API in your own workspace and choose Create key, exactly as above.
  • A key reaches only your workspace. Every call answers with the leads, conversations, agents and settings of the workspace the key was created in, nothing else.
  • Agency pages are not available to it. The agency’s client list, its branding, its reselling and its billing cannot be reached with a client key; those calls answer 404.
  • Keys never sign anyone in. Opening a client workspace, switching into it and going back to the agency only work from the app. A key that asks for one of those sign-in links gets 403, an agency key included.
  • The agency decides. The agency can switch API access off for your workspace on its Clients page. While it is off the API card is hidden and your keys answer 401 with api_access_disabled; switched back on, the same keys work again within a minute. Pausing the workspace has the same effect on the keys.
  • Use the addresses shown in Settings. The API card lists the API base and the MCP address for your workspace. Those are the ones to use in scripts and assistants, also when they differ from the examples on this page.

Example 1: only accept leads from certain countries

Your ICP profile holds the rules leads have to pass. This sets an allow list of the Netherlands and Belgium. Country codes are two letters, uppercase.

curl -X PUT https://app.sdrpilot.ai/api/v1/icp/YOUR_ICP_ID/filters \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"countries":{"mode":"allow","codes":["NL","BE"]}}'

Two things to know. The body is the complete set of rules, not a patch: a rule you leave out is switched off. And the answer includes an impact_on_queue block telling you how many already queued connection requests would fail the new rules. Once saved, the new rules are applied to the queue automatically: waiting requests that fail them are withdrawn.

In an assistant you would say: “Set my ICP to accept only the Netherlands and Belgium, and tell me what that would do to my queue.”

Example 2: see what is queued

Connection requests that are approved but not sent yet:

curl -s "https://app.sdrpilot.ai/api/v1/connections/queue?status=queued&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"

Each row carries the person’s name, headline, company, location, country, their connection and follower counts, and the score. Narrow the list with country, min_score, max_score and source, and page through it with limit and cursor. Requests already sent are history and cannot be changed.

Example 3: withdraw everyone outside your countries

After changing your rules, re-check the queue against them. Without apply=true this is a preview and changes nothing:

curl -X POST "https://app.sdrpilot.ai/api/v1/connections/queue/rescreen" \
  -H "X-API-Key: YOUR_API_KEY"

You get back how many were examined, how many would be withdrawn, and a breakdown per rule, such as country or the lead’s network being smaller than your minimum. Happy with it? Run it again with ?apply=true and those requests are withdrawn.

Example 4: score the queue again with AI

Rescreen checks the hard rules. Re-scoring asks the AI to grade the queued leads again against your current ideal customer profile, which is what you want after rewriting your ICP description rather than its filters. Preview first:

curl -X POST "https://app.sdrpilot.ai/api/v1/connections/queue/rescore" \
  -H "X-API-Key: YOUR_API_KEY"

This one has no preview. It queues one AI re-qualification per lead right away (up to 500 per call, included in your plan) and answers with how many were queued. As each lead is re-scored, its score and reasoning are updated; a request whose lead no longer passes your rules or your qualification bar is withdrawn, the rest stay queued. Pass {"ids": [...]} or {"filter": {...}} in the body to limit it to part of the queue; an empty body re-scores every waiting request.

Import leads

Have a list from Apollo, Clay or a spreadsheet? Send it to POST /leads/bulk, up to 100 people per call. Larger lists go in several calls.

curl -X POST "https://app.sdrpilot.ai/api/v1/leads/bulk" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "source": "search",
    "agent_id": "YOUR_AGENT_ID",
    "linkedin_account_id": "THE_AGENTS_LINKEDIN_ACCOUNT_ID",
    "tags": ["apollo-october"],
    "leads": [
      {"name": "Jane Doe", "profile_url": "https://www.linkedin.com/in/jane-doe", "headline": "CEO at Acme"}
    ]
  }'
  • Every lead needs name and profile_url (a linkedin.com/in/ link). headline and a per-lead source_context object (for your own notes, such as company or email) are optional. One lead missing a field rejects the whole call with invalid_lead, naming the lead, so nothing is half imported.
  • agent_id is the agent the leads are for. linkedin_account_id names the LinkedIn account they are added to; it must be the agent’s own account or one in its sender pool. With a single LinkedIn account you can leave it out.
  • tags (optional) are added to every new lead.
  • The answer tells you how many were created and how many were skipped because they are already your leads.

Imported leads start as new and are scored against the agent’s ICP before any connection request goes out, exactly like the leads an agent finds itself. The same import is the linkedin_create_leads_bulk MCP tool, and the Leads page has a CSV import for doing it by hand.

Long-running work does not block the call

Anything that touches LinkedIn or the AI is queued and the call returns at once, so a request never sits open for minutes. You get back what was queued and you read the result later:

What you start What to poll Done when
Connect a LinkedIn account (POST /auth/linkedin/connect, /verify-2fa, /refresh) GET /auth/linkedin/progress, then GET /auth/linkedin/status the seat shows active
Re-scrape and re-score a lead (POST /leads/{id}/enrich) GET /leads/{id} profile_scraped_at and the score update
Build or rebuild an ICP (POST /icp, POST /icp/{id}/rebuild) GET /icp/{id} build_status is ready
Re-check, withdraw or re-score the queue (POST /connections/queue/...) GET /connections/queue each request is queued or withdrawn
Send a message (POST /conversations/{id}/messages) GET /conversations/{id} the message appears in the thread
Scrape a monitored post (POST /posts, POST /posts/{id}/scrape) GET /posts and GET /leads scrape_status is completed and new engagers appear as leads
Generate, schedule or publish a post (POST /content/...) GET /content/{id} status moves from draft or scheduled to posted
Profile optimizer sync, analyze, apply GET /profile-optimizer status is ready

Builds, content generation and login have no webhook, so poll those. What does send a webhook is below.

Webhooks

Set up webhooks in Settings under Webhooks (add an endpoint, pick the events, see the delivery log), or through the API and MCP tools:

  1. POST /webhooks (linkedin_create_webhook) with a url that starts with https://, the events you want and an optional name. You may pass your own secret (16 to 256 characters); otherwise one is made for you. The response carries the secret once, so store it.
  2. GET /webhooks lists them, PATCH /webhooks/{id} changes the URL, the events or switches one off, DELETE /webhooks/{id} removes it, and GET /webhooks/{id}/deliveries shows what was sent and how your endpoint answered.

Every delivery is a POST with a JSON body of event, timestamp and data. The X-Webhook-Signature header is sha256= followed by the hex HMAC SHA256 of the raw body, made with your secret. Check it before trusting the payload.

Deliveries go out for lead.qualified (a lead passed qualification; data carries lead_id, lead_name, agent_id, score and threshold), connection.sent (an invitation went out), connection.accepted (a lead accepted), conversation.started (a new conversation with a lead began; data carries conversation_id, lead_id, agent_id and thread_id), conversation.needs_attention (your agent handed a conversation to you; data adds handoff_reason and goal_progress), conversation.completed (a conversation was archived; data carries conversation_id, lead_id, agent_id and completed_at) and agent.error (an agent stopped with an error; data carries agent_id and reason). Every active webhook subscribed to an event gets its own delivery. A webhook subscribed to connection.accepted also receives incoming_invitation.accepted when you accept someone else’s request. Older setups may still list lead.created, lead.status_changed, meeting.booked or agent.daily_summary: those never send anything and are dropped the next time the webhook is saved.

Monitored posts

Your agent keeps a list of LinkedIn posts it watches for engagement: your own recent posts and the posts content search finds for it. People who react or comment on them become leads. The list is on the agent’s Overview tab under Monitored Posts, and through GET /posts (linkedin_list_monitored_posts). DELETE /posts/{id} stops watching a post and keeps the leads it already produced.

You can also add any LinkedIn post by hand with POST /posts (linkedin_create_monitored_post), passing the post’s own link (it contains activity followed by a number) and the agent_id. The post is queued for scraping right away on the agent’s LinkedIn account, and POST /posts/{id}/scrape (linkedin_scrape_monitored_post) queues it again later. The scrape runs within that account’s active hours and daily pacing, so outside them it starts when the account’s day opens. People who engaged with a post that is not yours count as content search leads, so they follow the Content Search lead source setting. An agent without a connected LinkedIn account cannot scrape: the post is saved and POST /posts/{id}/scrape answers with an error until you connect one.

Competitors

POST /competitors/discover (linkedin_discover_competitors) suggests companies that compete with a product you describe (productName, productDescription, optional websiteUrl) and finds their LinkedIn pages. POST /competitors/save, GET /competitors and DELETE /competitors/{id} keep your own list of them. The list is stored for you only; agents, the ICP and lead sources do not use it.

A few calls still do their work inside the request and answer when it is finished. They can take longer than a typical client timeout, so give them up to two minutes:

  • POST /agents/simulate and /agents/simulate/personas (several AI calls, up to 90 seconds)
  • POST /onboarding/analyze-website and POST /competitors/discover (a site fetch plus AI)
  • POST /leads/customers/import and POST /icp/{id}/customers/import with a large CSV
  • POST /leads/{id}/connect and accepting an invitation (one live LinkedIn action, usually 5 to 15 seconds)
  • POST /icp/{id}/filters/chat and POST /conversations/{id}/suggest-replies (one AI call)

Troubleshooting

  • 401 on every call. The key is missing, invalid or revoked. Create a new one in Settings → API.
  • 402 with subscription_required. The workspace has no active plan or trial. Reading your leads, conversations and settings still works, but starting an agent and anything that reaches LinkedIn is refused until you choose a plan in Settings → Billing.
  • 401 with api_access_disabled. You are in a client workspace and API access is switched off for it, or the workspace is paused. Ask the agency that runs your workspace to switch it back on; your keys work again within a minute.
  • 403 although the key is accepted. The key’s workspace is not allowed to make that call.

Champions Circle members using a DM Champ key and getting 403: sign in to SDRPilot with that DM Champ account first so the workspace is linked.

  • A rule matches nothing. Country codes must be two letters uppercase (NL, not Netherlands or nl), and language codes lowercase.
  • The assistant shows no tools. Reconnect it so it reloads the tool list, and check the API key has not been revoked.