Needle LogoNeedle

Documentation

Needle

Needle helps agents search people and places, build lead lists, run multi-channel campaigns on LinkedIn and Instagram, keep suppressions, preview messages, and send from connected accounts.

Needle helps agents search people and places, build lead lists, run multi-channel campaigns on LinkedIn and Instagram, keep suppressions, preview messages, and send from connected accounts.

The same outbound engine is available as a REST API and as MCP tools. One API key unlocks both. Listing MCP tools does not require a key; calling tools and REST endpoints does.

Get started

No install. Get an API key, then pick a path.

This skill is the routing layer. After you know the path, use the API Reference or MCP catalog for schemas.

Get credentials

Needle users create an API key in the dashboard:

If they do not have an account yet, send them to Path D.

Sending, following, and inviting require a connected LinkedIn or Instagram account. Connecting an account is dashboard-only at /accounts. The API and MCP can list, update, and delete connected accounts; they cannot start the OAuth connect flow.

Already have NEEDLE_API_KEY? Skip credential setup. Pick a path below.

Choose your path

All paths use the same API key. The difference is what you do next.

  • Need outbound during this session → Path A (MCP tools)
  • Need to add Needle to app code → Path B (REST in the product)
  • Need a finished outbound workflow → Path C (source, campaign, or one-off send)
  • Need more than one of the above → do them in sequence; one key covers everything
  • Need an account or API key → Path D
  • Do not want to connect MCP → Path E (REST directly)
PathQuestion it answersWhere the work runs
AWhich Needle tool should I call right now?In the agent session, over MCP
BHow do I add a Needle API call to this codebase?Inside the user's product code
CWhat is the finished outbound workflow?In the agent session, producing a result
DHow does the human get a key?Dashboard
EHow do I call Needle over HTTP?REST at /api/v1

Path A: Live MCP tools

Use this when you need outbound during your work: searching people, building leads, running campaigns, sending LinkedIn or Instagram messages, or checking suppressions.

Connect at https://needle.app/mcp/v1 with Authorization: Bearer sk-ndl-…. Listing tools at https://needle.app/mcp/v1/tools does not require a key; calling them does.

{
  "mcpServers": {
    "needle": {
      "url": "https://needle.app/mcp/v1",
      "headers": {
        "Authorization": "Bearer sk-ndl-…"
      }
    }
  }
}

Works with Claude Code, Cowork, Codex, Cursor, Hermes, or any MCP client.

Route by job:

  • Who am I bound to? → needleGetMe
  • What can I send from? → needleListConnectedAccounts
  • Find people → needleSearchLinkedinPeople, then needleGetLinkedinProfile
  • Find companies and jobs → needleSearchLinkedinCompanies, needleGetLinkedinCompany, needleListLinkedinCompanyJobs, or needleSearchLinkedinJobs (searches all of LinkedIn unless you pass companies; resolve location, industry and title ids with needleListLinkedinSearchParameters)
  • Read LinkedIn posts → needleSearchLinkedinPosts, needleListLinkedinPosts, needleGetLinkedinPost, needleListLinkedinPostComments
  • Engage on a post → needleCommentOnLinkedinPost or needleReactToLinkedinPost
  • Read the LinkedIn inbox → needleListLinkedinConversations, then needleListLinkedinConversationMessages
  • Answer inbound requests → needleListLinkedinReceivedInvitations, then needleRespondToLinkedinInvitation
  • Find locations → needleSearchPlaces, then needleGetPlace
  • Build a list → needleCreateLead / needleCreateLeads / needleListLeads
  • Do not contact → needleCheckSuppressions / needleCreateSuppressions
  • Preview copy → needleComposePreview before any send
  • One-off LinkedIn → needleSendLinkedinInvitation, needleSendLinkedinMessage, or needleSendLinkedinInMail
  • One-off Instagram → needleFollowInstagramUser or needleSendInstagramMessage
  • Campaign → needleCreateCampaign, needleEnrollCampaignLeads, needleListPendingApprovals, needleApprovePendingTask

Default flow for live outbound:

  1. needleGetMe to confirm the user and organization.
  2. needleListConnectedAccounts before any send. If none are connected, send the human to /accounts.
  3. Search people or places, then create leads.
  4. needleCheckSuppressions before outreach.
  5. needleComposePreview when the message is generated.
  6. Enroll in a campaign, or send a one-off invitation/message.
  7. Watch needleGetCampaignStats / needleSearchEvents after a campaign is live.

