# Needle MCP server

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

## Contents

- Me
  - [Get the authenticated user](/docs/mcp/needle-get-me)
- Connected accounts
  - [List connected accounts](/docs/mcp/needle-list-connected-accounts)
  - [Search connected accounts](/docs/mcp/needle-search-connected-accounts)
  - [Get a connected account](/docs/mcp/needle-get-connected-account)
  - [Update a connected account](/docs/mcp/needle-update-connected-account)
  - [Delete a connected account](/docs/mcp/needle-delete-connected-account)
  - [List connected account limits](/docs/mcp/needle-list-connected-account-limits)
  - [Override a connected account limit](/docs/mcp/needle-update-connected-account-limit)
  - [Reset a connected account limit](/docs/mcp/needle-reset-connected-account-limit)
  - [List connected account events](/docs/mcp/needle-list-connected-account-events)
  - [List connected account tasks](/docs/mcp/needle-list-connected-account-tasks)
- Leads
  - [List leads](/docs/mcp/needle-list-leads)
  - [List lead properties](/docs/mcp/needle-list-lead-properties)
  - [Update a lead property](/docs/mcp/needle-update-lead-property)
  - [Search leads](/docs/mcp/needle-search-leads)
  - [Create a lead](/docs/mcp/needle-create-lead)
  - [Create or update a lead](/docs/mcp/needle-upsert-lead)
  - [Create leads in bulk](/docs/mcp/needle-create-leads)
  - [Get a lead](/docs/mcp/needle-get-lead)
  - [Update a lead](/docs/mcp/needle-update-lead)
  - [Update leads in bulk](/docs/mcp/needle-update-leads)
  - [Delete a lead](/docs/mcp/needle-delete-lead)
  - [Delete leads in bulk](/docs/mcp/needle-delete-leads)
  - [List lead events](/docs/mcp/needle-list-lead-events)
  - [List lead tasks](/docs/mcp/needle-list-lead-tasks)
- Campaigns
  - [List campaigns](/docs/mcp/needle-list-campaigns)
  - [Search campaigns](/docs/mcp/needle-search-campaigns)
  - [Search enrollments](/docs/mcp/needle-search-enrollments)
  - [Create a campaign](/docs/mcp/needle-create-campaign)
  - [Get a campaign](/docs/mcp/needle-get-campaign)
  - [Update a campaign](/docs/mcp/needle-update-campaign)
  - [Archive a campaign](/docs/mcp/needle-archive-campaign)
  - [Get campaign stats](/docs/mcp/needle-get-campaign-stats)
  - [List campaign events](/docs/mcp/needle-list-campaign-events)
  - [List campaign tasks](/docs/mcp/needle-list-campaign-tasks)
  - [Preview a step message](/docs/mcp/needle-get-message-preview-for-step)
  - [Preview a task message](/docs/mcp/needle-get-message-preview-for-task)
  - [List campaign leads](/docs/mcp/needle-list-campaign-leads)
  - [Enroll leads](/docs/mcp/needle-enroll-campaign-leads)
  - [Stop a lead in a campaign](/docs/mcp/needle-remove-campaign-lead)
  - [Stop leads in a campaign in bulk](/docs/mcp/needle-stop-campaign-leads)
- Drafts
  - [List drafts](/docs/mcp/needle-list-drafts)
  - [Create a draft](/docs/mcp/needle-create-draft)
  - [Get a draft](/docs/mcp/needle-get-draft)
  - [Withdraw a draft](/docs/mcp/needle-withdraw-draft)
- Events
  - [Search events](/docs/mcp/needle-search-events)
- LinkedIn
  - [Get a LinkedIn profile](/docs/mcp/needle-get-linkedin-profile)
  - [Search LinkedIn people](/docs/mcp/needle-search-linkedin-people)
  - [Search LinkedIn people (Classic)](/docs/mcp/needle-search-linkedin-people-classic)
  - [Search LinkedIn people (Sales Navigator)](/docs/mcp/needle-search-linkedin-people-sales-navigator)
  - [Send a LinkedIn message](/docs/mcp/needle-send-linkedin-message)
  - [Send a Sales Navigator InMail](/docs/mcp/needle-send-linkedin-in-mail)
  - [Get remaining InMail credits](/docs/mcp/needle-get-linkedin-in-mail-balance)
  - [List conversations](/docs/mcp/needle-list-linkedin-conversations)
  - [List messages in a conversation](/docs/mcp/needle-list-linkedin-conversation-messages)
  - [List pending invitations](/docs/mcp/needle-list-linkedin-invitations)
  - [Send a connection invitation](/docs/mcp/needle-send-linkedin-invitation)
  - [Withdraw an invitation](/docs/mcp/needle-withdraw-linkedin-invitation)
  - [List invitations sent to you](/docs/mcp/needle-list-linkedin-received-invitations)
  - [Accept or decline a received invitation](/docs/mcp/needle-respond-to-linkedin-invitation)
  - [List followers](/docs/mcp/needle-list-linkedin-followers)
  - [List accounts this account follows](/docs/mcp/needle-list-linkedin-following)
  - [List first-degree connections](/docs/mcp/needle-list-linkedin-relations)
  - [Get a LinkedIn company](/docs/mcp/needle-get-linkedin-company)
  - [List jobs posted by a company](/docs/mcp/needle-list-linkedin-company-jobs)
  - [List posts from a company page](/docs/mcp/needle-list-linkedin-company-posts)
  - [Search LinkedIn jobs](/docs/mcp/needle-search-linkedin-jobs)
  - [Get a LinkedIn job](/docs/mcp/needle-get-linkedin-job)
  - [Search LinkedIn companies (Classic)](/docs/mcp/needle-search-linkedin-companies-classic)
  - [Search LinkedIn posts](/docs/mcp/needle-search-linkedin-posts)
  - [List posts by a person or company](/docs/mcp/needle-list-linkedin-posts)
  - [Get a LinkedIn post](/docs/mcp/needle-get-linkedin-post)
  - [List comments on a post](/docs/mcp/needle-list-linkedin-post-comments)
  - [List reactions on a post](/docs/mcp/needle-list-linkedin-post-reactions)
  - [Comment on a post](/docs/mcp/needle-comment-on-linkedin-post)
  - [React to a post](/docs/mcp/needle-react-to-linkedin-post)
  - [List LinkedIn search parameters](/docs/mcp/needle-list-linkedin-search-parameters)
- Instagram
  - [Get an Instagram profile](/docs/mcp/needle-get-instagram-profile)
  - [Get the connected account profile](/docs/mcp/needle-get-instagram-account-profile)
  - [Send an Instagram message](/docs/mcp/needle-send-instagram-message)
  - [React to an Instagram message](/docs/mcp/needle-react-to-instagram-message)
  - [List Instagram conversations](/docs/mcp/needle-list-instagram-conversations)
  - [List messages in a conversation](/docs/mcp/needle-list-instagram-conversation-messages)
  - [List the participants of a conversation](/docs/mcp/needle-list-instagram-conversation-participants)
  - [List the posts of an account](/docs/mcp/needle-list-instagram-posts)
  - [Get an Instagram post](/docs/mcp/needle-get-instagram-post)
  - [Publish an Instagram post](/docs/mcp/needle-create-instagram-post)
  - [List the comments on a post](/docs/mcp/needle-list-instagram-post-comments)
  - [Comment on a post](/docs/mcp/needle-comment-on-instagram-post)
  - [List the likes on a post](/docs/mcp/needle-list-instagram-post-reactions)
  - [Like a post](/docs/mcp/needle-like-instagram-post)
  - [List followers](/docs/mcp/needle-list-instagram-followers)
  - [List followed accounts](/docs/mcp/needle-list-instagram-following)
  - [Follow an Instagram user](/docs/mcp/needle-follow-instagram-user)
  - [Unfollow an Instagram user](/docs/mcp/needle-unfollow-instagram-user)
- Places
  - [Search places](/docs/mcp/needle-search-places)
  - [Get a place](/docs/mcp/needle-get-place)
- Compose
  - [Preview an AI-composed message](/docs/mcp/needle-compose-preview)
- Files
  - [List files](/docs/mcp/needle-list-files)
  - [Create a file preview URL](/docs/mcp/needle-create-file-access-url)
  - [Delete a file](/docs/mcp/needle-delete-file)
  - [Create a file upload](/docs/mcp/needle-create-file-upload)
