UpdatelyUpdately

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

GET/org/account

The 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.

GET/leads/lists

All 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" }
]
POST/leads/lists

Creates a list.

Request body
{ "name": "VP Sales — UK", "description": "Optional" }
GET/leads/contacts

Every lead in the workspace, or in one list.

Query parameters
  • 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"
  }
]
GET/leads/lists/{listId}/contacts

The leads in one list.

POST/leads/lists/{listId}/contacts

Adds 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.

Request body
{
  "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"
}
POST/leads/lists/{listId}/contacts/bulk

Adds many people in one call. Rows without a LinkedIn URL are skipped, and people already in the list count as duplicates.

Request body
{ "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.

GET/campaigns

All campaigns with their status and totals.

data in the response
[ { "campaignId": "c4737503-…", "name": "Heads of Revenue — Q4", "status": "ACTIVE", "totalContacts": 120 } ]
GET/campaigns/{campaignId}

One campaign.

POST/campaigns/{campaignId}/contacts

Enrolls people by LinkedIn URL, by lead ID, or a whole list. People already in the campaign are skipped.

Request body
{
  "linkedinProfileUrls": ["https://www.linkedin.com/in/priya-shah"],
  "leadIds": ["5f0c1e8a-…"],
  "listIds": ["b695428e-…"]
}
data in the response
{ "enrolled": 1 }
GET/campaigns/{campaignId}/contacts

The 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.

GET/signals

All 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
  }
]
GET/signals/{signalId}

One signal.

POST/signals/{signalId}/run

Starts 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.

Query parameters
  • 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.

GET/org/webhooks

Your webhooks and the events you can subscribe to.

POST/org/webhooks

Registers a webhook. An empty events list means every event. The signing secret is only returned here.

Request body
{ "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 }
PUT/org/webhooks/{webhookId}

Changes the URL, events, description or enabled flag.

Request body
{ "enabled": false }
DELETE/org/webhooks/{webhookId}

Removes a webhook.

POST/org/webhooks/{webhookId}/test

Sends a ping event right away and reports what your endpoint answered.

Webhook events

EventSent when
lead.capturedA signal saved a new lead to a list.
signal.run_finishedA signal finished a run, whether it completed or failed.
contact.repliedA prospect replied to a campaign message.
contact.interestedA reply was classified as interested (sent in addition to contact.replied).
contact.connectedA prospect accepted your connection invitation.
contact.needs_humanThe reply agent handed a conversation to you.
contact.completedA 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.