Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Phone Number


With Twilio Proxy, you associate phone numbers (this resource) and short codes directly with a Proxy Service. All added numbers go into the Phone Number Pool associated with a given Proxy Service.

A Twilio number cannot be associated with more than one Proxy Service, but it can be associated with a Messaging Service, for example, to complete US A2P 10DLC registration (see below for important details about how to do this).

For more information on managing the phone numbers in your Proxy Phone Number Pool, refer to our Phone Number Management guide.


"Reserved" numbers in Proxy

reserved-numbers-in-proxy page anchor

In a Proxy service, phone numbers can be marked as Reserved. Reserved numbers will not be included in the set of numbers Proxy considers when choosing a number for a participant, but they can be manually assigned as Proxy Numbers for participants (e.g., in a lead tracking use-case).


Proxy Number Pool Size Limit

proxy-number-pool-size-limit page anchor

Phone Number Pools are limited to 5000 reserved phone numbers and 500 unreserved phone numbers per Proxy Service. Numbers can be distributed across multiple Proxy Services if you need more of numbers.


Adding Proxy Phone Numbers to Messaging Services

adding-proxy-phone-numbers-to-messaging-services page anchor

It is possible to associate Twilio Proxy numbers with a Messaging Service, although there are some limitations to be aware of. This capability is especially important for customers who use US long code numbers to send messages to US recipients because adding numbers to a Messaging Service is required in order to complete A2P 10DLC(link takes you to an external page) registration.

Currently, a number that is already associated with a Messaging Service cannot be added to a Proxy Service via the Proxy Console or API.

However, Twilio numbers that are already associated with a Proxy Service can be associated with a Messaging Service. Before doing this, you must ensure that your Messaging Service is configured correctly. Your Messaging Service must have its Incoming Message handling behavior set to "Defer to sender's webhook" to ensure that your numbers continue to use Proxy after they are added to the Service.

Step-by-step instructions to associate Proxy numbers with a Messaging Service:

  1. Set up your Messaging Service, but do not add any phone numbers to it yet. Ensure that the Incoming Message handling is set to "Defer to sender's webhook." This setting can be found in the "Integration" settings for the Messaging Service in the Twilio Console.
  2. Ensure that all numbers you plan to add to the Messaging Service are already associated with a Proxy Service.
  3. Add your Proxy numbers to the Messaging Service, either using the Twilio Console or the Messaging Service API PhoneNumber endpoint.

Resource properties
sidtype: SID<PN>Not PII

The unique string that we created to identify the PhoneNumber resource.


account_sidtype: SID<AC>Not PII

The SID of the Account(link takes you to an external page) that created the PhoneNumber resource.


service_sidtype: SID<KS>Not PII

The SID of the PhoneNumber resource's parent Service(link takes you to an external page) resource.


date_createdtype: string<DATE TIME>Not PII

The ISO 8601(link takes you to an external page) date and time in GMT when the resource was created.


date_updatedtype: string<DATE TIME>Not PII

The ISO 8601(link takes you to an external page) date and time in GMT when the resource was last updated.


phone_numbertype: string<PHONE NUMBER>Not PII

The phone number in E.164(link takes you to an external page) format, which consists of a + followed by the country code and subscriber number.


friendly_nametype: stringNot PII

The string that you assigned to describe the resource.


iso_countrytype: stringNot PII

The ISO Country Code for the phone number.


capabilitiestype: object<PHONE NUMBER CAPABILITIES>Not PII

The capabilities of the phone number.


urltype: string<URI>Not PII

The absolute URL of the PhoneNumber resource.


is_reservedtype: booleanNot PII

Whether the phone number should be reserved and not be assigned to a participant using proxy pool logic. See Reserved Phone Numbers(link takes you to an external page) for more information.


in_usetype: integerNot PII

The number of open session assigned to the number. See the How many Phone Numbers do I need?(link takes you to an external page) guide for more information.


Add a Phone Number to a Proxy Service

add-a-phone-number-to-a-proxy-service page anchor
POST https://proxy.twilio.com/v1/Services/{ServiceSid}/PhoneNumbers

Parameters

create-parameters page anchor
URI parameters
ServiceSidtype: SID<KS>Not PII
Path Parameter

The SID parent Service(link takes you to an external page) resource of the new PhoneNumber resource.


Request body parameters
Sidtype: SID<PN>Not PII

The SID of a Twilio IncomingPhoneNumber(link takes you to an external page) resource that represents the Twilio Number you would like to assign to your Proxy Service.


PhoneNumbertype: string<PHONE NUMBER>Not PII

The phone number in E.164(link takes you to an external page) format. E.164 phone numbers consist of a + followed by the country code and subscriber number without punctuation characters. For example, +14155551234.


IsReservedtype: booleanNot PII