- Suppressions
  - [List suppressions](/docs/mcp/needle-list-suppressions)
  - [Search suppressions](/docs/mcp/needle-search-suppressions)
  - [Create suppressions](/docs/mcp/needle-create-suppressions)
  - [Check people and companies against the suppression list](/docs/mcp/needle-check-suppressions)
  - [Delete a suppression](/docs/mcp/needle-delete-suppression)
- Webhooks
  - [List webhooks](/docs/mcp/needle-list-webhooks)
  - [Create a webhook](/docs/mcp/needle-create-webhook)
  - [Get a webhook](/docs/mcp/needle-get-webhook)
  - [Update a webhook](/docs/mcp/needle-update-webhook)
  - [Delete a webhook](/docs/mcp/needle-delete-webhook)
- Onboarding
  - [Get onboarding info](/docs/mcp/needle-get-onboarding-info)
- Assistant chats
  - [Get an assistant chat](/docs/mcp/needle-get-assistant-chat)
- Docs
  - [Search the Needle docs](/docs/mcp/needle-search-docs)
  - [Read the Needle docs](/docs/mcp/needle-read-docs)

## Me

### needleGetMe

**Get the authenticated user**

Returns the user and the workspace (`organization`) this caller is bound to.

**Input**

object

## Connected accounts

### needleListConnectedAccounts

**List connected accounts**

List a page of connected LinkedIn and Instagram accounts. Use nextCursor as cursor for the next page.

**Input**

- `cursor` (string, optional)
- `limit` (integer, optional)

### needleSearchConnectedAccounts

**Search connected accounts**

Find connected accounts by display name, handle, or username. Every word in query must match; names or handles starting with it come first. Pass nextCursor as cursor, with the same query, for more. Use the returned id with needleGetConnectedAccount.

**Input**

- `query` (string, required): Text to match. Every word must appear in the record.
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleGetConnectedAccount

**Get a connected account**

Get a connected account and its usage.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account id

### needleUpdateConnectedAccount

**Update a connected account**

Update a connected account.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account id
- `paused` (boolean, optional)
- `limitOverrides` (object | null, optional): Per-action caps for this account. Keys merge with existing overrides: set a key to null to restore the channel default for that action, or set the whole field to null to clear every override.

### needleDeleteConnectedAccount

**Delete a connected account**

Delete a connected account. Its owner or a workspace admin can delete it.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account id

### needleListConnectedAccountLimits

**List connected account limits**

Every metered action on a connected account with its channel defaults, the caps currently enforced, the override behind them (if any), and usage so far. Use this to explain a 429 or before changing a cap.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account id

### needleUpdateConnectedAccountLimit

**Override a connected account limit**

Set hourly, daily, or weekly caps for one action on a connected account. Fields left out keep the channel default. Caps can be tightened or loosened but not removed. Going above the default is applied but returns a warning, since it raises the risk of the channel restricting the account; relay it to the user.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account id
- `action` ("linkedin_invitation" | "linkedin_cancel_invitation" | "linkedin_message" | "linkedin_sales_navigator_message" | "linkedin_inmail" | "linkedin_profile_view" | "linkedin_search" | "linkedin_comment" | "linkedin_reaction" | "linkedin_post_view" | "linkedin_company_view" | "linkedin_job_view" | "linkedin_conversation_view" | "linkedin_network_view" | "linkedin_invitation_list" | "linkedin_invitation_response" | "linkedin_search_parameter" | "linkedin_inmail_balance" | "linkedin_own_profile" | "instagram_message" | "instagram_profile_view" | "instagram_follow" | "instagram_unfollow" | "instagram_comment" | "instagram_reaction" | "instagram_post" | "instagram_post_view" | "instagram_conversation_view" | "instagram_network_view" | "instagram_own_profile", required): Metered action, e.g. linkedin_profile_view.
- `hour` (integer, optional): Hourly cap.
- `day` (integer, optional): Daily cap.
- `week` (integer, optional): Weekly cap.

### needleResetConnectedAccountLimit

**Reset a connected account limit**

Remove the override for one action so the connected account runs on the channel defaults again.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account id
- `action` ("linkedin_invitation" | "linkedin_cancel_invitation" | "linkedin_message" | "linkedin_sales_navigator_message" | "linkedin_inmail" | "linkedin_profile_view" | "linkedin_search" | "linkedin_comment" | "linkedin_reaction" | "linkedin_post_view" | "linkedin_company_view" | "linkedin_job_view" | "linkedin_conversation_view" | "linkedin_network_view" | "linkedin_invitation_list" | "linkedin_invitation_response" | "linkedin_search_parameter" | "linkedin_inmail_balance" | "linkedin_own_profile" | "instagram_message" | "instagram_profile_view" | "instagram_follow" | "instagram_unfollow" | "instagram_comment" | "instagram_reaction" | "instagram_post" | "instagram_post_view" | "instagram_conversation_view" | "instagram_network_view" | "instagram_own_profile", required): Metered action, e.g. linkedin_profile_view.

### needleListConnectedAccountEvents

**List connected account events**

List a page of events for a connected account. Use nextCursor as cursor for the next page.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account id
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleListConnectedAccountTasks

**List connected account tasks**

List a page of the queue for one connected account, earliest scheduled first. Limits and pacing are per account, so this is the order and rate its work will go out at. Use nextCursor as cursor for the next page.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account id
- `cursor` (string, optional)
- `limit` (integer, optional)
- `status` ("pending" | "pending_approval", optional)

## Leads

### needleListLeads

**List leads**

List a page of leads in this workspace. Use nextCursor as cursor for the next page.

**Input**

- `cursor` (string, optional)
- `limit` (integer, optional)

### needleListLeadProperties

**List lead properties**

List every custom property key leads in this workspace use, with its type, lead count and most common values. Use them as properties.<key> in needleSearchLeads filters.

**Input**

object

### needleUpdateLeadProperty

**Update a lead property**

Change how a custom property is compared when filtering (type: string, number, boolean, date), or whether it shows as a column in the leads table. Stored values are not changed.

**Input**

- `key` (string, required): Property key
- `type` ("string" | "number" | "boolean" | "date", optional): How values are compared when filtering. Values are always stored as text; the type is guessed from the first value seen and can be changed.
- `showAsColumn` (boolean, optional): Show this property as a column in the leads table.

### needleSearchLeads

**Search leads**

Find leads already in this workspace. With a query, best matches come first (name, then email starting with it); without one, newest first. Every word in query must appear in the name, email, company, title, or a handle. Filter built-in fields (jobTitle, companyDomain, createdAt…) or custom properties as properties.<key>; call needleListLeadProperties first for the keys, types and common values. Pass nextCursor as cursor, with the same query and filters, for the next page.

**Input**

- `query` (string, optional): Free text. Every word must appear in the name, email, company, company domain, job title, or a profile handle. Combined with filters.
- `filters` (object[], optional): Every filter must match.
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleCreateLead

**Create a lead**

Create a lead. Fails when an identity already belongs to a lead (the error data has that leadId); use needleUpsertLead to create-or-update. 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.

**Input**

