Skip to content Skip to navigation Skip to topbar

On this page

PhoneNumber Resource

The Phone Numbers subresource contains the list of Phone Number instances associated with a SIP Trunk.

To purchase a new phone number for your trunk or manage your numbers more generally, you'll need to use the IncomingPhoneNumbers Resource. The SIP Trunking PhoneNumbers Resource is only for adding, removing, and viewing phone numbers associated with a SIP Trunk.

PhoneNumber Properties

Property nameTypeRequiredDescriptionChild properties

account_sidSID<AC>

Optional

The SID of the Account that created the PhoneNumber resource.

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

address_requirementsenum<string>

Optional

Whether the phone number requires an Address registered with Twilio and, if so, what type. Can be: none, any, local, or foreign.

Possible values:

noneanylocalforeign

api_versionstring

Optional

The API version used to start a new TwiML session.

betaboolean

Optional

Whether the phone number is new to the Twilio platform. Can be: true or false.

capabilitiesobject<string-map>

Optional

The set of Boolean properties that indicate whether a phone number can receive calls or messages. Capabilities are Voice, SMS, and MMS and each capability can be: true or false.

date_createdstring<date-time>

Optional

The date and time in GMT when the resource was created specified in RFC 2822 format.

date_updatedstring<date-time>

Optional

The date and time in GMT when the resource was last updated specified in RFC 2822 format.

friendly_namestring

Optional

PII MTL: 30 days

The string that you assigned to describe the resource.

linksobject<uri-map>

Optional

The URLs of related resources.

phone_numberstring<phone-number>

Optional

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

sidSID<PN>

Optional

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

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

sms_application_sidSID<AP>

Optional

The SID of the application that handles SMS messages sent to the phone number. If an sms_application_sid is present, we ignore all sms_*_url values and use those of the application.

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

sms_fallback_methodenum<http-method>

Optional

The HTTP method we use to call sms_fallback_url. Can be: GET or POST.

Possible values:

GETPOST

sms_fallback_urlstring<uri>

Optional

The URL that we call using the sms_fallback_method when an error occurs while retrieving or executing the TwiML from sms_url.

sms_methodenum<http-method>

Optional

The HTTP method we use to call sms_url. Can be: GET or POST.

Possible values:

GETPOST

sms_urlstring<uri>

Optional

The URL we call using the sms_method when the phone number receives an incoming SMS message.

status_callbackstring<uri>

Optional

The URL we call using the status_callback_method to send status information to your application.

status_callback_methodenum<http-method>

Optional

The HTTP method we use to call status_callback. Can be: GET or POST.

Possible values:

GETPOST

trunk_sidSID<TK>

Optional

The SID of the Trunk that handles calls to the phone number. If a trunk_sid is present, we ignore all of the voice URLs and voice applications and use those set on the Trunk. Setting a trunk_sid will automatically delete your voice_application_sid and vice versa.

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

urlstring<uri>

Optional

The absolute URL of the resource.

voice_application_sidSID<AP>

Optional

The SID of the application that handles calls to the phone number. If a voice_application_sid is present, we ignore all of the voice URLs and use those set on the application. Setting a voice_application_sid will automatically delete your trunk_sid and vice versa.

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

voice_caller_id_lookupboolean

Optional

Whether we look up the caller's caller-ID name from the CNAM database ($0.01 per look up). Can be: true or false.

voice_fallback_methodenum<http-method>

Optional

The HTTP method that we use to call voice_fallback_url. Can be: GET or POST.

Possible values:

GETPOST

voice_fallback_urlstring<uri>

Optional

The URL that we call using the voice_fallback_method when an error occurs retrieving or executing the TwiML requested by url.

voice_methodenum<http-method>

Optional

The HTTP method we use to call voice_url. Can be: GET or POST.

Possible values:

GETPOST

voice_urlstring<uri>

Optional

The URL we call using the voice_method when the phone number receives a call. The voice_url is not be used if a voice_application_sid or a trunk_sid is set.

Create a PhoneNumber resource

POST https://trunking.twilio.com/v1/Trunks/{TrunkSid}/PhoneNumbers

Path parameters

Property nameTypeRequiredPIIDescription

TrunkSidSID<TK>required

The SID of the Trunk to associate the phone number with.

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

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredDescriptionChild properties

PhoneNumberSidSID<PN>required

The SID of the Incoming Phone Number that you want to associate with the trunk.

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

