Phone numbers

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`	List your numbers, paged and searchable
`GET /phone-number/{id}`	One number
`POST /phone-number/sip`	Connect a number over SIP trunking
`POST /phone-number/twilio`	Import a number by its Twilio credentials
`POST /phone-number/{id}/twilio-webhook`	Point an imported Twilio number at Verbeo
`PUT /phone-number/{id}`	Change the assistants, the dial rate or the inbound webhook
`DELETE /phone-number/{id}`	Delete a number

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

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.

Two ways to add a number

	SIP trunking	Twilio credentials
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` once
Inbound call webhook	Yes	No

SIP trunking is the path to choose for a new number. Import a phone number from Twilio walks through the carrier side of it.

The phone number object

{
  "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
}

string

required

UUID of the phone number.

string

required

UUID of your workspace.

string

required

The number in E.164 format, e.g. +14155550123. A number can be connected to Verbeo once, in one workspace.

string | null

required

Your label for the number, up to 100 characters.

string

required

livekit_sip for a number connected over SIP trunking, twilio for one imported by its Twilio credentials.

boolean

required

Only an active number can place calls.

number

required

How many calls per second Verbeo dials from this number. 1 for a new number; at least 0.1.

string | null

required

The assistant that answers calls to this number. null: nobody answers.

string | null

required

The assistant that places calls from this number when a call names none.

string | null

required

That assistant’s name, for display.

string | null

required

That assistant’s name, for display.

string | null

required

The inbound call webhook of a SIP-trunk number. null: switched off.

string

required

ISO 8601 timestamp with microseconds and a UTC offset, e.g. 2026-01-15T10:30:00.123456+00:00.

string

required

The last change, in the same format.

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.

Placing a call from a number

A number is what an outbound call is placed from. See Create phone call.

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.

Overview

Assistants

Tools

Calls

Campaigns

Webhooks

Phone numbers

Endpoints

Two ways to add a number

The phone number object

Placing a call from a number

Authentication

​Endpoints

​Two ways to add a number

​The phone number object

​Placing a call from a number

​Authentication

Endpoints

Two ways to add a number

The phone number object

Placing a call from a number

Authentication