Skip to contentSkip to navigationSkip to topbar
Twilio Docs
On this page

Phone Number

(error)

Proxy Public Beta is not available to new customers

Proxy Public Beta is currently closed for new customers. Please consider using Twilio Conversations and Programmable Voice directly if you are building your masking application.

Note that this does not have any impact on Twilio Flex customers.

(warning)

Public Beta for customers already using Proxy

Twilio's Proxy API is currently available as a Public Beta product. Some features are not yet implemented and others may be changed before the product is declared as Generally Available.

Public Beta products are not covered by a Twilio SLA(link takes you to an external page).

With Twilio Proxy, you associate phone numbers (this resource) 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.

PhoneNumber Properties

phonenumber-properties page anchor
Property nameTypeRequiredDescriptionChild properties
sidSID<PN>

Optional

Not PII

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

Pattern: ^PN[0-9a-fA-F]{32}$Min length: 34Max length: 34
accountSidSID<AC>

Optional

Not PII

The SID of the Account that created the PhoneNumber resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
serviceSidSID<KS>

Optional

Not PII

The SID of the PhoneNumber resource's parent Service resource.

Pattern: ^KS[0-9a-fA-F]{32}$Min length: 34Max length: 34
dateCreatedstring<date-time>

Optional

Not PII

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

dateUpdatedstring<date-time>

Optional

Not PII

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

phoneNumberstring<phone-number>

Optional

Not PII

The phone number in E.164 format, which consists of a + followed by the country code and subscriber number.

friendlyNamestring

Optional

Not PII

The string that you assigned to describe the resource.

isoCountrystring

Optional

Not PII

The ISO Country Code for the phone number.

capabilitiesobject<phone-number-capabilities>

Optional

Not PII

The capabilities of the phone number.

urlstring<uri>

Optional

Not PII

The absolute URL of the PhoneNumber resource.

isReservedboolean

Optional

Not PII

Whether the phone number should be reserved and not be assigned to a participant using proxy pool logic. See Reserved Phone Numbers for more information.

inUseinteger

Optional

Not PII

The number of open session assigned to the number. See the How many Phone Numbers do I need? guide for more information.

Default: 0

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

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
serviceSidSID<KS>
required
Not PII

The SID parent Service resource of the new PhoneNumber resource.

