# Bookings

> List the meetings your agent booked in chat, with their status, attendee and calendar links, and sync them with your CRM.

Source: https://docs.whatsetter.com/developers/guides/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`](/api-reference/operations/listbookings/) | `bookings:read` |

## List bookings

**cURL**

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

**JavaScript**

```js
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();
```

**Python**

```python
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"]
```

```json
{
  "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`. |

## Related

- [Leads](/developers/guides/leads/)
- [Meetings in the dashboard](/dashboard/bookings/)
- [Signed webhooks](/developers/webhooks/)
