Bookings
Your account's bookings by reservation date: who, when, for how many and in which status.
The bookings endpoints return your account’s bookings: when the reservation is for, for how many people, its status, the guest’s details and the agent that took it. They need the bookings:read scope.
| Endpoint | Route | Scope |
|---|---|---|
| List bookings | GET /v1/bookings |
bookings:read |
| One booking | GET /v1/bookings/{booking_id} |
bookings:read |
In the examples, $BASE is https://api.bookline.ai/v1 and $BOOKLINE_API_KEY is your key, as in the quick start.
List bookings
Section titled “List bookings”GET /v1/bookings returns the bookings whose reservation falls in a window of days, earliest first. The window is on the time the reservation is for, not on when the booking was made.
| Parameter | Type | Default | Rules |
|---|---|---|---|
from |
date YYYY-MM-DD |
required | First day of the window, inclusive, in timezone |
to |
date YYYY-MM-DD |
required | Last day, inclusive; not before from; at most 31 days |
timezone |
IANA name | UTC |
e.g. Europe/Madrid; days start and end in that zone |
venue_ids |
UUID, repeatable | all your venues | At most 100; only the bookings taken by those venues’ agents |
agent_ids |
string, repeatable | all your agents | At most 100; only the bookings taken by those agents |
limit |
1 to 100 | 50 | Bookings per page |
cursor |
string | none | meta.next_cursor of the previous page, with the same filters and the same limit |
customer_id |
UUID | the key’s customer | See what each key reads |
curl -s -H "apikey: $BOOKLINE_API_KEY" \ "$BASE/bookings?from=2026-11-01&to=2026-11-30&timezone=Europe/Madrid"# repeat with &cursor=<meta.next_cursor> until next_cursor is null{ "data": [ { "id": "…", "status": "confirmed", "reservation_at": "2026-11-14T20:30:00Z", "diners": 4, "guest_name": "Ana García", "guest_phone": "+34600111222", "guest_email": null, "language": "SPANISH", "comments": "", "contact_id": "…", "agent_id": "…", "venue_id": "…", "created_at": "2026-11-10T11:02:44Z", "updated_at": "2026-11-10T11:02:51Z" } ], "meta": { "limit": 50, "next_cursor": "…" }}| Field | What it is |
|---|---|
id |
The booking’s identifier |
status |
Where the booking stands: confirmed, pending (waiting for the venue), pending_user_data, pending_propagation, submitted_to_backend (waiting for the reservation system), no_availability, propagation_failed, contacted, client_cancelled (cancelled by the guest) or source_cancelled (cancelled by the venue or its reservation system); others may appear |
reservation_at |
When the reservation is for |
diners |
How many people it is for |
guest_name, guest_phone, guest_email |
The guest’s name, phone (E.164) and email |
language |
The language the guest booked in: SPANISH, CATALAN, ENGLISH… |
comments |
What the guest asked for, in their words. May contain health data |
contact_id |
The guest’s contact, when the phone matched one |
agent_id |
The agent that took it; null for a booking made without one or by an agent that is not yours |
venue_id |
The venue of that agent, when it serves one venue |
created_at, updated_at |
When the booking was made and last changed |
One booking
Section titled “One booking”GET /v1/bookings/{booking_id} returns the same fields for one booking. A booking that is not your customer’s, or outside the venues your key is limited to, is 404 not_found.
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/bookings/<booking_id>"Data rules
Section titled “Data rules”- Which bookings are yours. A booking in your account’s Bookline reservation book is yours, whichever agent took it. Any other booking is yours when one of your agents took it: the account that owned the agent when the booking was made. If an agent moves to another Bookline account, its earlier bookings stay with the previous owner.
agent_idandvenue_idonly while the agent is yours. They arenullwhen the agent that took the booking is not yours, or no longer is.- The window is on the reservation. A booking made today for next month appears in next month’s window. To follow changes, read again:
statusandupdated_atchange as the booking does. - Venue-restricted keys. The key lists only the bookings taken by those venues’ agents, and a
venue_idsoutside them is 403insufficient_scope. - Read only. Bookings are not changed through the API.
Related
Section titled “Related”- Contacts: the guests behind the bookings.
- Endpoints: reservation counts and diners by day.
- Errors and rate limits.