Whether the new phone number should be reserved and not be assigned to a participant using proxy pool logic. See Reserved Phone Numbers(link takes you to an external page) for more information.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.proxy.v1.services('KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.phoneNumbers
_11
.create({sid: 'PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'})
_11
.then(phone_number => console.log(phone_number.sid));

Output

_17
{
_17
"sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"service_sid": "KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"date_created": "2015-07-30T20:00:00Z",
_17
"date_updated": "2015-07-30T20:00:00Z",
_17
"phone_number": "+1987654321",
_17
"friendly_name": "Friendly Name",
_17
"iso_country": "US",
_17
"capabilities": {
_17
"sms_outbound": true,
_17
"voice_inbound": false
_17
},
_17
"url": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"is_reserved": false,
_17
"in_use": 0
_17
}

Add a Reserved Phone Number

add-a-reserved-phone-number page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.proxy.v1.services('KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_14
.phoneNumbers
_14
.create({
_14
sid: 'PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
_14
isReserved: true
_14
})
_14
.then(phone_number => console.log(phone_number.sid));

Output

_17
{
_17
"sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"service_sid": "KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"date_created": "2015-07-30T20:00:00Z",
_17
"date_updated": "2015-07-30T20:00:00Z",
_17
"phone_number": "+1987654321",
_17
"friendly_name": "Friendly Name",
_17
"iso_country": "US",
_17
"capabilities": {
_17
"sms_outbound": true,
_17
"voice_inbound": false
_17
},
_17
"url": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"is_reserved": true,
_17
"in_use": 0
_17
}

(information)

Info

Note: You should pass a PhoneNumber or a Sid (identifying a phone number on your account). Only one of them is required. Passing both will return an error.


Fetch a PhoneNumber resource

fetch-a-phonenumber-resource page anchor
GET https://proxy.twilio.com/v1/Services/{ServiceSid}/PhoneNumbers/{Sid}

URI parameters
ServiceSidtype: SID<KS>Not PII
Path Parameter

The SID of the parent Service(link takes you to an external page) of the PhoneNumber resource to fetch.


Sidtype: SID<PN>Not PII
Path Parameter

The Twilio-provided string that uniquely identifies the PhoneNumber resource to fetch.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.proxy.v1.services('KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.phoneNumbers('PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.fetch()
_11
.then(phone_number => console.log(phone_number.friendlyName));

Output

_17
{
_17
"sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"service_sid": "KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"date_created": "2015-07-30T20:00:00Z",
_17
"date_updated": "2015-07-30T20:00:00Z",
_17
"phone_number": "12345",
_17
"friendly_name": "Friendly Name",
_17
"iso_country": "US",
_17
"capabilities": {
_17
"sms_outbound": true,
_17
"voice_inbound": false
_17
},
_17
"url": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"is_reserved": false,
_17
"in_use": 0
_17
}


Get the list of Phone Numbers associated with a Proxy Service

get-the-list-of-phone-numbers-associated-with-a-proxy-service page anchor
GET https://proxy.twilio.com/v1/Services/{ServiceSid}/PhoneNumbers

URI parameters
ServiceSidtype: SID<KS>Not PII
Path Parameter

The SID of the parent Service(link takes you to an external page) of the PhoneNumber resources to read.


PageSizetype: integerNot PII
Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.


Pagetype: integerNot PII
Query Parameter

The page index. This value is simply for client state.


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

List multiple PhoneNumbers

list-multiple-phonenumbers page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.proxy.v1.services('KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.phoneNumbers
_11
.list({limit: 20})
_11
.then(phoneNumbers => phoneNumbers.forEach(p => console.log(p.sid)));

Output

_30
{
_30
"meta": {
_30
"page": 0,
_30
"page_size": 50,
_30
"first_page_url": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers?PageSize=50&Page=0",
_30
"previous_page_url": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers?PageSize=50&Page=0",
_30
"next_page_url": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers?PageSize=50&Page=1",
_30
"key": "phone_numbers",
_30
"url": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers?PageSize=50&Page=0"
_30
},
_30
"phone_numbers": [
_30
{
_30
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"service_sid": "KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"date_created": "2015-07-30T20:00:00Z",
_30
"date_updated": "2015-07-30T20:00:00Z",
_30
"phone_number": "+1987654321",
_30
"friendly_name": "Friendly Name",
_30
"iso_country": "US",
_30
"capabilities": {
_30
"sms_outbound": true,
_30
"voice_inbound": false
_30
},
_30
"url": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_30
"is_reserved": false,
_30
"in_use": 0
_30
}
_30
]
_30
}


Update a PhoneNumber resource

update-a-phonenumber-resource page anchor
POST https://proxy.twilio.com/v1/Services/{ServiceSid}/PhoneNumbers/{Sid}

URI parameters
ServiceSidtype: SID<KS>Not PII
Path Parameter

The SID of the parent Service(link takes you to an external page) of the PhoneNumber resource to update.


Sidtype: SID<PN>Not PII
Path Parameter

The Twilio-provided string that uniquely identifies the PhoneNumber resource to update.


Request body parameters
IsReservedtype: booleanNot PII

Whether the phone number should be reserved and not be assigned to a participant using proxy pool logic. See Reserved Phone Numbers(link takes you to an external page) for more information.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.proxy.v1.services('KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.phoneNumbers('PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.update({isReserved: true})
_11
.then(phone_number => console.log(phone_number.friendlyName));

Output

_17
{
_17
"sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"service_sid": "KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"date_created": "2015-07-30T20:00:00Z",
_17
"date_updated": "2015-07-30T20:00:00Z",
_17
"phone_number": "12345",
_17
"friendly_name": "Friendly Name",
_17
"iso_country": "US",
_17
"capabilities": {
_17
"sms_outbound": true,
_17
"voice_inbound": false
_17
},
_17
"url": "https://proxy.twilio.com/v1/Services/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17
"is_reserved": true,
_17
"in_use": 0
_17
}


Remove a Phone Number from a Proxy Service

remove-a-phone-number-from-a-proxy-service page anchor
DELETE https://proxy.twilio.com/v1/Services/{ServiceSid}/PhoneNumbers/{Sid}

URI parameters
ServiceSidtype: SID<KS>Not PII
Path Parameter

The SID of the parent Service(link takes you to an external page) of the PhoneNumber resource to delete.


Sidtype: SID<PN>Not PII
Path Parameter

The Twilio-provided string that uniquely identifies the PhoneNumber resource to delete.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.proxy.v1.services('KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.phoneNumbers('PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.remove();


Rate this page: