Skip to content

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.

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 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 than limit, even none, and still have a next_cursor: keep going until it is null.

The rest of this page covers the venues list and the metrics.

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.

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
}
}

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.

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

GET /v1/metrics/summary returns calls, duration, callers, booking intents, transfers, bookings, diners, cancellations, visits, value and ROI. For restaurants and hotels.

Ventana de terminal
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 in currency; cost is in cost_currency (EUR).
  • estimated_value = booking_diners × avg_ticket_price.

GET /v1/metrics/conversion-funnel returns sessions per funnel stage, unique callers, recovered diners and revenue. For restaurants and hotels.

Ventana de terminal
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_revenue is in the summary’s currency.

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:

Ventana de terminal
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_reason adds up to total_calls; for restaurants only intent types are counted, so it can add up to less.
  • by_language always adds up (UNKNOWN when no language was detected).

GET /v1/metrics/reservations returns reservations and diners by visit date, no-shows and the no-show rate. Restaurants only.

Ventana de terminal
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_rate is 0 to 100, null without fulfilled bookings.
  • Does not accept channels.

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:

Ventana de terminal
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 null
  • granularity=total only; granularity=day is a 400 granularity_not_supported.
  • Page with limit and meta.next_cursor until it is null.
  • Does not accept channels.
  • 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 in data.total.
  • Visits vs bookings. Summary bookings and booking_diners count bookings made in the window; visits and the reservations endpoint count bookings whose visit falls in the window.
  • Money with venue_ids. currency, avg_ticket_price, estimated_value and recovered_revenue are computed over the requested venues. cost, cost_currency, roi, revenue_per_euro and net_profit_per_euro are null: 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.