- 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.createrefuses a duplicate. A second lead with the same identity answers 409.leads.upsertis the merging call: it answerscreatedormatched, and on a match it patches the fields sent onto the existing lead.leads.updatereplaces identities rather than adding. Sendingidentitiesreplaces the whole set, so omit it to leave the existing channels alone.- A campaign is a graph and starts in draft.
campaigns.createtakesnodes(at least a start and an end) and theedgesthat connect them; both are required. Nodes can bedelay,action,condition(branches onyes/noedges) orwait_until(followson_eventoron_timeout).schedule,limitsandsuppressionPolicyset the sending window, the gap between actions and who is skipped. Nothing is sent untilcampaigns.updatesetsstatus: 'active';pausedhalts it again.campaigns.deletearchives rather than erases. - Enrollment partly succeeds.
campaigns.enrolltakes 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 assuppressedorrecently_contacted. - Run
suppressions.checkbefore enrolling. It answerscontactableper 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.previewnever sends. It returns suggested text and the context sources used.
- 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 therequestId: it is what Needle support asks for. An HTTP failure is core’sApiError, with the id inerror.body.requestId;NeedleAPIErroronly covers a transport failure that never got a response. - Paging is a cursor. Pass
nextCursorback ascursor; it is null on the last page.places.searchis the exception: a text search returnscursor(notnextCursor), 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.
- 23 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the Needle API key before the first call: More: API Key
pnpm corsair setup --plugin=needle --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.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 leadsWhat’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.