Calls
The calls your agents answer, with their transcript: parameters, paging and what each endpoint returns.
The calls endpoints return the phone calls your agents answered: who called, which number they dialled, how the call ended and, in the detail, the conversation turn by turn. They need the calls:read scope.
| Endpoint | Route | Scope |
|---|---|---|
| List calls | GET /v1/calls |
calls:read |
| One call with its transcript | GET /v1/calls/{call_id} |
calls:read |
In the examples, $BASE is https://api.bookline.ai/v1 and $BOOKLINE_API_KEY is your key, as in the quick start.
List calls
Section titled “List calls”GET /v1/calls returns the calls your agents answered in a window of days, newest first, without their transcript.
| 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 calls of those venues’ agents (ids from GET /venues) |
agent_ids |
string, repeatable | all your agents | At most 100; only the calls of those agents |
limit |
1 to 100 | 50 | Calls 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/calls?from=2026-10-01&to=2026-10-31&timezone=Europe/Madrid&limit=50"# repeat with &cursor=<meta.next_cursor> until next_cursor is null{ "data": [ { "id": "…", "started_at": "2026-10-31T18:42:10Z", "caller_number": "+34600111222", "called_number": "+34910000000", "disposition": "CONNECTED", "agent_id": "…", "tags": [] } ], "meta": { "limit": 50, "next_cursor": "…" }}| Field | What it is |
|---|---|
id |
The call’s identifier; pass it to GET /v1/calls/{call_id} |
started_at |
When the call started (UTC) |
caller_number |
The number that called |
called_number |
The number they dialled |
disposition |
How it ended. Always CONNECTED today: only calls an agent answered are served |
agent_id |
The agent that answered. Always present today |
tags |
The call’s tags |
One call with its transcript
Section titled “One call with its transcript”GET /v1/calls/{call_id} returns the same fields plus transcript[]: the conversation, turn by turn.
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/calls/<call_id>"{ "id": "…", "started_at": "2026-10-31T18:42:10Z", "caller_number": "+34600111222", "called_number": "+34910000000", "disposition": "CONNECTED", "agent_id": "…", "tags": [], "transcript": [ { "at": "2026-10-31T18:42:12Z", "caller_said": "A table for two tonight", "agent_said": ["Sure, what time would you like to come?"] } ]}| Field | What it is |
|---|---|
transcript[].at |
When the turn started |
transcript[].caller_said |
The caller’s words, or the digits they pressed; null when they said nothing |
transcript[].agent_said |
What the agent answered, in order |
A call that is not your customer’s, or that does not exist, is 404 not_found.
Data rules
Section titled “Data rules”- Days are cut in your timezone. The window runs from 00:00 on
fromto 24:00 ontointimezone. - The calls are your agents’ calls. A call that never reached an agent (
dispositionother thanCONNECTED, noagent_id) is not part of the API: neither listed nor readable by id. - A cursor belongs to its query. A
cursoronly works with the same filters and the samelimitas the page that returned it; with others, the answer is 400invalid_query. If you change the filters, start again withoutcursor. - Paging up to today is safe. Each page resumes right after the last call of the previous one, so calls that arrive while you page never repeat or shift a row. Stop when
next_cursorisnull. - When you sync, overlap the window. A call shows up when it ends, with the time it started: a long call that started before your last sync can appear after it. If you sync daily, also ask for the previous day and keep one per
id. - Venue-restricted keys. If your portal access is limited to some venues, the key lists only the calls of those venues’ agents, and a
venue_idsoutside them is 403insufficient_scope.