- `identities` (object, required)
  - `linkedin` (string, optional): Public identifier (john-doe), /in/ path (/in/john-doe or in/john-doe), profile URL (https://www.linkedin.com/in/john-doe), or user id (ACoAAA…). Stored as the identifier, not the URL.
  - `instagram` (string, optional): Username (john-doe), handle (@john-doe), or profile URL (https://www.instagram.com/john-doe). Stored as the username without @.
- `timezone` (string, required)
- `firstName` (string, optional)
- `lastName` (string, optional)
- `companyName` (string, optional)
- `companyDomain` (string, optional)
- `jobTitle` (string, optional)
- `email` (string, optional)
- `imageUrl` (string, optional)
- `properties` (object, optional)

### needleUpsertLead

**Create or update a lead**

Create a lead, or when a LinkedIn or Instagram identity already belongs to one, patch the fields sent onto it. Returns created or matched with the lead. Same identity formats as needleCreateLead.

**Input**

- `identities` (object, required)
  - `linkedin` (string, optional): Public identifier (john-doe), /in/ path (/in/john-doe or in/john-doe), profile URL (https://www.linkedin.com/in/john-doe), or user id (ACoAAA…). Stored as the identifier, not the URL.
  - `instagram` (string, optional): Username (john-doe), handle (@john-doe), or profile URL (https://www.instagram.com/john-doe). Stored as the username without @.
- `timezone` (string, required)
- `firstName` (string, optional)
- `lastName` (string, optional)
- `companyName` (string, optional)
- `companyDomain` (string, optional)
- `jobTitle` (string, optional)
- `email` (string, optional)
- `imageUrl` (string, optional)
- `properties` (object, optional)

### needleCreateLeads

**Create leads in bulk**

Create up to 500 leads at once, matching on identity so re-sending a list does not duplicate anyone. Returns created, matched, or skipped per row, in request order, with the lead id to enroll. Same identity formats as needleCreateLead.

**Input**

- `leads` (object[], required)

### needleGetLead

**Get a lead**

Get a lead, its identities, and enrollments.

**Input**

- `leadId` (string · uuid, required): Lead id

### needleUpdateLead

**Update a lead**

Update a lead profile or identities.

**Input**

- `leadId` (string · uuid, required): Lead id
- `identities` (object, optional)
  - `linkedin` (string, optional): Public identifier (john-doe), /in/ path (/in/john-doe or in/john-doe), profile URL (https://www.linkedin.com/in/john-doe), or user id (ACoAAA…). Stored as the identifier, not the URL.
  - `instagram` (string, optional): Username (john-doe), handle (@john-doe), or profile URL (https://www.instagram.com/john-doe). Stored as the username without @.
- `timezone` (string, optional)
- `firstName` (string, optional)
- `lastName` (string, optional)
- `companyName` (string, optional)
- `companyDomain` (string, optional)
- `jobTitle` (string, optional)
- `email` (string, optional)
- `imageUrl` (string, optional)
- `properties` (object, optional)

### needleUpdateLeads

**Update leads in bulk**

Update up to 500 existing leads by id; never creates leads. Each row takes leadId plus the fields to change, same as needleUpdateLead. Returns updated or skipped per row in request order; skipped rows say why (lead_not_found, invalid_identity, or identity_taken with the conflictingLeadId).

**Input**

- `leads` (object[], required)

### needleDeleteLead

**Delete a lead**

Delete a lead.

**Input**

- `leadId` (string · uuid, required): Lead id

### needleDeleteLeads

**Delete leads in bulk**

Delete up to 500 leads by id, stopping their live campaign enrollments. Returns deleted or skipped (lead_not_found) per id in request order; retrying is safe.

**Input**

- `leadIds` (string · uuid[], required): The leads to delete.

### needleListLeadEvents

**List lead events**

List a page of events for a lead. Use nextCursor as cursor for the next page.

**Input**

- `leadId` (string · uuid, required): Lead id
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleListLeadTasks

**List lead tasks**

List a page of the actions campaigns owe a lead, earliest scheduled first. Use nextCursor as cursor for the next page.

**Input**

- `leadId` (string · uuid, required): Lead id
- `cursor` (string, optional)
- `limit` (integer, optional)
- `status` ("pending" | "pending_approval", optional)

## Campaigns

### needleListCampaigns

**List campaigns**

List a page of campaigns. Filter by status. Use nextCursor as cursor for the next page. Results leave out the step graph; use needleGetCampaign for it.

**Input**

- `cursor` (string, optional)
- `limit` (integer, optional)
- `status` ("draft" | "active" | "paused" | "archived", optional)

### needleSearchCampaigns

**Search campaigns**

Find campaigns in this workspace by name. Every word in query must match; names starting with it come first. Pass nextCursor as cursor, with the same query, for more. Results leave out the step graph; use the returned id with needleGetCampaign for it.

**Input**

- `query` (string, required): Text to match. Every word must appear in the record.
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleSearchEnrollments

**Search enrollments**

Find enrollments by the lead or the campaign name. Every word in query must match; lead names starting with it come first. Pass campaignId to search inside one campaign. Pass nextCursor as cursor, with the same query and campaignId, for more. Each enrollment includes campaignId and campaignName.

**Input**

- `query` (string, required): Text to match. Every word must appear in the record.
- `cursor` (string, optional)
- `limit` (integer, optional)
- `campaignId` (string · uuid, optional): Only enrollments in this campaign.

### needleCreateCampaign

**Create a campaign**

Create a campaign.

**Input**

- `name` (string, required)
- `graph` (object, required)
  - `nodes` (object[], required)
  - `edges` (object[], required)
- `schedule` (object, optional)
  - `workingDays` (integer[], optional)
  - `startTime` (string, optional)
  - `endTime` (string, optional)
- `limits` (object, optional)
  - `minGapSeconds` (integer, optional)
  - `maxGapSeconds` (integer, optional)
- `suppressionPolicy` (object, optional)
  - `bypassSuppressionReasons` ("manual" | "unsubscribed" | "not_interested" | "existing_customer" | "open_opportunity" | "competitor" | "employee" | "invalid_recipient" | "complained" | "recently_contacted" | "unresponsive"[], optional)
  - `cooldownDays` (integer, optional)
  - `unresponsiveAfterTouches` (integer, optional)
  - `autoSuppressKeywords` (string[], optional)

### needleGetCampaign

**Get a campaign**

Get a campaign by id.

**Input**

- `campaignId` (string · uuid, required): Campaign id

### needleUpdateCampaign

**Update a campaign**

Update a campaign.

**Input**

- `campaignId` (string · uuid, required): Campaign id
- `name` (string, optional)
- `status` ("active" | "paused", optional)
- `graph` (object, optional)
  - `nodes` (object[], required)
  - `edges` (object[], required)
- `schedule` (object, optional)
  - `workingDays` (integer[], optional)
  - `startTime` (string, optional)
  - `endTime` (string, optional)
- `limits` (object, optional)
  - `minGapSeconds` (integer, optional)
  - `maxGapSeconds` (integer, optional)
- `suppressionPolicy` (object, optional)
  - `bypassSuppressionReasons` ("manual" | "unsubscribed" | "not_interested" | "existing_customer" | "open_opportunity" | "competitor" | "employee" | "invalid_recipient" | "complained" | "recently_contacted" | "unresponsive"[], optional)
  - `cooldownDays` (integer, optional)
  - `unresponsiveAfterTouches` (integer, optional)
  - `autoSuppressKeywords` (string[], optional)

### needleArchiveCampaign

**Archive a campaign**

Archive a campaign.

**Input**

- `campaignId` (string · uuid, required): Campaign id

### needleGetCampaignStats

**Get campaign stats**

Campaign progress, funnel (distinct leads per stage), enrollments, and steps (including current and completed leads per step) for a campaign.

**Input**

- `campaignId` (string · uuid, required): Campaign id

### needleListCampaignEvents

**List campaign events**

List a page of campaign events. Use nextCursor as cursor for the next page.

**Input**

- `campaignId` (string · uuid, required): Campaign id
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleListCampaignTasks

**List campaign tasks**

List a page of the actions this campaign owes its leads, earliest scheduled first. Use nextCursor as cursor for the next page.

**Input**

- `campaignId` (string · uuid, required): Campaign id
- `cursor` (string, optional)
- `limit` (integer, optional)
- `status` ("pending" | "pending_approval", optional)

### needleGetMessagePreviewForStep

**Preview a step message**

What a campaign step would send to the lead of one of the campaign's enrollments, from the step's account, with subject, sender and attachments. Nothing is sent or saved. AI steps write the message fresh on every call, so check a few enrollments before going live. status unavailable gives the reason, such as a missing lead field. Step ids are the node ids from needleGetCampaign; enrollmentId comes from needleListCampaignLeads.

**Input**

- `campaignId` (string · uuid, required): Campaign id
- `nodeId` (string, required): Step id, the node id in the campaign graph
- `enrollmentId` (string · uuid, required): An enrollment in this campaign; its lead is the one written to. List them with GET /campaigns/{campaignId}/leads.

### needleGetMessagePreviewForTask

**Preview a task message**

What a queued task would send to its lead, from the step's current content and account. Nothing is sent or saved. AI steps write the message fresh on every call. status unavailable gives the reason. Task ids come from needleListCampaignTasks or needleListLeadTasks.

**Input**

- `taskId` (string · uuid, required): Task id

### needleListCampaignLeads

**List campaign leads**

List a page of leads enrolled in a campaign. Use nextCursor as cursor for the next page.

**Input**

- `campaignId` (string · uuid, required): Campaign id
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleEnrollCampaignLeads

**Enroll leads**

Enroll existing leads in a campaign, by lead id. Create the leads first with needleCreateLead or needleCreateLeads. A lead without a handle for every channel the campaign sends on is skipped as missing_identity. Contactability skips are suppressed (do-not-contact list), recently_contacted, or unresponsive — not every skip means the lead is on the list. Returns accepted or skipped per lead id.

**Input**

- `campaignId` (string · uuid, required): Campaign id
- `leadIds` (string · uuid[], required): Leads to enroll, by id. Create them first with POST /api/v1/leads or POST /api/v1/leads/bulk.

### needleRemoveCampaignLead

**Stop a lead in a campaign**

Stop a live lead enrollment in a campaign.

**Input**

- `campaignId` (string · uuid, required): Campaign id
- `leadId` (string · uuid, required): Lead id

### needleStopCampaignLeads

**Stop leads in a campaign in bulk**

Stop the live enrollments of up to 500 leads in a campaign, by lead id. Returns stopped or skipped (not_live: nothing live for that lead in this campaign) per lead id in request order; retrying is safe.

**Input**

- `campaignId` (string · uuid, required): Campaign id
- `leadIds` (string · uuid[], required): Leads to stop, by id.

## Drafts

### needleListDrafts

**List drafts**

List a page of drafted messages, newest first. By default only the ones waiting for a person to review them in the Needle inbox; pass status for sent, failed or discarded ones. Filter by campaignId, leadId or connectedAccountId. Use nextCursor as cursor for the next page.

**Input**

- `cursor` (string, optional)
- `limit` (integer, optional)
- `status` ("awaiting_review" | "sent" | "failed" | "discarded", optional): Defaults to the drafts waiting for review.
- `campaignId` (string · uuid, optional): Only drafts from this campaign
- `leadId` (string · uuid, optional): Only drafts to this lead
- `connectedAccountId` (string · uuid, optional): Only drafts sent from this account

### needleCreateDraft

**Create a draft**

Draft a message, InMail or connection request (text is its note) to a lead from a connected account. Nothing sends until the user approves it in the Needle inbox, where they can also edit or discard it, so use this instead of sending when the user wants to review first. A conversation (account and lead) has one draft waiting at a time: a new one replaces a waiting one created with this tool, but fails while a draft from a campaign step waits. Write the final words: {{variables}} are not filled in.

**Input**

- `connectedAccountId` (string · uuid, required): The account that sends it. Its channel must match `action`.
- `leadId` (string · uuid, required): The lead it goes to.
- `action` ("linkedin_message" | "linkedin_inmail" | "linkedin_invitation" | "instagram_message", required): `linkedin_invitation` sends a connection request with `text` as its note.
- `text` (string, required): Sent exactly as written, so {{variables}} are not allowed. Up to 300 characters for a connection note and 1900 for an InMail.
- `subject` (string, optional): Required for `linkedin_inmail`, not allowed otherwise.
- `messagingChannel` ("linkedin" | "instagram" | "linkedin_sales_navigator", optional): Inbox it is sent from. Omit it for the default: linkedin_message sends from LinkedIn, linkedin_inmail from Sales Navigator. Set "linkedin_sales_navigator" on linkedin_message to send it from Sales Navigator, in its own chat apart from the LinkedIn one; the lead must be a connection, and the account needs Sales Navigator.

### needleGetDraft

**Get a draft**

Get one draft and where it is in review: awaiting_review, sent, failed or discarded.

**Input**

- `draftId` (string · uuid, required): Draft id

### needleWithdrawDraft

**Withdraw a draft**

Take back a draft before anyone reviewed it, so it never sends. Only for drafts created with needleCreateDraft; a draft a campaign step holds goes away when the lead is removed from the campaign.

**Input**

- `draftId` (string · uuid, required): Draft id

## Events

### needleSearchEvents

**Search events**

Search a page of events. Filter by campaign, lead, enrollment, account, type, channel, or date. Use nextCursor as cursor for the next page.

**Input**

- `types` (string[], optional)
- `channel` ("linkedin" | "instagram", optional)
- `campaignId` (string · uuid, optional)
- `leadId` (string · uuid, optional)
- `enrollmentId` (string · uuid, optional): Only events recorded for this campaign enrollment.
- `accountId` (string · uuid, optional)
- `actorUserId` (string · uuid, optional): Only events caused by this member: what they sent, approved or stopped, and what campaigns they started sent.
- `from` (string · date, optional)
- `to` (string · date, optional)
- `cursor` (string, optional)
- `limit` (integer, optional)

## LinkedIn

### needleGetLinkedinProfile

**Get a LinkedIn profile**

Get a LinkedIn profile by user id or public identifier.

**Input**

- `identity` (string, required): User id (ACoAAA…) or public identifier.
- `connectedAccountId` (string · uuid, required): Connected account to act as

### needleSearchLinkedinPeople

**Search LinkedIn people**

Deprecated. Use needleSearchLinkedinPeopleClassic for standard LinkedIn or needleSearchLinkedinPeopleSalesNavigator for Sales Navigator.

**Input**

- `connectedAccountId` (string, optional)
- `keywords` (string, optional)
- `api` (string, optional)
- `searchUrl` (string, optional)
- `cursor` (string, optional)
- `limit` (number, optional)

### needleSearchLinkedinPeopleClassic

**Search LinkedIn people (Classic)**

Search standard LinkedIn people with keywords or filters. Resolve location, industry, company, school, service-category, connections-of, and followers-of ids with needleListLinkedinSearchParameters using service classic. Job titles are keyword-matched here via advancedKeywords.title, not ids.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `keywords` (string, optional)
- `locations` (string[], optional): Location ids from the search parameters endpoint with type=LOCATION.
- `industries` (string[], optional): Industry ids from the search parameters endpoint with type=INDUSTRY.
- `companies` (string[], optional): Current-company ids from the search parameters endpoint with type=COMPANY.
- `pastCompanies` (string[], optional): Past-company ids from the search parameters endpoint with type=COMPANY.
- `schools` (string[], optional): School ids from the search parameters endpoint with type=SCHOOL.
- `serviceCategories` (string[], optional): Service-category ids from the search parameters endpoint with type=SERVICE.
- `connectionsOf` (string[], optional): Member ids from the search parameters endpoint with type=CONNECTIONS. Returns people connected to them.
- `followersOf` (string[], optional): Member ids from the search parameters endpoint with type=PEOPLE. Returns people who follow them.
- `profileLanguages` (string[], optional): ISO 639-1 profile-language codes from the search parameters endpoint with type=LANGUAGE.
- `networkDistances` (number[], optional): LinkedIn connection degrees: first, second, or third-plus.
- `openTo` ("pro_bono" | "board_member"[], optional): LinkedIn only filters on these two, not on open to work or hiring.
- `advancedKeywords` (object, optional): LinkedIn's Keywords panel: each field matches text against that profile field only.
  - `firstName` (string, optional)
  - `lastName` (string, optional)
  - `title` (string, optional)
  - `company` (string, optional)
  - `school` (string, optional)
- `searchUrl` (string · uri, optional): Use a people search URL copied from standard LinkedIn, such as https://www.linkedin.com/search/results/people/?keywords=engineer. The filters it carries replace the filter fields, which must then be left out. Sales Navigator URLs go to POST /api/v1/linkedin/sales-navigator/people/search.
- `cursor` (string, optional)
- `limit` (integer, optional): Requested page size, capped at 10 by LinkedIn Classic.

### needleSearchLinkedinPeopleSalesNavigator

**Search LinkedIn people (Sales Navigator)**

Search Sales Navigator leads with keywords or filters, including current and past company, company headcount and type, function, seniority, years of experience, groups, saved lists and personas, and Spotlights such as changed_jobs. Most filters also take an excluded form. Resolve filter ids with needleListLinkedinSearchParameters using service sales_navigator. Requires a Sales Navigator seat.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `keywords` (string, optional)
- `firstName` (string, optional): Matches the first name on the profile.
- `lastName` (string, optional): Matches the last name on the profile.
- `locations` (string[], optional): Geography ids from the search parameters endpoint with type=REGION and service=sales_navigator.
- `excludedLocations` (string[], optional): Geographies to leave out of the results.
- `industries` (string[], optional): Industry ids from the search parameters endpoint with type=SALES_INDUSTRY and service=sales_navigator.
- `excludedIndustries` (string[], optional): Industries to leave out of the results.
- `companies` (string[], optional): Current-company ids from the search parameters endpoint with type=COMPANY and service=sales_navigator.
- `excludedCompanies` (string[], optional): Current companies to leave out of the results.
- `pastCompanies` (string[], optional): Past-company ids from the search parameters endpoint with type=COMPANY and service=sales_navigator.
- `excludedPastCompanies` (string[], optional): Past companies to leave out of the results.
- `companyLocations` (string[], optional): Where the company sits, rather than where the person does. Geography ids with type=REGION and service=sales_navigator.
- `excludedCompanyLocations` (string[], optional): Company geographies to leave out of the results.
- `companyHeadcounts` ("1_to_10" | "11_to_50" | "51_to_200" | "201_to_500" | "501_to_1000" | "1001_to_5000" | "5001_to_10000" | "10001_plus"[], optional): Employee-count bands of the current company.
- `companyTypes` ("public_company" | "privately_held" | "non_profit" | "educational_institution" | "partnership" | "self_employed" | "self_owned" | "government_agency"[], optional): How the current company is held.
- `schools` (string[], optional): School ids from the search parameters endpoint with type=SCHOOL and service=sales_navigator.
- `excludedSchools` (string[], optional): Schools to leave out of the results.
- `functions` (string[], optional): The department someone works in. Function ids from the search parameters endpoint with type=DEPARTMENT and service=sales_navigator.
- `excludedFunctions` (string[], optional): Functions to leave out of the results.
- `jobTitles` (string[], optional): Current job-title ids from the search parameters endpoint with type=JOB_TITLE and service=sales_navigator.
- `excludedJobTitles` (string[], optional): Current job titles to leave out of the results.
- `pastJobTitles` (string[], optional): Job titles someone used to hold. Ids with type=JOB_TITLE and service=sales_navigator.
- `excludedPastJobTitles` (string[], optional): Past job titles to leave out of the results.
- `seniorities` ("owner_partner" | "cxo" | "vice_president" | "director" | "experienced_manager" | "entry_level_manager" | "strategic" | "senior" | "entry_level" | "in_training"[], optional): Seniority levels to search, from owner_partner down to in_training.
- `excludedSeniorities` ("owner_partner" | "cxo" | "vice_president" | "director" | "experienced_manager" | "entry_level_manager" | "strategic" | "senior" | "entry_level" | "in_training"[], optional): Seniority levels to leave out of the results.
- `yearsOfExperience` ("less_than_1" | "1_to_2" | "3_to_5" | "6_to_10" | "more_than_10"[], optional): Years of experience across someone's whole career.
- `yearsAtCompany` ("less_than_1" | "1_to_2" | "3_to_5" | "6_to_10" | "more_than_10"[], optional): Years spent at the current company.
- `yearsInPosition` ("less_than_1" | "1_to_2" | "3_to_5" | "6_to_10" | "more_than_10"[], optional): Years spent in the current position.
- `groups` (string[], optional): LinkedIn groups the person belongs to. Group ids with type=GROUPS and service=sales_navigator.
- `personas` (string[], optional): Personas saved on the Sales Navigator seat. Ids with type=PERSONA and service=sales_navigator.
- `accountLists` (string[], optional): Only people at companies on these saved account lists. Ids with type=ACCOUNT_LISTS and service=sales_navigator.
- `excludedAccountLists` (string[], optional): Saved account lists to leave out of the results.
- `leadLists` (string[], optional): Only people on these saved lead lists. Ids with type=LEAD_LISTS and service=sales_navigator.
- `excludedLeadLists` (string[], optional): Saved lead lists to leave out of the results.
- `connectionsOf` (string[], optional): Member ids from the search parameters endpoint with type=CONNECTIONS. Returns people connected to them.
- `profileLanguages` (string[], optional): ISO 639-1 profile-language codes from the search parameters endpoint with type=LANGUAGE.
- `networkDistances` (number[], optional): LinkedIn connection degrees: first, second, or third-plus.
- `spotlights` ("changed_jobs" | "posted_on_linkedin" | "mentioned_in_news" | "following_your_company" | "viewed_your_profile_recently" | "past_colleague" | "shared_experiences"[], optional): Sales Navigator's Spotlights: recent signals about the person rather than facts about their profile.
- `interactedWith` ("messaged" | "viewed_profile"[], optional): Only people this seat has messaged, or whose profile it opened.
- `includeSaved` ("leads" | "accounts"[], optional): Also return people already saved as leads, or at saved accounts.
- `searchUrl` (string · uri, optional): Use a lead search URL copied from Sales Navigator, such as https://www.linkedin.com/sales/search/people?query=.... The filters it carries replace the filter fields, which must then be left out. Standard LinkedIn URLs go to POST /api/v1/linkedin/people/search.
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleSendLinkedinMessage

**Send a LinkedIn message**

Send a LinkedIn message as a connected account. Attach files by passing a url from needleListFiles or from creating a file first.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `identity` (string, required): User id (ACoAAA…) or public identifier.
- `text` (string, required)
- `attachments` (object[], optional): Files from POST /api/v1/files. Pass the returned url, not a signed URL. Needle reads the private object and sends the bytes to LinkedIn.
- `messagingChannel` ("linkedin" | "linkedin_sales_navigator", optional): Inbox it is sent from. Defaults to "linkedin". Set "linkedin_sales_navigator" to send from Sales Navigator, in the lead's chat there, apart from the LinkedIn one; the lead must be a connection, and the account needs Sales Navigator. It counts against the linkedin_sales_navigator_message limits, and remainingUsage reports those.

### needleSendLinkedinInMail

**Send a Sales Navigator InMail**

Send a LinkedIn InMail. Needs a Sales Navigator seat. Reaches people in your network and out-of-network Open Profiles. Usually costs one credit. Attach files by passing a url from needleListFiles or from creating a file first.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `identity` (string, required): User id (ACoAAA…) or public identifier.
- `subject` (string, required): InMail subject line shown to the recipient.
- `text` (string, required)
- `attachments` (object[], optional): Files from POST /api/v1/files. Pass the returned url, not a signed URL. Needle reads the private object and sends the bytes to LinkedIn.

### needleGetLinkedinInMailBalance

**Get remaining InMail credits**

Read the InMail credits left on a connected account.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as

### needleListLinkedinConversations

**List conversations**

List LinkedIn conversations. Use a conversationId from here to read its messages.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleListLinkedinConversationMessages

**List messages in a conversation**

List messages in a LinkedIn conversation.

**Input**

- `conversationId` (string, required): conversationId from the conversations listing
- `connectedAccountId` (string · uuid, required): Connected account to act as
- `limit` (integer, optional): Page size. Defaults to 20.

### needleListLinkedinInvitations

**List pending invitations**

List a page of pending LinkedIn connection invitations from this account. Use nextCursor as cursor for the next page.

**Input**

- `cursor` (string, optional)
- `limit` (integer, optional)
- `connectedAccountId` (string · uuid, required): Connected account to act as

### needleSendLinkedinInvitation

**Send a connection invitation**

Send a LinkedIn connection invitation.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `identity` (string, required): User id (ACoAAA…) or public identifier.
- `note` (string, optional)

### needleWithdrawLinkedinInvitation

**Withdraw an invitation**

Withdraw a pending LinkedIn invitation.

**Input**

- `invitationId` (string, required): invitationId from the sent invitations listing
- `connectedAccountId` (string · uuid, required): Connected account to act as

### needleListLinkedinReceivedInvitations

**List invitations sent to you**

List connection invitations other people sent to this account. Use nextCursor as cursor for the next page.

**Input**

- `cursor` (string, optional)
- `limit` (integer, optional)
- `connectedAccountId` (string · uuid, required): Connected account to act as

### needleRespondToLinkedinInvitation

**Accept or decline a received invitation**

Accept or decline an invitation from the received invitations listing.

**Input**

- `invitationId` (string, required): invitationId from the received invitations listing
- `connectedAccountId` (string · uuid, required): Connected account to act as
- `action` ("accept" | "decline", required)

### needleListLinkedinFollowers

**List followers**

List followers of the connected account, or of a person or company when identity is given.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `identity` (string, optional): Whose followers to read: a person (user id or public identifier) or a company (public identifier, numeric id, or company URL). Omit for the connected account; a company page is readable only by its admins.
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleListLinkedinFollowing

**List accounts this account follows**

List the people and companies this account follows.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleListLinkedinRelations

**List first-degree connections**

List first-degree LinkedIn connections. Use the returned cursor for the next page.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `cursor` (string, optional)

### needleGetLinkedinCompany

**Get a LinkedIn company**

Get a LinkedIn company by public identifier, numeric id, or company URL such as https://www.linkedin.com/company/heravideo.

**Input**

- `identifier` (string, required): Company public identifier (heravideo), numeric company id, or a LinkedIn company URL such as https://www.linkedin.com/company/heravideo.
- `connectedAccountId` (string · uuid, required): Connected account to act as

### needleListLinkedinCompanyJobs

**List jobs posted by a company**

List jobs on a LinkedIn company page. Identifier accepts a public identifier, numeric id, or company URL.

**Input**

- `identifier` (string, required): Company public identifier (heravideo), numeric company id, or a LinkedIn company URL such as https://www.linkedin.com/company/heravideo.
- `connectedAccountId` (string · uuid, required): Connected account to act as
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleListLinkedinCompanyPosts

**List posts from a company page**

List posts on a LinkedIn company page. Identifier accepts a public identifier, numeric id, or company URL.

**Input**

- `identifier` (string, required): Company public identifier (heravideo), numeric company id, or a LinkedIn company URL such as https://www.linkedin.com/company/heravideo.
- `connectedAccountId` (string · uuid, required): Connected account to act as
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleSearchLinkedinJobs

**Search LinkedIn jobs**

Search LinkedIn jobs with keywords, a company, or a LinkedIn jobs searchUrl. Do not combine a searchUrl with keywords or company.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `keywords` (string, optional)
- `companies` (string[], optional): Companies to search within. Each non-numeric identifier costs one extra lookup call.
- `location` (string, optional): A single location id from GET /api/v1/linkedin/search/parameters?type=LOCATION. One location per search.
- `industries` (string[], optional): Industry ids from GET /api/v1/linkedin/search/parameters?type=INDUSTRY.
- `jobTitles` (string[], optional): Job title ids from GET /api/v1/linkedin/search/parameters?type=JOB_TITLE.
- `jobFunctions` (string[], optional): Job function ids from GET /api/v1/linkedin/search/parameters?type=JOB_FUNCTION.
- `seniority` ("executive" | "director" | "mid_senior" | "associate" | "entry" | "intern"[], optional)
- `jobType` ("full_time" | "part_time" | "contract" | "temporary" | "volunteer" | "internship" | "other"[], optional)
- `workplace` ("on_site" | "hybrid" | "remote"[], optional)
- `postedWithinDays` (integer, optional)
- `sortBy` ("relevance" | "date", optional): Defaults to relevance.
- `searchUrl` (string · uri, optional): A LinkedIn jobs search URL, which cannot be combined with the filter fields above. Use it for filters this endpoint does not expose, such as salary.
- `cursor` (string, optional)
- `limit` (integer, optional): Page size, capped at 50 for a classic job search. Use cursor for the next page.

### needleGetLinkedinJob

**Get a LinkedIn job**

Get one LinkedIn job with its full description, applicant count, apply link and hiring team. jobId accepts the id from a job listing or search, or a job URL such as https://www.linkedin.com/jobs/view/4447604185. Salary, seniority, skills and screening questions are not returned for jobs posted by other companies; use service recruiter for jobs posted through LinkedIn Recruiter.

**Input**

- `jobId` (string, required): Numeric job id from a job listing or search, or a job URL such as https://www.linkedin.com/jobs/view/4447604185 (URL-encoded when sent in the path).
- `connectedAccountId` (string · uuid, required): Connected account to act as
- `service` ("classic" | "recruiter", optional): recruiter for a job posted through LinkedIn Recruiter, which needs a Recruiter seat on the connected account. Defaults to classic.

### needleSearchLinkedinCompaniesClassic

**Search LinkedIn companies (Classic)**

Search LinkedIn companies. Provide either keywords or a LinkedIn company searchUrl, not both.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `keywords` (string, optional)
- `searchUrl` (string · uri, optional): A search URL copied from LinkedIn, searching for the same kind of entity this endpoint returns. Filters carried in the URL take precedence.
- `cursor` (string, optional)
- `limit` (integer, optional): Page size, capped at 10 for a company keyword search. Use cursor for the next page.

### needleSearchLinkedinPosts

**Search LinkedIn posts**

Search LinkedIn posts. Provide either keywords or a LinkedIn post searchUrl, not both.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `keywords` (string, optional)
- `searchUrl` (string · uri, optional): A search URL copied from LinkedIn, searching for the same kind of entity this endpoint returns. Filters carried in the URL take precedence.
- `cursor` (string, optional)
- `limit` (integer, optional): Page size, capped at 49 for a post keyword search. Use cursor for the next page.

### needleListLinkedinPosts

**List posts by a person or company**

List posts from a person (user id or public identifier) or a company page (numeric id or company URL). remainingUsage is the post-view budget; looking up a handle also spends a profile-view or company-view unit.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `identity` (string, required): Author to read, as a user id or public identifier. For a company page, prefer GET /api/v1/linkedin/companies/{identifier}/posts.
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleGetLinkedinPost

**Get a LinkedIn post**

Get one LinkedIn post by the postId returned from a post listing or search.

**Input**

- `postId` (string, required): Post id as returned by a post listing or search. An id copied from a post URL often does not resolve.
- `connectedAccountId` (string · uuid, required): Connected account to act as

### needleListLinkedinPostComments

**List comments on a post**

List comments on a post, or replies to one comment when commentId is given.

**Input**

- `postId` (string, required): Post id as returned by a post listing or search. An id copied from a post URL often does not resolve.
- `connectedAccountId` (string · uuid, required): Connected account to act as
- `commentId` (string, optional): Read replies to this comment instead of top-level comments.
- `sortBy` ("MOST_RECENT" | "MOST_RELEVANT", optional)
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleListLinkedinPostReactions

**List reactions on a post**

List the people who reacted to a LinkedIn post, or to a comment when commentId is given.

**Input**

- `postId` (string, required): Post id as returned by a post listing or search. An id copied from a post URL often does not resolve.
- `connectedAccountId` (string · uuid, required): Connected account to act as
- `commentId` (string, optional): Read reactions on this comment instead of the ones on the post.
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleCommentOnLinkedinPost

**Comment on a post**

Comment on a LinkedIn post, or reply to a comment when commentId is given.

**Input**

- `postId` (string, required): Post id as returned by a post listing or search. An id copied from a post URL often does not resolve.
- `connectedAccountId` (string · uuid, required): Connected account to act as
- `text` (string, required)
- `commentId` (string, optional): Reply to this comment instead of commenting on the post.

### needleReactToLinkedinPost

**React to a post**

React to a LinkedIn post, or to a comment when commentId is given. Defaults to like.

**Input**

- `postId` (string, required): Post id as returned by a post listing or search. An id copied from a post URL often does not resolve.
- `connectedAccountId` (string · uuid, required): Connected account to act as
- `reaction` ("like" | "celebrate" | "support" | "love" | "insightful" | "funny", optional): Defaults to like.
- `commentId` (string, optional): React to this comment instead of the post.

### needleListLinkedinSearchParameters

**List LinkedIn search parameters**

Resolve LinkedIn filter values from keywords. Each service has its own types: standard LinkedIn resolves LOCATION and INDUSTRY, while Sales Navigator resolves REGION and SALES_INDUSTRY along with DEPARTMENT, GROUPS, PERSONA, ACCOUNT_LISTS and LEAD_LISTS. LANGUAGE lists official ISO 639-1 codes for either and can be filtered by code or name.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `type` ("LOCATION" | "INDUSTRY" | "COMPANY" | "SCHOOL" | "SERVICE" | "JOB_TITLE" | "JOB_FUNCTION" | "CONNECTIONS" | "PEOPLE" | "LANGUAGE" | "REGION" | "SALES_INDUSTRY" | "DEPARTMENT" | "GROUPS" | "PERSONA" | "ACCOUNT_LISTS" | "LEAD_LISTS", required): Kind of filter value to resolve, and it has to be one the chosen service has. Standard LinkedIn takes LOCATION, INDUSTRY, COMPANY, SCHOOL, SERVICE, JOB_TITLE, JOB_FUNCTION, CONNECTIONS, PEOPLE, LANGUAGE. Sales Navigator takes REGION, SALES_INDUSTRY, COMPANY, SCHOOL, JOB_TITLE, DEPARTMENT, GROUPS, PERSONA, ACCOUNT_LISTS, LEAD_LISTS, CONNECTIONS, LANGUAGE. LANGUAGE returns ISO 639-1 codes rather than LinkedIn ids.
- `keywords` (string, optional): Text to match, such as Berlin for LOCATION or REGION, engineer for JOB_TITLE, or Russian or ru for LANGUAGE. Saved groups, personas and lists are listed whole when this is left out.
- `service` ("classic" | "sales_navigator", optional): Which search to resolve against. Defaults to classic.
- `limit` (integer, optional)

## Instagram

### needleGetInstagramProfile

**Get an Instagram profile**

Get an Instagram profile by username without @.

**Input**

- `identity` (string, required): Username without @.
- `connectedAccountId` (string · uuid, required): Connected account to act as

### needleGetInstagramAccountProfile

**Get the connected account profile**

Get the Instagram profile of the connected account, with its follower, following and post counts.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as

### needleSendInstagramMessage

**Send an Instagram message**

Send an Instagram direct message as a connected account.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `identity` (string, required): Username without @.
- `text` (string, required)
- `attachments` (object[], optional): Files to send alongside the text.

### needleReactToInstagramMessage

**React to an Instagram message**

Add an emoji reaction to an Instagram direct message.

**Input**

- `messageId` (string, required): messageId from the messages of a conversation.
- `connectedAccountId` (string · uuid, required): Connected account to act as
- `reaction` (string, required): A single emoji, such as 👍.

### needleListInstagramConversations

**List Instagram conversations**

List the Instagram inbox of a connected account, most recent first.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `cursor` (string, optional)
- `limit` (integer, optional): Page size, up to 100. Defaults to 20. A page can hold fewer, so follow cursor until it comes back null.

### needleListInstagramConversationMessages

**List messages in a conversation**

List messages in an Instagram conversation.

**Input**

- `conversationId` (string, required): conversationId from the conversations listing
- `connectedAccountId` (string · uuid, required): Connected account to act as
- `limit` (integer, optional): Page size. Defaults to 20.

### needleListInstagramConversationParticipants

**List the participants of a conversation**

List the accounts in an Instagram conversation, with their usernames.

**Input**

- `conversationId` (string, required): conversationId from the conversations listing
- `connectedAccountId` (string · uuid, required): Connected account to act as

### needleListInstagramPosts

**List the posts of an account**

List the posts of an Instagram account, most recent first. A username that does not exist comes back with no posts.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `identity` (string, required): Whose posts to read, as a username without @.
- `cursor` (string, optional)
- `limit` (integer, optional): Page size, up to 100. Defaults to 20. A page can hold fewer, so follow cursor until it comes back null.

### needleGetInstagramPost

**Get an Instagram post**

Get one Instagram post by post id, or by the short code from its URL.

**Input**

- `postId` (string, required): postId from a posts listing, or the short code from the post URL.
- `connectedAccountId` (string · uuid, required): Connected account to act as

### needleCreateInstagramPost

**Publish an Instagram post**

Publish an Instagram feed post or story. At least one image or video URL is required.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `text` (string, required): Caption for the post. Write @username to mention someone.
- `media` (object[], required): Images or videos to publish.
- `postType` ("feed" | "story", optional): Defaults to feed. A story is visible for 24 hours.
- `location` (string, optional): Name of a place to tag.

### needleListInstagramPostComments

**List the comments on a post**

List the comments on an Instagram post, or the replies to one comment.

**Input**

- `postId` (string, required): postId from a posts listing, or the short code from the post URL.
- `connectedAccountId` (string · uuid, required): Connected account to act as
- `commentId` (string, optional): Read the replies to this comment instead of the top-level comments.
- `cursor` (string, optional)
- `limit` (integer, optional): Page size, up to 100. Defaults to 20. A page can hold fewer, so follow cursor until it comes back null.

### needleCommentOnInstagramPost

**Comment on a post**

Comment on an Instagram post, or reply to a comment on it. Write @username to mention someone.

**Input**

- `postId` (string, required): postId from a posts listing, or the short code from the post URL.
- `connectedAccountId` (string · uuid, required): Connected account to act as
- `text` (string, required): The comment. Write @username to mention someone.
- `commentId` (string, optional): Reply to this comment instead of commenting on the post.

### needleListInstagramPostReactions

**List the likes on a post**

List the accounts that liked an Instagram post, or one of its comments.

**Input**

- `postId` (string, required): postId from a posts listing, or the short code from the post URL.
- `connectedAccountId` (string · uuid, required): Connected account to act as
- `commentId` (string, optional): Read the likes on this comment instead of the ones on the post.
- `cursor` (string, optional)
- `limit` (integer, optional): Page size, up to 100. Defaults to 20. A page can hold fewer, so follow cursor until it comes back null.

### needleLikeInstagramPost

**Like a post**

Like an Instagram post, or one of its comments. A like is the only reaction a post takes.

**Input**

- `postId` (string, required): postId from a posts listing, or the short code from the post URL.
- `connectedAccountId` (string · uuid, required): Connected account to act as
- `commentId` (string, optional): Like this comment instead of the post.

### needleListInstagramFollowers

**List followers**

List the followers of an Instagram account. Omit identity for the connected account.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `identity` (string, optional): Whose followers to read. Omit for the connected account.
- `cursor` (string, optional)
- `limit` (integer, optional): Page size, up to 25. A page can hold fewer, so follow cursor until it comes back null.

### needleListInstagramFollowing

**List followed accounts**

List the accounts an Instagram account follows. Omit identity for the connected account.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `identity` (string, optional): Whose followed accounts to read. Omit for the connected account.
- `cursor` (string, optional)
- `limit` (integer, optional): Page size, up to 25. A page can hold fewer, so follow cursor until it comes back null.

### needleFollowInstagramUser

**Follow an Instagram user**

Follow an Instagram user as a connected account.

**Input**

- `connectedAccountId` (string · uuid, required): Connected account to act as
- `identity` (string, required): Username without @.

### needleUnfollowInstagramUser

**Unfollow an Instagram user**

Unfollow an Instagram user as a connected account.

**Input**

- `identity` (string, required): Username without @.
- `connectedAccountId` (string · uuid, required): Connected account to act as

## Places

### needleSearchPlaces

**Search places**

Build a list of businesses and locations. Pass a query for text search, or a location (and optional type) for nearby search. Page text-search results with the returned cursor. The response includes remainingUsage for this workspace.

**Input**

- `query` (string, optional): Free-text query, e.g. "dentists in Munich". Required unless `location` is set.
- `location` (object, optional): Center point. Required unless `query` is set. Without a query this is a nearby search inside the radius.
  - `latitude` (number, required)
  - `longitude` (number, required)
- `radiusMeters` (integer, optional): Radius when `location` is set. Defaults to 50 km. Nearby search stays inside this circle; text search is biased toward it.
- `type` (string, optional): A Google Places type such as `restaurant` or `dentist`.
- `language` (string, optional): BCP-47 language code for names and addresses.
- `region` (string, optional): CLDR region code that biases results, e.g. `DE`.
- `cursor` (string, optional): Text-search pagination cursor. Nearby search does not page.
- `limit` (integer, optional)

### needleGetPlace

**Get a place**

Get place details by Google Place id. The response includes remainingUsage for this workspace.

**Input**

- `placeId` (string, required): Google Place id

## Compose

### needleComposePreview

**Preview an AI-composed message**

Preview an AI-composed outreach message without sending it, from any prompt, account, and profile. To see what a saved campaign step sends, use needleGetMessagePreviewForStep instead. identity accepts the same forms as leads: LinkedIn public identifier, /in/ path, profile URL, or user id; Instagram username, @handle, or profile URL.

**Input**

- `channel` ("linkedin" | "instagram", required)
- `connectedAccountId` (string · uuid, required)
- `identity` (string, required): LinkedIn public identifier, /in/ path, profile URL, or user id (ACoAAA…); or Instagram username, @handle, or profile URL. Stored as the identifier.
- `prompt` (string, required)
- `context` ("profile" | "posts" | "conversation" | "lead_properties"[], optional)
- `maxChars` (integer, optional)
- `leadProperties` (object, optional)

## Files

### needleListFiles

**List files**

List a page of files you can use: every workspace file, then your private files. Each item includes scope. Pass a workspace url on a campaign step or a LinkedIn send. Pass your own user url on needleSendLinkedinMessage or needleSendLinkedinInMail. Use nextCursor as cursor for the next page.

**Input**

- `cursor` (string, optional)
- `limit` (integer, optional)

### needleCreateFileAccessUrl

**Create a file preview URL**

Mint a preview URL for a stored file. It redirects to a short-lived signed GET. Do not send it to LinkedIn.

**Input**

- `url` (string · uri, required)

### needleDeleteFile

**Delete a file**

Delete a private file stored in Needle. Pass the url from needleListFiles or from creating a file. Messages and campaign steps that still reference it will fail when sending.

**Input**

- `url` (string · uri, required)

### needleCreateFileUpload

**Create a file upload**

Mint a short-lived signed PUT URL, or copy a public file with sourceUrl. Omit scope for a workspace file. Pass scope "user" to keep the file visible only to you. PUT bytes to uploadUrl when it is returned, then pass the returned url on needleSendLinkedinMessage or needleSendLinkedinInMail. Campaign steps can attach workspace files only. downloadUrl is a preview link. Do not store uploadUrl.

**Input**

- `scope` ("workspace" | "user", optional): workspace shares the file with the organization. user keeps it visible only to you. Omit for a workspace file. Campaign steps can attach workspace files only.
- `filename` (string, optional)
- `contentType` (string, optional)
- `sourceUrl` (string · uri, optional): Public https URL. Needle copies the file into a private object and returns the url to attach.

## Suppressions

### needleListSuppressions

**List suppressions**

List a page of suppression entries. Optionally filter by reason. Use nextCursor as cursor for the next page.

**Input**

- `cursor` (string, optional)
- `limit` (integer, optional)
- `reason` ("manual" | "unsubscribed" | "not_interested" | "existing_customer" | "open_opportunity" | "competitor" | "employee" | "invalid_recipient" | "complained" | "recently_contacted" | "unresponsive", optional)

### needleSearchSuppressions

**Search suppressions**

Find suppression entries by person, company domain, note, or reason. Every word in query must match; people or domains starting with it come first. Pass nextCursor as cursor, with the same query, for more. Use the returned id with needleDeleteSuppression.

**Input**

- `query` (string, required): Text to match. Every word must appear in the record.
- `cursor` (string, optional)
- `limit` (integer, optional)

### needleCreateSuppressions

**Create suppressions**

Create suppression entries for people or companies.

**Input**

- `entries` (object[], required)

### needleCheckSuppressions

**Check people and companies against the suppression list**

Check whether identities are contactable or suppressed. IdenToolAnnotationWrite,tity accepts the same forms as leads: LinkedIn public identifier, /in/ path, profile URL, or user id; Instagram username, @handle, or profile URL.

**Input**

- `identities` (object[], required)

### needleDeleteSuppression

**Delete a suppression**

Delete a suppression entry.

**Input**

- `suppressionId` (string · uuid, required): Suppression id

## Webhooks

### needleListWebhooks

**List webhooks**

List the workspace's webhooks, oldest first, with their delivery status. lastError is null when the last delivery succeeded.

**Input**

object

### needleCreateWebhook

**Create a webhook**

Add an https URL that receives events, signed with a new secret. eventTypes picks the event types: "all" (the default, also types added later) or a list. The whsec_ secret is returned only here; show it to the user so they can store it. Up to 5 per workspace. Optional headers, such as an API key the URL requires, are sent with every request. Header values you send pass through your AI app.

**Input**

- `url` (string · uri, required): An https URL that accepts POST requests.
- `headers` (object, optional): Extra headers sent with every request, for example an API key your endpoint checks: {"Authorization": "Bearer ..."}. Up to 5. Names are stored in lower case.
- `eventTypes` (string | string[], optional): The event types this webhook gets: "all" (every type, also types added later) or a list. Left out, it is "all".

### needleGetWebhook

**Get a webhook**

Get one webhook with its delivery status.

**Input**

- `webhookId` (string · uuid, required): Webhook id

### needleUpdateWebhook

**Update a webhook**

Change the URL, the headers, the event types, or several at once, or turn on a webhook that was turned off after 3 days without a 2xx (enabled: true). Only the member who created the webhook can change it. Pending deliveries of event types no longer picked are dropped. Only the headers named change: a value sets or replaces one, null removes it. A new URL removes all saved headers first. The secret stays the same, and pending deliveries go out with the new URL and headers. Header values you send pass through your AI app.

**Input**

- `webhookId` (string · uuid, required): Webhook id
- `url` (string · uri, optional): The new URL. A different URL removes all saved headers first.
- `headers` (object, optional): Changes only the headers named here: a value sets or replaces that header, null removes it. Headers not named stay, except when url changes: then only the headers sent here are kept.
- `eventTypes` (string | string[], optional): The new event types: "all" or a list. Pending deliveries of types no longer in the list are dropped; added types only get events from now on.
- `enabled` (boolean, optional): Turns on a webhook that was turned off. Events from while it was off are not sent. Any other change turns it on too.

### needleDeleteWebhook

**Delete a webhook**

Delete a webhook. Only the member who created it or a workspace admin can. Needle stops sending events to it, and its pending deliveries are dropped.

**Input**

- `webhookId` (string · uuid, required): Webhook id

## Onboarding

### needleGetOnboardingInfo

**Get onboarding info**

Get what the user told Needle during onboarding and what it produced: the use case, website, notes, attached documents, the ideal customer profile, the ids of the leads found, the onboarding campaign id, and when onboarding was completed. Fields the user has not reached yet are null or empty.

**Input**

object

## Assistant chats

### needleGetAssistantChat

**Get an assistant chat**

Read a chat the user had with the assistant inside the Needle web app, to continue it here. When `handoff` is set, the assistant passed the task on: its `brief` holds the goal, the ids involved, what was already found, and what is left. Start from the brief and carry the task out with your Needle tools. Messages hold each turn's text and the tools it called. Calls since the last user message keep their results; earlier ones do not.

**Input**

- `id` (string · uuid, required)

## Docs

### needleSearchDocs

**Search the Needle docs**

Find Needle documentation pages: guides, concepts, every REST API endpoint, and every MCP tool. Pages that match more of the words come first. Read a result with needleReadDocs and its pageId.

**Input**

- `query` (string, required): Words to look for. Pages that match more of them come first.
- `limit` (integer, optional): Most pages to return. Default 10.

### needleReadDocs

**Read the Needle docs**

Read one page of the Needle documentation as markdown. Use it to answer how Needle works: its features, integrations, setup, and limits.
Not sure which page? Search first with needleSearchDocs.
Pages:
- introduction: What Needle is and the ways to use it: the dashboard, the REST API, and MCP.
- authentication: Two ways in: API keys for the REST API, sign-in for MCP.
- agent-onboarding: Where an agent starts: MCP, the REST API, credentials, and common outbound workflows.
- api-reference/introduction: Every REST API endpoint. Each endpoint has its own page, for example api-reference/create-lead.
- mcp/introduction: Every MCP tool. Each tool has its own page, for example mcp/needle-create-lead.
- changelog: Notable changes to the Needle Agents REST API and MCP server.
- workspaces: Where leads, campaigns, and connected accounts live.
- leads: People you can enroll in a campaign.
- campaigns: Sequences this workspace is running.
- enrollments: A lead moving through a campaign sequence.
- drafts: Messages that wait for a person to approve them.
- connected-accounts: LinkedIn and Instagram senders this workspace reaches out from.
- suppressions: People and companies on the do-not-contact list.
- events: Activity across campaigns, leads, and connected accounts.
- webhooks: Receive events at your own URL as they happen.
- attio: Sync your team's LinkedIn activity to your Attio People.
- hubspot: Sync your team's LinkedIn activity to your HubSpot contacts.
- places: Companies and locations you can turn into lead lists.
- compose: Preview an AI-written message before you send it.
- agents: Personal agents that work in Slack and Teams.

**Input**

- `pageId` (string, required): The page's path after /docs/, for example `attio` or `mcp/needle-create-lead`. A full docs URL works too.
