Endpoints
Every route of the Bookline API with its method and scope, plus venues and the five metrics resources: parameters, example requests and what each one returns.
Every route lives under https://api.bookline.ai/v1. In the examples, $BASE is that URL and $BOOKLINE_API_KEY is your key, as in the quick start.
All routes
Section titled “All routes”| Domain | Method and route | What it does | Scope |
|---|---|---|---|
| Metrics | GET /v1/metrics/summary |
Headline figures | metrics:read |
GET /v1/metrics/conversion-funnel |
From calls to confirmed bookings | metrics:read |
|
GET /v1/metrics/calls-breakdown |
Calls by reason, language and country | metrics:read |
|
GET /v1/metrics/reservations |
Reservations and diners by visit day (restaurants) | metrics:read |
|
GET /v1/metrics/survey-ratings |
Survey answers, one row each (restaurants) | metrics:read |
|
| Venues | GET /v1/venues |
Your venues and their ids | venues:read or metrics:read |
GET /v1/venues/{venue_id} |
One venue’s detail | venues:read |
|
PATCH /v1/venues/{venue_id} |
Change its name, website or contact details | venues:write |
|
| Calls | GET /v1/calls |
Calls your agents answered in a window | calls:read |
GET /v1/calls/{call_id} |
One call with its transcript | calls:read |
|
| Chats | GET /v1/chats |
WhatsApp conversations started in a window | chats:read |
GET /v1/chats/{chat_id} |
One conversation with its messages | chats:read |
|
| Bookings | GET /v1/bookings |
Bookings whose reservation falls in a window | bookings:read |
GET /v1/bookings/{booking_id} |
One booking | bookings:read |
|
| Contacts | GET /v1/contacts |
Your contacts | contacts:read |
GET /v1/contacts/{contact_id} |
One contact | contacts:read |
|
POST /v1/contacts |
Add a contact | contacts:write |
|
PATCH /v1/contacts/{contact_id} |
Change a contact | contacts:write |
|
| Agents | GET /v1/agents |
Your agents | bots:read |
GET /v1/agents/{agent_id} |
One agent | bots:read |
|
PATCH /v1/agents/{agent_id} |
Rename an agent | bots:write |
|
| Knowledge bases | GET /v1/knowledge-bases |
Your knowledge bases | knowledge_bases:read |
GET /v1/knowledge-bases/{knowledge_base_id} |
One knowledge base | knowledge_bases:read |
|
POST /v1/knowledge-bases |
Create a text knowledge base | knowledge_bases:write |
|
PATCH /v1/knowledge-bases/{knowledge_base_id} |
Change a text knowledge base | knowledge_bases:write |
|
DELETE /v1/knowledge-bases/{knowledge_base_id} |
Delete a text knowledge base | knowledge_bases:write |
|
| Campaigns | GET /v1/campaigns |
Your campaigns | notifications:read |
GET /v1/campaigns/{campaign_id} |
One campaign | notifications:read |
|
PATCH /v1/campaigns/{campaign_id} |
Pause a campaign | notifications:write |
|
GET /v1/campaigns/{campaign_id}/runs |
A campaign’s runs | notifications:read |
|
GET /v1/campaigns/{campaign_id}/runs/{run_id} |
One run | notifications:read |
|
| Phone numbers | GET /v1/numbers |
Your phone numbers | numbers:read |
GET /v1/numbers/{number_id} |
One number | numbers:read |
|
| Integrations | GET /v1/integrations |
The integrations you installed | integrations:read |
GET /v1/integrations/{integration_id} |
One integration | integrations:read |
|
| Team members | GET /v1/users |
Your team and their access | users:read |
GET /v1/users/{user_id} |
One team member | users:read |
|
PATCH /v1/users/{user_id} |
Replace a team member’s access | users:write |
|
DELETE /v1/users/{user_id} |
Remove a team member | users:write |
|
| Billing | GET /v1/billing/accounts |
Your billing accounts | billing:read |
GET /v1/billing/accounts/{account_id} |
One billing account | billing:read |
|
GET /v1/billing/invoices |
Your invoices and credit notes | billing:read |
|
GET /v1/billing/invoices/{invoice_id} |
One invoice | billing:read |
|
GET /v1/billing/services |
The services you contracted | billing:read |
Each domain’s page has its parameters, fields and rules; the writes (POST, PATCH, DELETE) share the rules in Writing data. The full field list with descriptions is in the interactive reference.
Lists and paging
Section titled “Lists and paging”Lists answer {"data": [...], "meta": {"limit": ..., "next_cursor": ...}}. To read the next page, send meta.next_cursor as cursor, with the same filters and the same limit; stop when next_cursor is null. A cursor used with other filters, another limit or another customer is 400 invalid_query.
- Lists that grow while you page (calls, chats, bookings, contacts, campaign runs) never repeat a row because of new ones. A contact added while you page may be left out: it shows up in the next listing.
- The other lists (agents, knowledge bases, campaigns, numbers, integrations, team members, billing) can repeat a row created while you page: keep one per
id. A page can hold fewer rows thanlimit, even none, and still have anext_cursor: keep going until it isnull.
The rest of this page covers the venues list and the metrics.
Query parameters
Section titled “Query parameters”Every metrics request needs from and to; the rest are optional. Repeat a list parameter for several values: ?venue_ids=A&venue_ids=B.
| 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 |
granularity |
total | day |
total |
day adds one row per day; window at most 31 days (day) or 92 days (total) |
timezone |
IANA name | UTC |
e.g. Europe/Madrid; must have a whole-hour UTC offset over the window (Asia/Kolkata is rejected) |
venue_ids |
UUID, repeatable | all your venues | At most 100; ids from GET /venues |
channels |
repeatable | every channel | PHONE, WHATSAPP, TERMINAL, INSTAGRAM, WEB; not on reservations or survey-ratings |
industry |
RESTAURANTS | LODGING |
inferred | Needed only when the customer has both restaurant and hotel agents |
customer_id |
UUID | the key’s customer | See what each key reads |
limit |
1 to 5000 | 500 | survey-ratings only: rows per page |
cursor |
string | none | survey-ratings only: meta.next_cursor of the previous page |
Which parameters each endpoint accepts:
| Endpoint | Parameters |
|---|---|
| venues | customer_id |
| summary, conversion-funnel, calls-breakdown | from, to, granularity, timezone, venue_ids, channels, industry, customer_id |
| reservations | from, to, granularity, timezone, venue_ids, industry, customer_id |
| survey-ratings | from, to, timezone, venue_ids, industry, customer_id, limit, cursor |
A parameter the endpoint does not accept is a 400 invalid_query (for example channels on reservations, or a typo such as venue_id). Unknown parameters are never silently ignored.
Response format
Section titled “Response format”Metrics responses share one envelope: data.total holds the window’s figures, data.days one entry per day (only with granularity=day, otherwise null), and meta describes the request.
{ "data": { "total": { ... }, "days": [{ "date": "2026-10-01", ... }] }, "meta": { "customer_id": "...", "industry": "RESTAURANTS", "from": "2026-10-01", "to": "2026-10-31", "timezone": "Europe/Madrid", "granularity": "day", "api_version": "v1", "generated_at": "...", "next_cursor": null }}Venues
Section titled “Venues”GET /v1/venues returns, in data[], the id and name of the venues your key reads. Use those ids in venue_ids. Accepts only customer_id.
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/venues"{ "data": [ { "id": "...", "name": "..." } ]}GET /v1/venues/{venue_id} returns one venue’s detail, and PATCH changes it: see Venues.
Summary
Section titled “Summary”GET /v1/metrics/summary returns calls, duration, callers, booking intents, transfers, bookings, diners, cancellations, visits, value and ROI. For restaurants and hotels.
curl -s -H "apikey: $BOOKLINE_API_KEY" \ "$BASE/metrics/summary?from=2026-10-01&to=2026-10-31&granularity=day&timezone=Europe/Madrid"- Booking and money fields are for restaurants only.
- Value fields (
estimated_value,roi, …) are incurrency;costis incost_currency(EUR). estimated_value=booking_diners×avg_ticket_price.
Conversion funnel
Section titled “Conversion funnel”GET /v1/metrics/conversion-funnel returns sessions per funnel stage, unique callers, recovered diners and revenue. For restaurants and hotels.
curl -s -H "apikey: $BOOKLINE_API_KEY" \ "$BASE/metrics/conversion-funnel?from=2026-10-01&to=2026-10-31&timezone=Europe/Madrid"- Stages that don’t apply to your industry are
null. recovered_revenueis in the summary’scurrency.
Calls breakdown
Section titled “Calls breakdown”GET /v1/metrics/calls-breakdown returns total_calls, by_reason and by_language, plus by_country in the total. For restaurants and hotels.
For example, narrowed to two venues and only phone calls:
curl -s -H "apikey: $BOOKLINE_API_KEY" \ "$BASE/metrics/calls-breakdown?from=2026-10-01&to=2026-10-31&venue_ids=<venue-1>&venue_ids=<venue-2>&channels=PHONE"- For hotels
by_reasonadds up tototal_calls; for restaurants only intent types are counted, so it can add up to less. by_languagealways adds up (UNKNOWNwhen no language was detected).
Reservations
Section titled “Reservations”GET /v1/metrics/reservations returns reservations and diners by visit date, no-shows and the no-show rate. Restaurants only.
curl -s -H "apikey: $BOOKLINE_API_KEY" \ "$BASE/metrics/reservations?from=2026-10-01&to=2026-10-31&timezone=Europe/Madrid"- Counts bookings still valid at the POS whose visit falls in the window, not bookings made in it.
no_show_rateis 0 to 100,nullwithout fulfilled bookings.- Does not accept
channels.
Survey ratings
Section titled “Survey ratings”GET /v1/metrics/survey-ratings returns, in data.rows[], each post-visit survey answer, newest first, with rated_at, phone, score, min_score, max_score, bot_id and venue_id. Restaurants only.
Page through the ratings:
curl -s -H "apikey: $BOOKLINE_API_KEY" \ "$BASE/metrics/survey-ratings?from=2026-10-01&to=2026-10-31&limit=500"# repeat with &cursor=<meta.next_cursor> until next_cursor is nullgranularity=totalonly;granularity=dayis a 400granularity_not_supported.- Page with
limitandmeta.next_cursoruntil it isnull. - Does not accept
channels.
Data rules
Section titled “Data rules”- Days are cut in your timezone. A day runs from 00:00 to 24:00 in
timezone, built from hourly data; that is why the zone needs a whole-hour offset. Days with no activity are returned as zeros. - Totals vs days.
days[]carries only the fields that add up across days. Figures that don’t add up, such as distinct callers, unique callers,by_country, visits, no-shows and every money field, appear only indata.total. - Visits vs bookings. Summary
bookingsandbooking_dinerscount bookings made in the window;visitsand the reservations endpoint count bookings whose visit falls in the window. - Money with
venue_ids.currency,avg_ticket_price,estimated_valueandrecovered_revenueare computed over the requested venues.cost,cost_currency,roi,revenue_per_euroandnet_profit_per_euroarenull: the subscription cost belongs to the whole account, not to a venue. - Agents that moved to your account. If one of your agents belonged to another Bookline customer before, it counts only from the hour it moved to you (rounded up to the next whole hour, UTC). Nothing it did for the previous owner is ever returned. If every agent moved in after your window, the API answers 404 with
available_from, the first date that has data. - API vs dashboard. The API uses the same metrics as the portal dashboard, so numbers match for the same window and filters. The one difference: the dashboard still shows the full history of an agent that moved accounts.
