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.
List numbers
Section titled “List numbers”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 |
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 |
One number
Section titled “One number”GET /v1/numbers/{number_id} returns the same fields. A number that is not your customer’s is 404 not_found.
Data rules
Section titled “Data rules”- 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.
