> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verbeo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone numbers

> Connect the phone numbers your assistants answer and call from — the phone number object, the two ways to add a number, and how the endpoints fit together.

A **phone number** is a number you own at a carrier, connected to Verbeo so an assistant can answer it and place calls from it. Each number names up to two assistants: the one that answers inbound calls, and the one that places outbound calls.

## Endpoints

| Endpoint | Purpose |
| - | - |
| [`POST /phone-number/list`](/api-reference/phone-numbers/list) | List your numbers, paged and searchable |
| [`GET /phone-number/{id}`](/api-reference/phone-numbers/get) | One number |
| [`POST /phone-number/sip`](/api-reference/phone-numbers/connect-sip) | Connect a number over SIP trunking |
| [`POST /phone-number/twilio`](/api-reference/phone-numbers/import-twilio) | Import a number by its Twilio credentials |
| [`POST /phone-number/{id}/twilio-webhook`](/api-reference/phone-numbers/twilio-webhook) | Point an imported Twilio number at Verbeo |
| [`PUT /phone-number/{id}`](/api-reference/phone-numbers/update) | Change the assistants, the dial rate or the inbound webhook |
| [`DELETE /phone-number/{id}`](/api-reference/phone-numbers/delete) | Delete a number |

The workspace comes from your API key, so no endpoint asks you for a workspace id.

<Note>
  Listing is a `POST` because a list query is a document — page, size and a search term, typed as themselves rather than coerced from a query string. It reads, and changes nothing.
</Note>

## Two ways to add a number

| | [SIP trunking](/api-reference/phone-numbers/connect-sip) | [Twilio credentials](/api-reference/phone-numbers/import-twilio) |
| - | - | - |
| Works with | Any carrier that offers a SIP trunk, Twilio Elastic SIP Trunking included | Twilio only |
| You send | The trunk's termination host and, if it has them, its user name and password | Your Twilio Account SID and Auth Token |
| `provider` on the number | `livekit_sip` | `twilio` |
| Inbound calls reach Verbeo when | your carrier sends them to Verbeo's origination URI | you call [`/twilio-webhook`](/api-reference/phone-numbers/twilio-webhook) once |
| [Inbound call webhook](/guides/inbound-call-webhook) | Yes | No |

SIP trunking is the path to choose for a new number. [Import a phone number from Twilio](/guides/import-twilio-number) walks through the carrier side of it.

## The phone number object

```json theme={null}
{
  "id": "7d9f3b52-4c1e-4a8e-9b1a-2f6c0d4e8a11",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "phone_number": "+14155550123",
  "nickname": "Main line",
  "provider": "livekit_sip",
  "is_active": true,
  "max_cps": 1,
  "inbound_agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "outbound_agent_id": null,
  "inbound_webhook_url": null,
  "created_at": "2026-01-15T10:30:00.123456+00:00",
  "updated_at": "2026-01-22T14:00:00.654321+00:00",
  "inbound_agent_name": "Customer Support",
  "outbound_agent_name": null
}
```

<ResponseField name="id" type="string" required>UUID of the phone number.</ResponseField>
<ResponseField name="workspace_id" type="string" required>UUID of your workspace.</ResponseField>
<ResponseField name="phone_number" type="string" required>The number in E.164 format, e.g. `+14155550123`. A number can be connected to Verbeo once, in one workspace.</ResponseField>
<ResponseField name="nickname" type="string | null" required>Your label for the number, up to 100 characters.</ResponseField>
<ResponseField name="provider" type="string" required>`livekit_sip` for a number connected over SIP trunking, `twilio` for one imported by its Twilio credentials.</ResponseField>
<ResponseField name="is_active" type="boolean" required>Only an active number can place calls.</ResponseField>
<ResponseField name="max_cps" type="number" required>How many calls per second Verbeo dials from this number. `1` for a new number; at least `0.1`.</ResponseField>
<ResponseField name="inbound_agent_id" type="string | null" required>The assistant that answers calls to this number. `null`: nobody answers.</ResponseField>
<ResponseField name="outbound_agent_id" type="string | null" required>The assistant that places calls from this number when a call names none.</ResponseField>
<ResponseField name="inbound_agent_name" type="string | null" required>That assistant's name, for display.</ResponseField>
<ResponseField name="outbound_agent_name" type="string | null" required>That assistant's name, for display.</ResponseField>
<ResponseField name="inbound_webhook_url" type="string | null" required>The [inbound call webhook](/guides/inbound-call-webhook) of a SIP-trunk number. `null`: switched off.</ResponseField>
<ResponseField name="created_at" type="string" required>ISO 8601 timestamp with microseconds and a UTC offset, e.g. `2026-01-15T10:30:00.123456+00:00`.</ResponseField>
<ResponseField name="updated_at" type="string" required>The last change, in the same format.</ResponseField>

<Note>
  A number's credentials and trunk details are write-only: the Twilio Account SID and Auth Token, and a SIP trunk's termination URI, transport, user name and password are stored when the number is added and never returned.
</Note>

## Placing a call from a number

A number is what an outbound call is placed from. See [Create phone call](/api-reference/calls/create).

## Authentication

Every endpoint takes a **private** workspace API key (`vbr_…`) as a Bearer token. Public widget keys (`vbr_pub_…`) are rejected with `403 FORBIDDEN` — they ship inside web pages, where anyone can read them. See [Authentication](/api-reference/authentication).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.