Skip to main content
Use Needle through Corsair: one client, typed API calls. A key comes from https://needle.app/settings/api-keys. It is shown once, so copy it then. Each key is bound to one user and one workspace, and every call runs as that user in that workspace.
  • Every lead needs at least one identity and a timezone. Identities are a LinkedIn public identifier, /in/ path, profile URL or user id, or an Instagram username, handle or URL. Needle stores the bare identifier, so the value read back is not the URL sent in. The timezone drives the sending window, so it decides when a step may fire.
  • leads.create refuses a duplicate. A second lead with the same identity answers 409. leads.upsert is the merging call: it answers created or matched, and on a match it patches the fields sent onto the existing lead.
  • leads.update replaces identities rather than adding. Sending identities replaces the whole set, so omit it to leave the existing channels alone.
  • A campaign is a graph and starts in draft. campaigns.create takes nodes (at least a start and an end) and the edges that connect them; both are required. Nodes can be delay, action, condition (branches on yes/no edges) or wait_until (follows on_event or on_timeout). schedule, limits and suppressionPolicy set the sending window, the gap between actions and who is skipped. Nothing is sent until campaigns.update sets status: 'active'; paused halts it again. campaigns.delete archives rather than erases.
  • Enrollment partly succeeds. campaigns.enroll takes up to 500 lead ids and returns one result per lead: an accepted entry carries an enrollment id, a skipped one carries a reason such as suppressed or recently_contacted.
  • Run suppressions.check before enrolling. It answers contactable per identity with the reason when false. Needle also applies its own suppression policy during a send, so an enrolled lead can still be skipped.
  • compose.preview never sends. It returns suggested text and the context sources used.
Worth knowing:
  • There is no error code. Every failure is { requestId, error }, so the status is the only classification: 401 a bad key, 403 a missing scope or plan limit, 409 a duplicate identity, 422 validation. Keep the requestId: it is what Needle support asks for. An HTTP failure is core’s ApiError, with the id in error.body.requestId; NeedleAPIError only covers a transport failure that never got a response.
  • Paging is a cursor. Pass nextCursor back as cursor; it is null on the last page. places.search is the exception: a text search returns cursor (not nextCursor), absent on the last page, and a nearby search does not page.
  • Only reads are retried on a 5xx. A failed send or enroll may have gone through, and Needle takes no idempotency key.
What you get:
  • 23 typed API operations

Setup

1

Install

2

Add the plugin

corsair.ts
With multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.
3

Choose authentication

4

Connect a tenant

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.

Example API calls

List the first page of leads
Add a lead, or merge into the existing one
See the full list on the API page.

What’s next

API reference

Every needle.api.* operation with input and output types.

Connect / OAuth

createLink, Hub delivery, and tenant connect flows.

Use with agents

Expose this plugin’s operations as MCP tools.