Phone Numbers APIs | LiveKit docs

Overview

LiveKit provides Phone Numbers APIs that let you search for, purchase, and manage phone numbers for your SIP apps. These APIs are available with LiveKit server SDKs and CLI:

Important

Requests to the Phone Number API require the SIP admin permission unless otherwise noted. To create a token with the appropriate grant, see SIP grant.

To learn more about additional APIs, see SIP APIs and Server APIs.

Using endpoints

The Phone Number API is accessible via /twirp/livekit.PhoneNumberService/<MethodName>. For example, if you're using LiveKit Cloud the following URL is for the SearchPhoneNumbers API endpoint:

https://<your LiveKit URL domain>/twirp/livekit.PhoneNumberService/SearchPhoneNumbers

Authorization header

All endpoints require a signed access token. This token should be set via HTTP header:

Authorization: Bearer <token>

LiveKit server SDKs automatically include the above header.

Post body

Twirp expects an HTTP POST request. The body of the request must be a JSON object (application/json) containing parameters specific to that request. Use an empty {} body for requests that don't require parameters.

Examples

Search available phone numbers using SearchPhoneNumbers API endpoint:

curl -X POST https://<your LiveKit URL domain>/twirp/livekit.PhoneNumberService/SearchPhoneNumbers \
	-H "Authorization: Bearer <token-with-sip-admin>" \
	-H 'Content-Type: application/json' \
	-d '{ "country_code": "US", "area_code": "415", "limit": 10 }'

Purchase a phone number using PurchasePhoneNumber API endpoint:

curl -X POST https://<your LiveKit URL domain>/twirp/livekit.PhoneNumberService/PurchasePhoneNumber \
	-H "Authorization: Bearer <token-with-sip-admin>" \
	-H 'Content-Type: application/json' \
	-d '{ "phone_numbers": ["+14155551234"] }'

PhoneNumberService APIs

The PhoneNumberService APIs allow you to manage phone numbers for your LiveKit project, including searching, purchasing, and releasing phone numbers.

Tip

All RPC definitions and options can be found here.

SearchPhoneNumbers

Search available phone numbers in inventory.

Returns SearchPhoneNumbersResponse.

Parameter	Type	Required	Description
country_code	string	yes	Filter by country code (for example, "US", "CA").
area_code	string		Filter by area code (for example, "415").
limit	int32		Maximum number of results (default: 50).

PurchasePhoneNumber

Purchase a phone number from inventory.

Returns PurchasePhoneNumberResponse.

Parameter	Type	Required	Description
phone_numbers	string	yes	Phone numbers to purchase (for example, "+16505550010").
sip_dispatch_rule_id	string		SIP dispatch rule ID to apply to all purchased numbers.

ListPhoneNumbers

List phone numbers for a project.

Returns ListPhoneNumbersResponse.

Parameter Type Required Description

limit int32 Maximum number of results (default: 50).

Parameter	Type	Description
limit	int32	Maximum number of results (default: 50).
statuses	PhoneNumberStatus	Filter by status. Multiple statuses can be specified. Valid values are: `active` `pending` `released`
sip_dispatch_rule_id	string	Filter by SIP dispatch rule ID.

statuses

PhoneNumberStatus

Filter by status. Multiple statuses can be specified. Valid values are:

active
pending
released

sip_dispatch_rule_id string Filter by SIP dispatch rule ID.

GetPhoneNumber

Get a phone number from a project by ID or phone number string.

Returns GetPhoneNumberResponse.

Parameter	Type	Required	Description
id	string		Use phone number ID for direct lookup. Required if `phone_number` is not provided.
phone_number	string		Use phone number string for lookup. (for example, "+16505550010"). Required if `id` is not provided.

UpdatePhoneNumber

Update the SIP dispatch rule ID for a phone number in a project.

Returns UpdatePhoneNumberResponse.

Parameter	Type	Description
id	string	Use phone number ID for direct lookup. Required if `phone_number` is not provided.
phone_number	string	Use phone number string for lookup (for example, "+16505550010"). Required if `id` is not provided.
sip_dispatch_rule_id	string	SIP dispatch rule ID to assign to the phone number.

ReleasePhoneNumbers

Release phone numbers by ID or phone number string.

Returns ReleasePhoneNumbersResponse.

