Developers
Connect BookedUp to your systems
Get every new lead, call and booking in your CRM, spreadsheet or app the moment it happens, with signed webhooks, and create or look up leads with an API key.
Using an AI assistant?
Connect Claude, ChatGPT or another assistant to BookedUp over MCP, with no API keys: quickstart · tool reference · OpenAPI · llms.txt
Overview
There are two ways to connect:
- Webhooks (push): BookedUp sends an HTTPS POST to your URL for the events you choose. Set them up in your dashboard under Settings > Integrations > Webhooks.
- API keys (pull and actions): check a key, subscribe a URL to events, fetch sample payloads, create a lead, or find a lead by phone number.
Everything is scoped to one business: a key or webhook only ever sees that business's own leads and bookings. Spam calls are never sent.
API keys
Create a key in Settings > Integrations > API keys. Keys look like bk_live_… (43 random characters after the prefix). The full key is shown once; we only store a hash of it, so keep it somewhere safe. A business can have up to 10 active keys.
Send the key in either header:
Authorization: Bearer bk_live_...
# or
X-API-Key: bk_live_...Revoke a key from the same screen. Revoking takes effect immediately, and any Zapier subscriptions created with that key are deleted too.
Test a key:
curl https://getbookedup.ai/api/integrations/zapier/me \
-H "Authorization: Bearer $BOOKEDUP_API_KEY"
# 200 {"business":{"id":"…","name":"Acme Plumbing"}}Webhooks
Add an endpoint in Settings > Integrations > Webhooks: a public https:// URL (no private or internal addresses), a name, and the events you want. You'll see a signing secret (whsec_…) once; you can rotate it any time. Up to 10 endpoints per business. Use Send test event to get a sample delivery (it carries "test": true), and Deliveries to see the last 50 attempts.
Every delivery is a POST with a JSON body and these headers:
Content-Type: application/json
User-Agent: BookedUp-Webhooks/1.0 (+https://getbookedup.ai)
BookedUp-Signature: t=1794500000,v1=5f0c…
BookedUp-Event-Id: evt_3a9f…
BookedUp-Event-Type: lead.createdThe body is an envelope (version 2026-11-11; changes within a version are additive only):
{
"id": "evt_00000000000000000000000000000001",
"type": "lead.created",
"created_at": "2026-11-12T15:00:00.000Z",
"api_version": "2026-11-11",
"data": {
"lead_id": "00000000-0000-4000-8000-000000000001",
"business": {
"id": "00000000-0000-4000-8000-0000000000aa",
"name": "Acme Plumbing"
},
"source": "phone",
"name": "Jane Sample",
"phone": "+16155550123",
"address": "123 Main St, Nashville, TN 37203",
"within_service_area": true,
"issue": "AC is blowing warm air",
"urgency": "soon",
"status": "completed",
"outcome": "callback_requested",
"preferred_time": "Tomorrow morning",
"appointment": null,
"summary": "Sample lead from BookedUp. Caller needs AC service.",
"duration_seconds": 142,
"recording_available": true,
"tags": [],
"custom_answers": {},
"lead_url": "https://getbookedup.ai/dashboard/leads/00000000-0000-4000-8000-000000000001",
"created_at": "2026-11-11T15:04:05.000Z",
"updated_at": null
}
}- Fields a business turned off in its intake settings (email, address, issue) are left out entirely, not sent as null.
- Times are ISO-8601 in UTC; appointments also carry the business's IANA
timezone. - Recordings and transcripts are never included: use
lead_url(dashboard login required). - Lead
sourceisphone,booking_pageormanual(added by hand, in the dashboard or withPOST /leads). A hand-added lead hasstatusmanualand, until you set one,outcomelead. - Real event ids are
evt_plus 32 hex characters. Test events (Send test event) and the samples fromGET /samples/:eventhave ids starting withevt_test_and carry"test": true; real events never do.
Verifying signatures
BookedUp-Signature is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of <t>.<raw body>, keyed with your whole secret string (including the whsec_ prefix). To verify:
- Use the raw request body, before any JSON parsing.
- Compare in constant time, and accept any
v1value in the header. - Reject timestamps more than 5 minutes from now (replay protection).
The Node.js and Python snippets are tested against our signing code; the PHP one follows the same steps.
Node.js
const crypto = require("node:crypto");
// rawBody: the request body exactly as received (string or Buffer), before JSON.parse.
function verifyBookedUp(rawBody, header, secret, toleranceSec = 300) {
if (!header) return false;
const parts = Object.create(null);
const sigs = [];
for (const piece of header.split(",")) {
const [k, v] = piece.trim().split("=", 2);
if (k === "t") parts.t = v;
else if (k === "v1" && v) sigs.push(v);
}
if (!/^\d+$/.test(parts.t || "") || !sigs.length) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t)) > toleranceSec) return false;
const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.`).update(rawBody).digest();
return sigs.some((s) => {
if (!/^[0-9a-f]{64}$/i.test(s)) return false;
const got = Buffer.from(s, "hex");
return got.length === expected.length && crypto.timingSafeEqual(got, expected);
});
}
// Express example: keep the raw body for verification.
// app.post("/webhooks/bookedup", express.raw({ type: "application/json" }), (req, res) => {
// if (!verifyBookedUp(req.body, req.get("BookedUp-Signature"), process.env.BOOKEDUP_WEBHOOK_SECRET)) return res.sendStatus(400);
// const event = JSON.parse(req.body.toString("utf8"));
// res.sendStatus(200); // reply fast, then process event (dedupe on event.id)
// });
Python
import hashlib
import hmac
import time
def verify_bookedup(raw_body: bytes, header: str, secret: str, tolerance_sec: int = 300) -> bool:
"""raw_body: the request body bytes exactly as received, before json.loads."""
if not header:
return False
t, sigs = None, []
for piece in header.split(","):
k, _, v = piece.strip().partition("=")
if k == "t" and v.isdigit():
t = v
elif k == "v1" and v:
sigs.append(v)
if t is None or not sigs:
return False
if abs(int(time.time()) - int(t)) > tolerance_sec:
return False
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(expected, s.lower()) for s in sigs)
# Flask example:
# @app.post("/webhooks/bookedup")
# def bookedup():
# if not verify_bookedup(request.get_data(), request.headers.get("BookedUp-Signature"), SECRET):
# abort(400)
# event = request.get_json()
# return "", 200
PHP
<?php
// $rawBody must be the body exactly as received, before json_decode():
// $rawBody = file_get_contents('php://input');
// $header = $_SERVER['HTTP_BOOKEDUP_SIGNATURE'] ?? null;
function verify_bookedup(string $rawBody, ?string $header, string $secret, int $toleranceSec = 300): bool {
if (!$header) return false;
$t = null;
$sigs = [];
foreach (explode(',', $header) as $piece) {
$kv = explode('=', trim($piece), 2);
if (count($kv) !== 2) continue;
[$k, $v] = $kv;
if ($k === 't' && ctype_digit($v)) $t = $v;
elseif ($k === 'v1' && $v !== '') $sigs[] = strtolower($v);
}
if ($t === null || !$sigs) return false;
if (abs(time() - (int) $t) > $toleranceSec) return false;
$expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
foreach ($sigs as $s) {
if (hash_equals($expected, $s)) return true;
}
return false;
}
Webhooks created by Zapier subscriptions are signed too, but their secret isn't shown; Zapier relies on its own unguessable hook URL.
Delivery & retries
- Reply with any
2xxwithin 10 seconds. Do slow work after you respond. - Redirects are not followed: a
3xxcounts as a failure. We read at most the first 4 KB of your response. - Failed deliveries are retried up to 8 attempts over about a day: right away, then after 1 min, 5 min, 30 min, 2 h, 5 h, 8 h and 8 h (each with ±10% jitter).
- An endpoint that keeps failing (15 failures in a row spanning at least 12 hours) is turned off, its pending deliveries are skipped, and the business gets an email. Turn it back on from the dashboard once fixed.
- Deliveries can arrive more than once or out of order. Use the event
id(also inBookedUp-Event-Id) to ignore duplicates; it stays the same across retries. - For Zapier-style subscriptions, replying
410 Goneremoves the subscription.
Event reference
Sample payloads below are generated from the same code that sends real events.
lead.created
A call (or booking-page request) ended with a real lead. Spam is never sent.
Sample payload
{
"id": "evt_00000000000000000000000000000001",
"type": "lead.created",
"created_at": "2026-11-12T15:00:00.000Z",
"api_version": "2026-11-11",
"data": {
"lead_id": "00000000-0000-4000-8000-000000000001",
"business": {
"id": "00000000-0000-4000-8000-0000000000aa",
"name": "Acme Plumbing"
},
"source": "phone",
"name": "Jane Sample",
"phone": "+16155550123",
"address": "123 Main St, Nashville, TN 37203",
"within_service_area": true,
"issue": "AC is blowing warm air",
"urgency": "soon",
"status": "completed",
"outcome": "callback_requested",
"preferred_time": "Tomorrow morning",
"appointment": null,
"summary": "Sample lead from BookedUp. Caller needs AC service.",
"duration_seconds": 142,
"recording_available": true,
"tags": [],
"custom_answers": {},
"lead_url": "https://getbookedup.ai/dashboard/leads/00000000-0000-4000-8000-000000000001",
"created_at": "2026-11-11T15:04:05.000Z",
"updated_at": null
}
}lead.updated
You edited a lead in the dashboard.
Sample payload
{
"id": "evt_00000000000000000000000000000002",
"type": "lead.updated",
"created_at": "2026-11-12T15:00:00.000Z",
"api_version": "2026-11-11",
"data": {
"lead_id": "00000000-0000-4000-8000-000000000001",
"business": {
"id": "00000000-0000-4000-8000-0000000000aa",
"name": "Acme Plumbing"
},
"source": "phone",
"name": "Jane Sample",
"phone": "+16155550123",
"address": "123 Main St, Nashville, TN 37203",
"within_service_area": true,
"issue": "AC is blowing warm air",
"urgency": "soon",
"status": "completed",
"outcome": "callback_requested",
"preferred_time": "Tomorrow morning",
"appointment": null,
"summary": "Sample lead from BookedUp. Caller needs AC service.",
"duration_seconds": 142,
"recording_available": true,
"tags": [],
"custom_answers": {},
"lead_url": "https://getbookedup.ai/dashboard/leads/00000000-0000-4000-8000-000000000001",
"created_at": "2026-11-11T15:04:05.000Z",
"updated_at": "2026-11-11T15:04:05.000Z"
}
}call.completed
Any call that was not spam ended (including hang-ups and voicemails).
Sample payload
{
"id": "evt_00000000000000000000000000000003",
"type": "call.completed",
"created_at": "2026-11-12T15:00:00.000Z",
"api_version": "2026-11-11",
"data": {
"lead_id": "00000000-0000-4000-8000-000000000001",
"business": {
"id": "00000000-0000-4000-8000-0000000000aa",
"name": "Acme Plumbing"
},
"source": "phone",
"name": "Jane Sample",
"phone": "+16155550123",
"address": "123 Main St, Nashville, TN 37203",
"within_service_area": true,
"issue": "AC is blowing warm air",
"urgency": "soon",
"status": "completed",
"outcome": "callback_requested",
"preferred_time": "Tomorrow morning",
"appointment": null,
"summary": "Sample lead from BookedUp. Caller needs AC service.",
"duration_seconds": 142,
"recording_available": true,
"tags": [],
"custom_answers": {},
"lead_url": "https://getbookedup.ai/dashboard/leads/00000000-0000-4000-8000-000000000001",
"created_at": "2026-11-11T15:04:05.000Z",
"updated_at": null
}
}booking.created
An appointment was booked on your calendar (phone or booking page).
Sample payload
{
"id": "evt_00000000000000000000000000000004",
"type": "booking.created",
"created_at": "2026-11-12T15:00:00.000Z",
"api_version": "2026-11-11",
"data": {
"booking_id": "00000000-0000-4000-8000-000000000002",
"lead_id": "00000000-0000-4000-8000-000000000001",
"business": {
"id": "00000000-0000-4000-8000-0000000000aa",
"name": "Acme Plumbing"
},
"source": "phone",
"status": "confirmed",
"name": "Jane Sample",
"phone": "+16155550123",
"address": "123 Main St, Nashville, TN 37203",
"issue": "AC is blowing warm air",
"service": null,
"appointment_type": null,
"urgency": "soon",
"appointment": {
"start": "2026-11-13T15:00:00.000Z",
"end": "2026-11-13T17:00:00.000Z",
"timezone": "America/Chicago"
},
"cancelled_at": null,
"rescheduled_at": null,
"lead_url": "https://getbookedup.ai/dashboard/leads/00000000-0000-4000-8000-000000000001",
"created_at": "2026-11-11T15:04:05.000Z"
}
}booking.rescheduled
A customer moved their appointment.
Sample payload
{
"id": "evt_00000000000000000000000000000005",
"type": "booking.rescheduled",
"created_at": "2026-11-12T15:00:00.000Z",
"api_version": "2026-11-11",
"data": {
"booking_id": "00000000-0000-4000-8000-000000000002",
"lead_id": "00000000-0000-4000-8000-000000000001",
"business": {
"id": "00000000-0000-4000-8000-0000000000aa",
"name": "Acme Plumbing"
},
"source": "phone",
"status": "confirmed",
"name": "Jane Sample",
"phone": "+16155550123",
"address": "123 Main St, Nashville, TN 37203",
"issue": "AC is blowing warm air",
"service": null,
"appointment_type": null,
"urgency": "soon",
"appointment": {
"start": "2026-11-13T15:00:00.000Z",
"end": "2026-11-13T17:00:00.000Z",
"timezone": "America/Chicago"
},
"previous_appointment": {
"start": "2026-11-12T15:00:00.000Z",
"end": "2026-11-12T17:00:00.000Z",
"timezone": "America/Chicago"
},
"cancelled_at": null,
"rescheduled_at": "2026-11-11T15:04:05.000Z",
"lead_url": "https://getbookedup.ai/dashboard/leads/00000000-0000-4000-8000-000000000001",
"created_at": "2026-11-11T15:04:05.000Z"
}
}booking.cancelled
A customer cancelled their appointment.
Sample payload
{
"id": "evt_00000000000000000000000000000006",
"type": "booking.cancelled",
"created_at": "2026-11-12T15:00:00.000Z",
"api_version": "2026-11-11",
"data": {
"booking_id": "00000000-0000-4000-8000-000000000002",
"lead_id": "00000000-0000-4000-8000-000000000001",
"business": {
"id": "00000000-0000-4000-8000-0000000000aa",
"name": "Acme Plumbing"
},
"source": "phone",
"status": "cancelled",
"name": "Jane Sample",
"phone": "+16155550123",
"address": "123 Main St, Nashville, TN 37203",
"issue": "AC is blowing warm air",
"service": null,
"appointment_type": null,
"urgency": "soon",
"appointment": {
"start": "2026-11-13T15:00:00.000Z",
"end": "2026-11-13T17:00:00.000Z",
"timezone": "America/Chicago"
},
"cancelled_at": "2026-11-11T15:04:05.000Z",
"rescheduled_at": null,
"lead_url": "https://getbookedup.ai/dashboard/leads/00000000-0000-4000-8000-000000000001",
"created_at": "2026-11-11T15:04:05.000Z"
}
}API endpoints
Base URL https://getbookedup.ai/api/integrations/zapier. All endpoints need an API key. Request and response bodies are JSON.
GET /me
Check a key; returns the business it belongs to.
POST /subscribe
Subscribe an HTTPS URL to one event. Body: target_url, event. Returns the subscription id. Up to 50 per business.
curl -X POST https://getbookedup.ai/api/integrations/zapier/subscribe \
-H "Authorization: Bearer $BOOKEDUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"target_url":"https://example.com/hooks/bookedup","event":"lead.created"}'
# 201 {"id":"…","event":"lead.created","target_url":"https://example.com/hooks/bookedup"}DELETE /unsubscribe
Remove a subscription: {"id":"…"} in the body or ?id=. Safe to repeat.
GET /samples/:event
Up to 3 recent real payloads of that event (deduplicated), or a sample if there are none yet (marked "test": true, id evt_test_…). Handy for field mapping.
POST /leads
Create a lead (like Leads > Add Lead). Required: name, phone. Optional: email, address, service_needed, notes, urgency (emergency, soon, standard or flexible). Returns the lead in the same shape as lead.* event data, with source manual; there, service_needed comes back as issue and notes as summary. Addresses are checked with Google Maps like any other lead. Errors name the field you sent (for example name is too long (max 120 characters)).
curl -X POST https://getbookedup.ai/api/integrations/zapier/leads \
-H "Authorization: Bearer $BOOKEDUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Jane Sample","phone":"615-555-0123","service_needed":"Water heater leaking","urgency":"soon"}'GET /leads/search?phone=
Newest lead for a 10-digit US phone number, as a list with zero or one item (spam is never returned).
curl "https://getbookedup.ai/api/integrations/zapier/leads/search?phone=6155550123" \
-H "Authorization: Bearer $BOOKEDUP_API_KEY"Errors & limits
Errors return a JSON body like {"error":"Invalid API key"}:
400: invalid input (the message says what to fix), orInvalid JSON body.401:Missing API key(no key header), orInvalid API key(malformed or revoked).404: not found (or not yours).413: request body over 32 KB.429: too many requests. Each key can make 120 requests per minute. Every response carriesRateLimit-Limit,RateLimit-RemainingandRateLimit-Reset(seconds); a 429 also hasRetry-After.
Zapier
A native Zapier app is on our roadmap. Today you can use Zapier's Webhooks by Zapier (Catch Hook, a paid Zapier feature): paste the Zapier URL as a webhook endpoint in your dashboard and pick your events.
Slack, Discord & Telegram
For alerts in a chat channel you don't need any code: connect Slack, Discord or Telegram under Settings > Integrations. See the Help Center for setup steps.