Skip to content

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.

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

GET /v1/calls/{call_id} returns the same fields plus transcript[]: the conversation, turn by turn.

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

  • Days are cut in your timezone. The window runs from 00:00 on from to 24:00 on to in timezone.
  • The calls are your agents’ calls. A call that never reached an agent (disposition other than CONNECTED, no agent_id) is not part of the API: neither listed nor readable by id.
  • A cursor belongs to its query. A cursor only works with the same filters and the same limit as the page that returned it; with others, the answer is 400 invalid_query. If you change the filters, start again without cursor.
  • 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_cursor is null.
  • 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_ids outside them is 403 insufficient_scope.