Create a PhoneNumber

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createPhoneNumber() {
11  const phoneNumber = await client.trunking.v1
12    .trunks("TKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .phoneNumbers.create({
14      phoneNumberSid: "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15    });
16
17  console.log(phoneNumber.accountSid);
18}
19
20createPhoneNumber();

Output

1{
2  "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3  "date_created": "2010-12-10T17:27:34Z",
4  "date_updated": "2015-10-09T11:36:32Z",
5  "friendly_name": "(415) 867-5309",
6  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7  "phone_number": "+14158675309",
8  "api_version": "2010-04-01",
9  "voice_caller_id_lookup": null,
10  "voice_url": "https://webhooks.twilio.com/v1/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Proxy/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/Call",
11  "voice_method": "POST",
12  "voice_fallback_url": null,
13  "voice_fallback_method": null,
14  "status_callback": "",
15  "status_callback_method": "POST",
16  "voice_application_sid": "",
17  "trunk_sid": "TKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18  "sms_url": "https://webhooks.twilio.com/v1/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Proxy/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/Message",
19  "sms_method": "POST",
20  "sms_fallback_url": "",
21  "sms_fallback_method": "POST",
22  "sms_application_sid": "APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
23  "address_requirements": "none",
24  "beta": false,
25  "url": "https://trunking.twilio.com/v1/Trunks/TKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
26  "capabilities": {
27    "voice": true,
28    "sms": true,
29    "mms": true
30  },
31  "links": {
32    "phone_number": "https://api.twilio.com/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
33  }
34}

Read multiple PhoneNumber resources

GET https://trunking.twilio.com/v1/Trunks/{TrunkSid}/PhoneNumbers

Path parameters

Property nameTypeRequiredPIIDescription

TrunkSidSID<TK>required

The SID of the Trunk from which to read the PhoneNumber resources.

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

Query parameters

Property nameTypeRequiredPIIDescription

PageSizeinteger

Optional

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

Minimum: 1Maximum: 1000

Pageinteger

Optional

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

Minimum: 0

PageTokenstring

Optional

The page token. This is provided by the API.

List multiple PhoneNumbers

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listPhoneNumber() {
11  const phoneNumbers = await client.trunking.v1
12    .trunks("TKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .phoneNumbers.list({ limit: 20 });
14
15  phoneNumbers.forEach((p) => console.log(p.accountSid));
16}
17
18listPhoneNumber();

Output

1{
2  "meta": {
3    "first_page_url": "https://trunking.twilio.com/v1/Trunks/TKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers?PageSize=1&Page=0",
4    "key": "phone_numbers",
5    "next_page_url": null,
6    "page": 0,
7    "page_size": 1,
8    "previous_page_url": null,
9    "url": "https://trunking.twilio.com/v1/Trunks/TKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers?PageSize=1&Page=0"
10  },
11  "phone_numbers": [
12    {
13      "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14      "date_created": "2010-12-10T17:27:34Z",
15      "date_updated": "2015-10-09T11:36:32Z",
16      "friendly_name": "(415) 867-5309",
17      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18      "phone_number": "+14158675309",
19      "api_version": "2010-04-01",
20      "voice_caller_id_lookup": null,
21      "voice_url": "https://webhooks.twilio.com/v1/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Proxy/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/Call",
22      "voice_method": "POST",
23      "voice_fallback_url": null,
24      "voice_fallback_method": null,
25      "status_callback": "",
26      "status_callback_method": "POST",
27      "voice_application_sid": "",
28      "trunk_sid": "TKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
29      "sms_url": "https://webhooks.twilio.com/v1/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Proxy/KSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks/Message",
30      "sms_method": "POST",
31      "sms_fallback_url": "",
32      "sms_fallback_method": "POST",
33      "sms_application_sid": "APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
34      "address_requirements": "none",
35      "beta": false,
36      "url": "https://trunking.twilio.com/v1/Trunks/TKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
37      "capabilities": {
38        "voice": true,
39        "sms": true,
40        "mms": true
41      },
42      "links": {
43        "phone_number": "https://api.twilio.com/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
44      }
45    }
46  ]
47}

Delete a PhoneNumber resource

DELETE https://trunking.twilio.com/v1/Trunks/{TrunkSid}/PhoneNumbers/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

TrunkSidSID<TK>required

The SID of the Trunk from which to delete the PhoneNumber resource.

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

SidSID<PN>required

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

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

Delete a PhoneNumber

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deletePhoneNumber() {
11  await client.trunking.v1
12    .trunks("TKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13    .phoneNumbers("PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14    .remove();
15}
16
17deletePhoneNumber();