Parameter	Type	Required	Description
ids	array<string>		Use phone number IDs for direct lookup. Required if `phone_numbers` is not provided.
phone_numbers	array<string>		Use phone number strings for lookup (for example, "+16505550010"). Required if `ids` is not provided.

Types

The Phone Number service includes the following types.

PhoneNumber

This type is returned in the response types for multiple API endpoints. Some fields are only returned by certain endpoints. See the descriptions for specific response types for more information.

Field	Type	Description
id	string	Unique identifier.
e164_format	string	Phone number in E.164 format (for example, "+14155552671").
country_code	string	Country code (for example, "US").
area_code	string	Area code (for example, "415").
number_type	PhoneNumberType	Number type (mobile, local, toll-free, unknown).
locality	string	City/locality (for example, "San Francisco").
region	string	State/region (for example, "CA").
capabilities	array<string>	Available capabilities (for example, "voice", "sms").
status	PhoneNumberStatus	Current status.
assigned_at	google.protobuf.Timestamp	Assignment timestamp.
released_at	google.protobuf.Timestamp	Release timestamp (if applicable).
sip_dispatch_rule_id	string	Associated SIP dispatch rule ID.

PhoneNumberStatus

Enum. Valid values are as follows:

Name	Value	Description
PHONE_NUMBER_STATUS_UNSPECIFIED	0	Default value.
PHONE_NUMBER_STATUS_ACTIVE	1	Number is active and ready for use.
PHONE_NUMBER_STATUS_PENDING	2	Number is being provisioned.
PHONE_NUMBER_STATUS_RELEASED	3	Number has been released.

PhoneNumberType

Enum. Valid values are as follows:

Name	Value	Description
PHONE_NUMBER_TYPE_UNKNOWN	0	Default value - unknown or parsing error.
PHONE_NUMBER_TYPE_MOBILE	1	Mobile phone number.
PHONE_NUMBER_TYPE_LOCAL	2	Local/fixed line number.
PHONE_NUMBER_TYPE_TOLL_FREE	3	Toll-free number.

SearchPhoneNumbersResponse

Field	Type	Description
items	array<PhoneNumber>	List of available phone numbers.

PurchasePhoneNumberResponse

Field Type Description

Field	Type	Description
phone_numbers	array<PhoneNumber>	Details of the purchased phone numbers. Only the following fields of `PhoneNumber` type are returned: `id` `e164_format` `status`

phone_numbers

array<PhoneNumber>

Details of the purchased phone numbers. Only the following fields of PhoneNumber type are returned:

id
e164_format
status

ListPhoneNumbersResponse

Field Type Description

Field	Type	Description
items	array<PhoneNumber>	List of phone numbers. The following fields of `PhoneNumber` type are returned: `id` `e164_format` `country_code` `area_code` `number_type` `locality` `region` `capabilities` `status` `sip_dispatch_rule_id` `released_at` (if applicable)
total_count	int32	Total number of phone numbers.

items

array<PhoneNumber>

List of phone numbers. The following fields of PhoneNumber type are returned:

id
e164_format
country_code
area_code
number_type
locality
region
capabilities
status
sip_dispatch_rule_id
released_at (if applicable)

total_count int32 Total number of phone numbers.

GetPhoneNumberResponse

Field Type Description

Field	Type	Description
phone_number	PhoneNumber	The phone number details. The following fields of `PhoneNumber` type are returned: `id` `e164_format` `country_code` `area_code` `number_type` `locality` `region` `capabilities` `status` `sip_dispatch_rule_id` `released_at` (if applicable)

phone_number

PhoneNumber

The phone number details. The following fields of PhoneNumber type are returned:

id
e164_format
country_code
area_code
number_type
locality
region
capabilities
status
sip_dispatch_rule_id
released_at (if applicable)

UpdatePhoneNumberResponse

Field Type Description

Field	Type	Description
phone_number	PhoneNumber	The updated phone number details. The following fields of `PhoneNumber` type are returned: `id` `e164_format` `status` `sip_dispatch_rule_id`

phone_number

PhoneNumber

The updated phone number details. The following fields of PhoneNumber type are returned:

id
e164_format
status
sip_dispatch_rule_id

ReleasePhoneNumbersResponse

Field	Type	Description
		Empty response - operation completed successfully.