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:

http
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:

bash
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:

http
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.created

The body is an envelope (version 2026-11-11; changes within a version are additive only):

json
{
  "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 source is phone, booking_page or manual (added by hand, in the dashboard or with POST /leads). A hand-added lead has status manual and, until you set one, outcome lead.
  • Real event ids are evt_ plus 32 hex characters. Test events (Send test event) and the samples from GET /samples/:event have ids starting with evt_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 v1 value 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

javascript
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

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
<?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 2xx within 10 seconds. Do slow work after you respond.
  • Redirects are not followed: a 3xx counts 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 in BookedUp-Event-Id) to ignore duplicates; it stays the same across retries.
  • For Zapier-style subscriptions, replying 410 Gone removes 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
json
{
  "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
json
{
  "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
json
{
  "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
json
{
  "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
json
{
  "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
json
{
  "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.

bash
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)).

bash
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).

bash
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), or Invalid JSON body.
  • 401: Missing API key (no key header), or Invalid 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 carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds); a 429 also has Retry-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.