Skip to content

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.

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
Ventana de terminal
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

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.

Ventana de terminal
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/bookings/<booking_id>"
  • 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_id and venue_id only while the agent is yours. They are null when 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: status and updated_at change as the booking does.
  • Venue-restricted keys. The key lists only the bookings taken by those venues’ agents, and a venue_ids outside them is 403 insufficient_scope.
  • Read only. Bookings are not changed through the API.