Pattern: ^KS[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

request-body-parameters page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
sidSID<PN>

Optional

Not PII

The SID of a Twilio IncomingPhoneNumber resource that represents the Twilio Number you would like to assign to your Proxy Service.

Pattern: ^PN[0-9a-fA-F]{32}$Min length: 34Max length: 34
phoneNumberstring<phone-number>

Optional

Not PII

The phone number in E.164 format. E.164 phone numbers consist of a + followed by the country code and subscriber number without punctuation characters. For example, +14155551234.

isReservedboolean

Optional

Not PII

Whether the new phone number should be reserved and not be assigned to a participant using proxy pool logic. See Reserved Phone Numbers for more information.

Add a Phone NumberLink to code sample: Add a Phone Number
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createPhoneNumber() {

11
  const phoneNumber = await client.proxy.v1

12
    .services("KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .phoneNumbers.create({ sid: "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" });

14


15
  console.log(phoneNumber.sid);

16
}

17


18
createPhoneNumber();

Response

1
{

2
  "sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "service_sid": "KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

5
  "date_created": "2015-07-30T20:00:00Z",

6
  "date_updated": "2015-07-30T20:00:00Z",

7
  "phone_number": "+1987654321",

8
  "friendly_name": "Friendly Name",

9
  "iso_country": "US",

10
  "capabilities": {

11
    "sms_outbound": true,

12
    "voice_inbound": false

13
  },

14
  "url": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

15
  "is_reserved": false,

16
  "in_use": 0

17
}
Add a Reserved Phone NumberLink to code sample: Add a Reserved Phone Number
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createPhoneNumber() {

11
  const phoneNumber = await client.proxy.v1

12
    .services("KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .phoneNumbers.create({

14
      isReserved: true,

15
      sid: "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

16
    });

17


18
  console.log(phoneNumber.sid);

19
}

20


21
createPhoneNumber();

Response

1
{

2
  "sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "service_sid": "KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

5
  "date_created": "2015-07-30T20:00:00Z",

6
  "date_updated": "2015-07-30T20:00:00Z",

7
  "phone_number": "+1987654321",

8
  "friendly_name": "Friendly Name",

9
  "iso_country": "US",

10
  "capabilities": {

11
    "sms_outbound": true,

12
    "voice_inbound": false

13
  },

14
  "url": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

15
  "is_reserved": true,

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

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
serviceSidSID<KS>
required
Not PII

The SID of the parent Service of the PhoneNumber resource to fetch.

Pattern: ^KS[0-9a-fA-F]{32}$Min length: 34Max length: 34
sidSID<PN>
required
Not PII

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

Pattern: ^PN[0-9a-fA-F]{32}$Min length: 34Max length: 34
Fetch a PhoneNumberLink to code sample: Fetch a PhoneNumber
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function fetchPhoneNumber() {

11
  const phoneNumber = await client.proxy.v1

12
    .services("KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .phoneNumbers("PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

14
    .fetch();

15


16
  console.log(phoneNumber.sid);

17
}

18


19
fetchPhoneNumber();

Response

1
{

2
  "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "service_sid": "KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "date_created": "2015-07-30T20:00:00Z",

6
  "date_updated": "2015-07-30T20:00:00Z",

7
  "phone_number": "12345",

8
  "friendly_name": "Friendly Name",

9
  "iso_country": "US",

10
  "capabilities": {

11
    "sms_outbound": true,

12
    "voice_inbound": false

13
  },

14
  "url": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

15
  "is_reserved": false,

16
  "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

Path parameters

path-parameters-2 page anchor
Property nameTypeRequiredPIIDescription
serviceSidSID<KS>
required
Not PII

The SID of the parent Service of the PhoneNumber resources to read.

Pattern: ^KS[0-9a-fA-F]{32}$Min length: 34Max length: 34

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
pageSizeinteger<int64>

Optional

Not PII

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

Minimum: 1Maximum: 1000
pageinteger

Optional

Not PII

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

Minimum: 0
pageTokenstring

Optional

Not PII

The page token. This is provided by the API.

List multiple PhoneNumbersLink to code sample: List multiple PhoneNumbers
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listPhoneNumber() {

11
  const phoneNumbers = await client.proxy.v1

12
    .services("KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .phoneNumbers.list({ limit: 20 });

14


15
  phoneNumbers.forEach((p) => console.log(p.sid));

16
}

17


18
listPhoneNumber();

Response

1
{

2
  "meta": {

3
    "page": 0,

4
    "page_size": 50,

5
    "first_page_url": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers?PageSize=50&Page=0",

6
    "previous_page_url": null,

7
    "next_page_url": null,

8
    "key": "phone_numbers",

9
    "url": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers?PageSize=50&Page=0"

10
  },

11
  "phone_numbers": [

12
    {

13
      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

14
      "service_sid": "KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

15
      "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

16
      "date_created": "2015-07-30T20:00:00Z",

17
      "date_updated": "2015-07-30T20:00:00Z",

18
      "phone_number": "+1987654321",

19
      "friendly_name": "Friendly Name",

20
      "iso_country": "US",

21
      "capabilities": {

22
        "sms_outbound": true,

23
        "voice_inbound": false

24
      },

25
      "url": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

26
      "is_reserved": false,

27
      "in_use": 0

28
    }

29
  ]

30
}

Update a PhoneNumber resource

update-a-phonenumber-resource page anchor

POST https://proxy.twilio.com/v1/Services/{ServiceSid}/PhoneNumbers/{Sid}

Path parameters

path-parameters-3 page anchor
Property nameTypeRequiredPIIDescription
serviceSidSID<KS>
required
Not PII

The SID of the parent Service of the PhoneNumber resource to update.

Pattern: ^KS[0-9a-fA-F]{32}$Min length: 34Max length: 34
sidSID<PN>
required
Not PII

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

Pattern: ^PN[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

request-body-parameters-1 page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
isReservedboolean

Optional

Not PII

Whether the phone number should be reserved and not be assigned to a participant using proxy pool logic. See Reserved Phone Numbers for more information.

Update a PhoneNumberLink to code sample: Update a PhoneNumber
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function updatePhoneNumber() {

11
  const phoneNumber = await client.proxy.v1

12
    .services("KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .phoneNumbers("PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

14
    .update({ isReserved: false });

15


16
  console.log(phoneNumber.sid);

17
}

18


19
updatePhoneNumber();

Response

1
{

2
  "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "service_sid": "KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "date_created": "2015-07-30T20:00:00Z",

6
  "date_updated": "2015-07-30T20:00:00Z",

7
  "phone_number": "12345",

8
  "friendly_name": "Friendly Name",

9
  "iso_country": "US",

10
  "capabilities": {

11
    "sms_outbound": true,

12
    "voice_inbound": false

13
  },

14
  "url": "https://proxy.twilio.com/v1/Services/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

15
  "is_reserved": false,

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

Path parameters

path-parameters-4 page anchor
Property nameTypeRequiredPIIDescription
serviceSidSID<KS>
required
Not PII

The SID of the parent Service of the PhoneNumber resource to delete.

Pattern: ^KS[0-9a-fA-F]{32}$Min length: 34Max length: 34
sidSID<PN>
required
Not PII

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

Pattern: ^PN[0-9a-fA-F]{32}$Min length: 34Max length: 34
Delete a PhoneNumberLink to code sample: Delete a PhoneNumber
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function deletePhoneNumber() {

11
  await client.proxy.v1

12
    .services("KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .phoneNumbers("PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

14
    .remove();

15
}

16


17
deletePhoneNumber();