Skip to content

Phone numbers

The phone lines your agents answer: type, status and who holds each line.

The phone numbers endpoints return the lines your agents answer. They need the numbers:read scope.

Endpoint Route Scope
List numbers GET /v1/numbers numbers:read
One number GET /v1/numbers/{number_id} numbers:read

Numbers belong to the whole customer: a key limited to some venues gets 403 insufficient_scope. In the examples, $BASE is https://api.bookline.ai/v1 and $BOOKLINE_API_KEY is your key, as in the quick start.

GET /v1/numbers returns your numbers, paged.

Parameter Type Default Rules
type PSTN | VIRTUAL both Only numbers of this type
status ACTIVE | BLOCKED | INACTIVE | PENDING_DELETION all Only numbers in this status
limit 1 to 100 50 Numbers 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/numbers?status=ACTIVE"
{
"data": [
{
"id": "…",
"phone_number": "+34910000000",
"virtual_id": null,
"type": "PSTN",
"status": "ACTIVE",
"ownership": "BOOKLINE"
}
],
"meta": { "limit": 50, "next_cursor": null }
}
Field What it is
id The number’s identifier
phone_number The number in E.164, e.g. +34910000000; null for a number that is not PSTN
virtual_id The id a VIRTUAL number is reached by on your switchboard, if one
type PSTN: a phone line on the public network; VIRTUAL: reached through a switchboard
status ACTIVE: in service; BLOCKED: in service but not assignable; INACTIVE; PENDING_DELETION
ownership BOOKLINE: Bookline holds the line with the carrier; CUSTOMER: you hold it and Bookline only routes it

GET /v1/numbers/{number_id} returns the same fields. A number that is not your customer’s is 404 not_found.

  • Only the fields on this page. Carrier and routing settings are not part of the API.
  • Read only. Numbers are managed in the portal or by Bookline.
  • Calls: called_number is one of these numbers.
  • Agents: the agents that answer them.