If the task becomes "wire Needle into product code," switch to Path B.

MCP tools

Me

Connected accounts

Leads

Campaigns

Events

LinkedIn

Instagram

Places

Compose

Suppressions

Path B: Integrate Needle into an app

Use this when you are building an application, agent, or workflow that calls Needle from code, meaning the integration will run inside the user's product rather than from this session's MCP client.

This is the key difference from Path A: Path A calls MCP tools during the current session. Path B writes code that keeps running after the agent stops, using NEEDLE_API_KEY from the project's .env or runtime config.

NEEDLE_API_KEY=sk-ndl-…

Base URL: https://needle.app/api/v1

Auth header: Authorization: Bearer sk-ndl-…

Smoke-test with GET /api/v1/me before writing feature code:

curl https://needle.app/api/v1/me \
  -H "Authorization: Bearer sk-ndl-…" \
  -H "Content-Type: application/json"

Route the feature the same way as Path A, then call the matching REST endpoint from Path E. Sends still need a connected account in the organization that owns the key.

If you do not have a key yet, do Path D first.

Path C: Repeatable outbound workflows

Use this when the goal is a finished outbound result (a lead list, a live campaign, a one-off send, or a suppression pass), not raw tool output and not product-code integration.

Source a list

  1. needleSearchLinkedinPeople (keywords or a LinkedIn / Sales Navigator searchUrl; api: "classic" when the account has no Sales Navigator seat) or needleSearchPlaces. For companies, posts and job listings, use needleSearchLinkedinCompanies, needleSearchLinkedinPosts, needleGetLinkedinCompany / needleListLinkedinCompanyJobs.
  2. needleGetLinkedinProfile / needleGetPlace when you need details.
  3. needleCreateLeads for the whole list at once, or needleCreateLead per person. Keep the lead ids that come back: enrolling needs them. LinkedIn identity accepts john-doe, /in/john-doe, https://www.linkedin.com/in/john-doe, or a user id (ACoAAA…). Instagram accepts john-doe, @john-doe, or https://www.instagram.com/john-doe.
  4. needleCheckSuppressions and drop anyone you should not contact.

Run a campaign

  1. Confirm at least one connected account (needleListConnectedAccounts).
  2. needleCreateCampaign with the sequence graph, schedule, limits, and the connected accounts to send from.
  3. needleEnrollCampaignLeads with the lead ids from the list you sourced.
  4. needleListPendingApprovals and needleApprovePendingTask when a send is waiting.
  5. needleGetCampaignStats and needleSearchEvents to see what happened.

One-off outreach

  1. Get the profile.
  2. needleComposePreview for the message.
  3. LinkedIn: needleSendLinkedinInvitation, needleSendLinkedinMessage, or needleSendLinkedinInMail (check credits with needleGetLinkedinInMailBalance).
  4. Instagram: needleFollowInstagramUser or needleSendInstagramMessage.

Keep people off the list

needleCreateSuppressions for people or companies that should not be contacted. Campaigns honor the suppression policy you set on create/update.

If the request shifts to "wire Needle into product code," switch to Path B. If you only need a single tool call, stay on Path A.

Path D: Account or API key

Use this when the human still needs to sign up, sign in, or create a key.

  1. If they have no account, open https://needle.app/login and sign up.
  2. Create a key at https://needle.app/api-keys. Save it as NEEDLE_API_KEY.
  3. To send, connect LinkedIn and/or Instagram at https://needle.app/accounts.
  4. Continue with Path A, B, C, or E.

There is no keyless tier. Listing MCP tools at /mcp/v1/tools is public; every other call needs a key.

Path E: REST API without MCP

Use this when you do not want to connect an MCP client. This works for both live work in this session and app integrations (Path B).

Base URL: https://needle.app/api/v1

Auth header: Authorization: Bearer sk-ndl-…

curl https://needle.app/api/v1/me \
  -H "Authorization: Bearer sk-ndl-…" \
  -H "Content-Type: application/json"

Successful requests return 2xx. 401 means a missing or invalid key. 422 means an invalid payload.

REST endpoints

Me

Connected accounts

Leads

Campaigns

Events

LinkedIn

Instagram

Places

Compose

Suppressions

References

Search docs

Search documentation, API reference, and MCP tools

We use cookies to enhance your experience on Needle and keep your data secure. Privacy Policy