Bookings

A booking is a meeting your AI agent booked inside the conversation, on your connected calendar. The API lists them read-only, most recent slot first.

Endpoints

Method	Path	Scope
GET	`/bookings`	`bookings:read`

List bookings

curl "https://app.whatsetter.com/api/v1/bookings?since=2026-09-01T00:00:00Z&limit=25" \
  -H "Authorization: Bearer ws_live_…"

const res = await fetch(
  'https://app.whatsetter.com/api/v1/bookings?since=2026-09-01T00:00:00Z&limit=25',
  { headers: { Authorization: 'Bearer ws_live_…' } },
);
const { data: bookings, pagination } = await res.json();

import requests

r = requests.get(
    "https://app.whatsetter.com/api/v1/bookings",
    params={"since": "2026-09-01T00:00:00Z", "limit": 25},
    headers={"Authorization": "Bearer ws_live_…"},
)
bookings = r.json()["data"]

{
  "data": [
    {
      "id": "66f1a2b3c4d5e6f7a8b9c0f5",
      "status": "booked",
      "lead_id": "33612345678@c.us",
      "campaign_id": "acme-france-1-ab12",
      "provider": "calendly",
      "source": "chat",
      "start_at": "2026-09-23T13:00:00.000Z",
      "end_at": "2026-09-23T13:30:00.000Z",
      "timezone": "Europe/Paris",
      "attendee": {
        "name": "Julien",
        "email": "julien@example.com",
        "phone": "+33612345678"
      },
      "cancel_url": "https://calendly.com/cancellations/…",
      "reschedule_url": "https://calendly.com/reschedulings/…",
      "canceled_at": null,
      "cancellation_reason": null,
      "created_at": "2026-09-18T16:45:00.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": "66f1a2b3c4d5e6f7a8b9c0f5" }
}

Parameter	What it does
`status`	Exact match on a status below.
`campaign_id`	The campaign’s slug or its `id`.
`since`	Only bookings starting at or after this ISO 8601 date.
`limit`, `cursor`	Pagination, 1 to 100 per page.

Fields and statuses

Field	Meaning
`status`	`booked`, `canceled`, `rescheduled`, `failed` or `no_show`.
`lead_id`	The lead’s WhatsApp id (`33612345678@c.us`), the same value as `whatsapp_id` on a lead. To open the lead, call `GET /leads?phone=+33612345678`.
`campaign_id`	The campaign slug.
`provider`	The calendar provider the meeting lives in.
`source`	How it was booked: `chat` (by the agent in the conversation), `static_link` (the lead used the booking link), `webhook` (reported by the provider), `manual`.
`start_at`, `end_at`	UTC. Display them in `timezone`.
`attendee`	Name, email and phone the lead gave at booking time.
`canceled_at`, `cancellation_reason`	Set when the meeting was canceled.

The list is ordered by start_at, most recent slot first, so upcoming meetings come before past ones.

The links are secrets

cancel_url and reschedule_url are capability links generated by the calendar provider: anyone who holds one can cancel or move the meeting, no login needed. Treat them like passwords: store them encrypted, never log them, never show them to someone who could not act on the meeting. They are null when the provider gave none.

Errors you will meet

HTTP	`code`	When
401	`missing_api_key`, `invalid_api_key`	Key absent, unknown or revoked.
403	`insufficient_scope`	The key lacks `bookings:read`.
422	`validation_error`	`since` is not an ISO 8601 date, `limit` out of 1 to 100, invalid or expired cursor.
429	`rate_limited`	Too many requests this minute. Honor `Retry-After`.