Skip to contentSkip to navigationSkip to topbar
Rate this page:
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

phonenumber-properties page anchor
Resource properties
account_sidtype: SID<AC>Not PII

address_requirementstype: enum<STRING>Not PII

Whether the phone number requires an Address(link takes you to an external page) registered with Twilio and, if so, what type. Can be: none, any, local, or foreign.

Possible values:
noneanylocalforeign

api_versiontype: stringNot PII

The API version used to start a new TwiML session.


betatype: booleanNot PII

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


capabilitiestype: object<STRING MAP>Not PII

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_createdtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was created specified in RFC 2822(link takes you to an external page) format.


date_updatedtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was last updated specified in RFC 2822(link takes you to an external page) format.


friendly_nametype: stringPII MTL: 30 days

The string that you assigned to describe the resource.


linkstype: object<URI MAP>Not PII

The URLs of related resources.


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.


sidtype: SID<PN>Not PII

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


sms_application_sidtype: SID<AP>Not PII

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.


sms_fallback_methodtype: enum<HTTP METHOD>Not PII

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

Possible values:
HEADGETPOSTPATCHPUTDELETE

sms_fallback_urltype: string<URI>Not PII

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


sms_methodtype: enum<HTTP METHOD>Not PII

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

Possible values:
HEADGETPOSTPATCHPUTDELETE

sms_urltype: string<URI>Not PII

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


status_callbacktype: string<URI>Not PII

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


status_callback_methodtype: enum<HTTP METHOD>Not PII

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

Possible values:
HEADGETPOSTPATCHPUTDELETE

trunk_sidtype: SID<TK>Not PII

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.


urltype: string<URI>Not PII

The absolute URL of the resource.


voice_application_sidtype: SID<AP>Not PII

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.


voice_caller_id_lookuptype: booleanNot PII

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_methodtype: enum<HTTP METHOD>Not PII

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

Possible values:
HEADGETPOSTPATCHPUTDELETE

voice_fallback_urltype: string<URI>Not PII

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


voice_methodtype: enum<HTTP METHOD>Not PII

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

Possible values:
HEADGETPOSTPATCHPUTDELETE

voice_urltype: string<URI>Not PII

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

create-a-phonenumber-resource page anchor
POST https://trunking.twilio.com/v1/Trunks/{TrunkSid}/PhoneNumbers

Parameters

create-parameters page anchor
URI parameters
TrunkSidtype: SID<TK>Not PII
Path Parameter

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


Request body parameters
PhoneNumberSidtype: SID<PN>Not PII
Required

The SID of the Incoming Phone Number(link takes you to an external page) that you want to associate with the trunk.

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

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

Output

_34
{
_34
"sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_34
"date_created": "2010-12-10T17:27:34Z",
_34
"date_updated": "2015-10-09T11:36:32Z",
_34
"friendly_name": "(415) 867-5309",
_34
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_34
"phone_number": "+14158675309",
_34
"api_version": "2010-04-01",
_34
"voice_caller_id_lookup": null,
_34
"voice_url": "https://webhooks.twilio.com/v1/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Proxy/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Webhooks/Call",
_34
"voice_method": "POST",
_34
"voice_fallback_url": null,
_34
"voice_fallback_method": null,
_34
"status_callback": "",
_34
"status_callback_method": "POST",
_34
"voice_application_sid": "",
_34
"trunk_sid": "TKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_34
"sms_url": "https://webhooks.twilio.com/v1/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Proxy/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Webhooks/Message",
_34
"sms_method": "POST",
_34
"sms_fallback_url": "",
_34
"sms_fallback_method": "POST",
_34
"sms_application_sid": "APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_34
"address_requirements": "none",
_34
"beta": false,
_34
"url": "https://trunking.twilio.com/v1/Trunks/TKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_34
"capabilities": {
_34
"voice": true,
_34
"sms": true,
_34
"mms": true
_34
},
_34
"links": {
_34
"phone_number": "https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_34
}
_34
}


Read multiple PhoneNumber resources

read-multiple-phonenumber-resources page anchor
GET https://trunking.twilio.com/v1/Trunks/{TrunkSid}/PhoneNumbers

URI parameters
TrunkSidtype: SID<TK>Not PII
Path Parameter

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


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.trunking.v1.trunks('TKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.phoneNumbers
_11
.list({limit: 20})
_11
.then(phoneNumbers => phoneNumbers.forEach(p => console.log(p.sid)));

Output

_47
{
_47
"meta": {
_47
"first_page_url": "https://trunking.twilio.com/v1/Trunks/TKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers?PageSize=1&Page=0",
_47
"key": "phone_numbers",
_47
"next_page_url": "https://trunking.twilio.com/v1/Trunks/TKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers?PageSize=1&Page=1",
_47
"page": 0,
_47
"page_size": 1,
_47
"previous_page_url": "https://trunking.twilio.com/v1/Trunks/TKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers?PageSize=1&Page=0",
_47
"url": "https://trunking.twilio.com/v1/Trunks/TKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers?PageSize=1&Page=0"
_47
},
_47
"phone_numbers": [
_47
{
_47
"sid": "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_47
"date_created": "2010-12-10T17:27:34Z",
_47
"date_updated": "2015-10-09T11:36:32Z",
_47
"friendly_name": "(415) 867-5309",
_47
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_47
"phone_number": "+14158675309",
_47
"api_version": "2010-04-01",
_47
"voice_caller_id_lookup": null,
_47
"voice_url": "https://webhooks.twilio.com/v1/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Proxy/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Webhooks/Call",
_47
"voice_method": "POST",
_47
"voice_fallback_url": null,
_47
"voice_fallback_method": null,
_47
"status_callback": "",
_47
"status_callback_method": "POST",
_47
"voice_application_sid": "",
_47
"trunk_sid": "TKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_47
"sms_url": "https://webhooks.twilio.com/v1/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Proxy/KSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Webhooks/Message",
_47
"sms_method": "POST",
_47
"sms_fallback_url": "",
_47
"sms_fallback_method": "POST",
_47
"sms_application_sid": "APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_47
"address_requirements": "none",
_47
"beta": false,
_47
"url": "https://trunking.twilio.com/v1/Trunks/TKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/PhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_47
"capabilities": {
_47
"voice": true,
_47
"sms": true,
_47
"mms": true
_47
},
_47
"links": {
_47
"phone_number": "https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_47
}
_47
}
_47
]
_47
}


Delete a PhoneNumber resource

delete-a-phonenumber-resource page anchor
DELETE https://trunking.twilio.com/v1/Trunks/{TrunkSid}/PhoneNumbers/{Sid}

URI parameters
TrunkSidtype: SID<TK>Not PII
Path Parameter

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


Sidtype: SID<PN>Not PII
Path Parameter

The unique string that we created to identify 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.trunking.v1.trunks('TKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.phoneNumbers('PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.remove();


Rate this page: