API Reference
The Updately REST API gives you your leads, lists, campaigns and signals, and webhooks tell you the moment a lead is found or a prospect replies. It is the same API behind our MCP server and our Zapier integration.
Authentication
Create an API key in the app under Settings → Integrations → API Keys. Keys start with api_key_, belong to one workspace, and are shown once. Send the key as a bearer token on every request to https://api.updately.ai.
curl https://api.updately.ai/org/account \
-H "Authorization: Bearer api_key_…"Every response is JSON in the same envelope:
{ "success": true, "message": "3 list(s) found.", "data": … }Errors come back with "success": false and a readable message — often with HTTP 200, so check success rather than the status code. An invalid or revoked key answers Organization ID not found. Please provide valid authentication.
All requests and webhook URLs must use HTTPS. Timestamps are ISO 8601 in UTC.
Account
/org/accountThe workspace the API key belongs to. Useful for checking a key works.
data in the response{
"email": "you@company.com",
"username": "acme",
"name": "Acme Inc"
}Lead lists
Leads live in lists. Signals save the people they find into lists, and campaigns enroll people from them.
/leads/listsAll lead lists in the workspace.
data in the response[
{ "listId": "b695428e-…", "name": "VP Sales — UK", "contactCount": 42,
"createdAt": "2026-10-15T08:44:18Z", "updatedAt": "2026-10-15T09:02:11Z" }
]/leads/listsCreates a list.
{ "name": "VP Sales — UK", "description": "Optional" }/leads/contactsEvery lead in the workspace, or in one list.
listId(optional) — only leads in this list
data in the response[
{
"leadId": "5f0c1e8a-…", "listId": "b695428e-…",
"firstName": "Priya", "lastName": "Shah", "email": null,
"headline": "VP Sales at Northwind Analytics", "currentJobTitle": "VP Sales",
"company": "Northwind Analytics", "linkedinUrl": "https://www.linkedin.com/in/priya-shah",
"location": "London, United Kingdom", "industry": "Software Development",
"source": "LINKEDIN_JOBS_SIGNAL", "signalId": "1ad12150-…", "intent": "Hiring for SDR",
"captureScore": 82, "createdAt": "2026-10-15T08:30:00Z"
}
]/leads/lists/{listId}/contactsThe leads in one list.
/leads/lists/{listId}/contactsAdds one person to a list and returns the lead. If the LinkedIn URL is already in the list, the existing lead comes back instead of a duplicate. People added to a list that a campaign uses as its source are enrolled in that campaign.
{
"linkedinUrl": "https://www.linkedin.com/in/priya-shah",
"email": "priya@northwind-analytics.com",
"firstName": "Priya", "lastName": "Shah",
"headline": "VP Sales", "company": "Northwind Analytics",
"location": "London", "industry": "Software Development"
}/leads/lists/{listId}/contacts/bulkAdds many people in one call. Rows without a LinkedIn URL are skipped, and people already in the list count as duplicates.
{ "leads": [ { "linkedinUrl": "https://www.linkedin.com/in/priya-shah", "firstName": "Priya" } ] }data in the response{ "added": 12, "duplicates": 3, "skipped": 1 }Campaigns
Campaigns are LinkedIn sequences. They send on their own schedule, and only while their status is ACTIVE.
/campaignsAll campaigns with their status and totals.
data in the response[ { "campaignId": "c4737503-…", "name": "Heads of Revenue — Q4", "status": "ACTIVE", "totalContacts": 120 } ]/campaigns/{campaignId}One campaign.
/campaigns/{campaignId}/contactsEnrolls people by LinkedIn URL, by lead ID, or a whole list. People already in the campaign are skipped.
{
"linkedinProfileUrls": ["https://www.linkedin.com/in/priya-shah"],
"leadIds": ["5f0c1e8a-…"],
"listIds": ["b695428e-…"]
}data in the response{ "enrolled": 1 }/campaigns/{campaignId}/contactsThe people in a campaign, with their progress, reply and reply intent.
data in the response[
{
"contactId": "ct_8f2a91", "firstName": "Tom", "lastName": "Becker",
"headline": "Head of Revenue at Brightlane", "companyName": "Brightlane",
"linkedinProfileUrl": "https://www.linkedin.com/in/tombecker",
"status": "REPLIED", "replyIntent": "INTERESTED",
"lastReplyText": "Sounds interesting…", "repliedAt": "2026-10-15T09:12:44Z"
}
]Signals
Signals find people showing buying intent — hiring, posting, searching — and save them to lists on a schedule.
/signalsAll signals, with the outcome of their last run.
data in the response[
{
"signalId": "1ad12150-…", "name": "Hiring SDRs in London", "type": "LINKEDIN_JOBS",
"enabled": true, "listIds": ["b695428e-…"],
"runStatus": "COMPLETED", "lastRunAt": "2026-10-15T06:00:12Z",
"lastRunLeadCount": 14, "lastRunFetchedCount": 37, "lastRunError": null
}
]/signals/{signalId}One signal.
/signals/{signalId}/runStarts a run in the background and returns at once. New leads land in the signal’s lists a few minutes later, and a signal.run_finished webhook fires when it ends.
force(optional, true/false) — run a paused signal and skip the wait between scheduled runs
data in the response"Run started"Webhooks
Register a URL and Updately POSTs to it when something happens. A workspace can have up to 10 webhooks.
/org/webhooksYour webhooks and the events you can subscribe to.
/org/webhooksRegisters a webhook. An empty events list means every event. The signing secret is only returned here.
{ "url": "https://example.com/updately", "events": ["contact.replied"], "description": "CRM sync" }data in the response{ "webhookId": "a1b2c3d4", "url": "https://example.com/updately",
"events": ["contact.replied"], "secret": "whsec_…", "enabled": true }/org/webhooks/{webhookId}Changes the URL, events, description or enabled flag.
{ "enabled": false }/org/webhooks/{webhookId}Removes a webhook.
/org/webhooks/{webhookId}/testSends a ping event right away and reports what your endpoint answered.
Webhook events
| Event | Sent when |
|---|---|
| lead.captured | A signal saved a new lead to a list. |
| signal.run_finished | A signal finished a run, whether it completed or failed. |
| contact.replied | A prospect replied to a campaign message. |
| contact.interested | A reply was classified as interested (sent in addition to contact.replied). |
| contact.connected | A prospect accepted your connection invitation. |
| contact.needs_human | The reply agent handed a conversation to you. |
| contact.completed | A prospect finished the sequence without replying. |
Each delivery is a POST with a JSON body and these headers: X-Updately-Event (the event name), X-Updately-Delivery (unique per delivery) and X-Updately-Signature. The body is always this envelope:
{
"id": "9b2f…", // unique per event
"event": "lead.captured",
"createdAt": "2026-10-15T08:30:00Z",
"orgId": "2d73b91f-…",
"data": { … } // depends on the event, below
}data for lead.captured
{
"signal": "Hiring SDRs in London",
"lead": {
"leadId": "5f0c1e8a-…", "listId": "b695428e-…",
"firstName": "Priya", "lastName": "Shah", "headline": "VP Sales at Northwind Analytics",
"company": "Northwind Analytics", "linkedinUrl": "https://www.linkedin.com/in/priya-shah",
"location": "London, United Kingdom", "industry": "Software Development",
"intent": "Hiring for SDR", "score": 82, "source": "LINKEDIN_JOBS_SIGNAL"
}
}data for signal.run_finished
{
"signal": {
"signalId": "1ad12150-…", "name": "Hiring SDRs in London", "type": "LINKEDIN_JOBS",
"status": "COMPLETED", // or FAILED
"error": null, "leadsSaved": 14, "fetched": 37,
"diagnosis": "37 found, 14 matched your ideal customer profile.",
"listIds": ["b695428e-…"], "finishedAt": "2026-10-15T06:00:12Z"
}
}data for contact.* events
{
"campaign": { "campaignId": "c4737503-…", "name": "Heads of Revenue — Q4" },
"contact": {
"contactId": "ct_8f2a91", "firstName": "Tom", "lastName": "Becker",
"headline": "Head of Revenue at Brightlane", "company": "Brightlane",
"linkedinUrl": "https://www.linkedin.com/in/tombecker",
"status": "REPLIED", "intent": "INTERESTED",
"repliedAt": "2026-10-15T09:12:44Z", "connectedAt": "2026-10-12T14:03:10Z",
"lastReply": "Sounds interesting — can you send over a few times next week?",
"customFields": {}, "enrichment": {}
},
"reply": "Sounds interesting…", // contact.replied and contact.interested only
"intent": "INTERESTED" // contact.replied and contact.interested only
}Verifying the signature
X-Updately-Signature is sha256= followed by the hex HMAC-SHA256 of the raw body, keyed with the webhook's secret.
import crypto from 'node:crypto'
// rawBody: the request body exactly as received, before JSON parsing
function isFromUpdately(rawBody, signatureHeader, secret) {
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader || ''))
}Retries
Answer with any 2xx within 10 seconds. A timeout, network error, 408, 429 or 5xx is retried twice, after 2 and 8 seconds; other 4xx answers are not retried. The webhook list shows each hook's last status and error.
MCP server
AI assistants such as Claude and ChatGPT can use these same endpoints as tools through https://api.updately.ai/mcp. Setup is on the MCP docs. Questions: hello@updately.ai.