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

IncomingPhoneNumber resource

An IncomingPhoneNumber instance resource represents a Twilio phone number provisioned from Twilio, ported or hosted to Twilio.

The IncomingPhoneNumbers list resource represents an account's Twilio phone numbers. You can POST to the list resource to provision a new Twilio number. To find a new number to provision use the subresources of the AvailablePhoneNumbers resource.

You can transfer phone numbers between two Twilio accounts if you're using subaccounts. For details, see Exchanging Numbers Between Subaccounts.

(information)

Info

Provisioning a phone number is a two-step process. First, you must find an available phone number to provision using the subresources of the AvailablePhoneNumbers resource. Second, you must POST to the IncomingPhoneNumbers list resource, documented below.

(warning)

Warning

NOTE: The order of the columns in the CSV is not defined and may change when new fields are added to the API response. Your application design should be resilient to changes in the order of the columns in the CSV response.

IncomingPhoneNumber Properties

incomingphonenumber-properties page anchor
Property nameTypeRequiredDescriptionChild properties
accountSidSID<AC>

Optional

Not PII

The SID of the Account that created this IncomingPhoneNumber resource.

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

Optional

Not PII

The SID of the Address resource associated with the phone number.

Pattern: ^AD[0-9a-fA-F]{32}$Min length: 34Max length: 34
addressRequirementsenum<string>

Optional

Not PII
Possible values:
noneanylocalforeign
apiVersionstring

Optional

Not PII

The API version used to start a new TwiML session.

betaboolean

Optional

Not PII

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

capabilitiesobject<phone-number-capabilities>

Optional

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.

dateCreatedstring<date-time-rfc-2822>

Optional

Not PII

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

dateUpdatedstring<date-time-rfc-2822>

Optional

Not PII

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

friendlyNamestring

Optional

PII MTL: 30 days

The string that you assigned to describe the resource.

identitySidSID<RI>

Optional

Not PII

The SID of the Identity resource that we associate with the phone number. Some regions require an Identity to meet local regulations.

Pattern: ^RI[0-9a-fA-F]{32}$Min length: 34Max length: 34
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.

originstring

Optional

Not PII

The phone number's origin. twilio identifies Twilio-owned phone numbers and hosted identifies hosted phone numbers.

sidSID<PN>

Optional

Not PII

The unique string that that we created to identify this IncomingPhoneNumber resource.

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

Optional

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.

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

Optional

Not PII

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

Possible values:
GETPOST
smsFallbackUrlstring<uri>

Optional

Not PII

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

smsMethodenum<http-method>

Optional

Not PII

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

Possible values:
GETPOST
smsUrlstring<uri>

Optional

Not PII

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

statusCallbackstring<uri>

Optional

Not PII

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

statusCallbackMethodenum<http-method>

Optional

Not PII

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

Possible values:
GETPOST
trunkSidSID<TK>

Optional

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.

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

Optional

Not PII

The URI of the resource, relative to https://api.twilio.com.

voiceReceiveModeenum<string>

Optional

Not PII
Possible values:
voicefax
voiceApplicationSidSID<AP>

Optional

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.

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

Optional

Not 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.

voiceFallbackMethodenum<http-method>

Optional

Not PII

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

Possible values:
GETPOST
voiceFallbackUrlstring<uri>

Optional

Not PII

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

voiceMethodenum<http-method>

Optional

Not PII

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

Possible values:
GETPOST
voiceUrlstring<uri>

Optional

Not PII

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

emergencyStatusenum<string>

Optional

Not PII

The parameter displays if emergency calling is enabled for this number. Active numbers may place emergency calls by dialing valid emergency numbers for the country.

Possible values:
ActiveInactive
emergencyAddressSidSID<AD>

Optional

Not PII

The SID of the emergency address configuration that we use for emergency calling from this phone number.

Pattern: ^AD[0-9a-fA-F]{32}$Min length: 34Max length: 34
emergencyAddressStatusenum<string>

Optional

Not PII

The status of address registration with emergency services. A registered emergency address will be used during handling of emergency calls from this number.

Possible values:
registeredunregisteredpending-registrationregistration-failurepending-unregistrationunregistration-failure
bundleSidSID<BU>

Optional

Not PII

The SID of the Bundle resource that you associate with the phone number. Some regions require a Bundle to meet local Regulations.

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

Optional

Not PII

Create an IncomingPhoneNumber resource

create-an-incomingphonenumber-resource page anchor

POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
accountSidSID<AC>
required
Not PII

The SID of the Account that will create the resource.

Pattern: ^AC[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
apiVersionstring

Optional

Not PII

The API version to use for incoming calls made to the new phone number. The default is 2010-04-01.

friendlyNamestring

Optional

PII MTL: 30 days

A descriptive string that you created to describe the new phone number. It can be up to 64 characters long. By default, this is a formatted version of the new phone number.

smsApplicationSidSID<AP>

Optional

Not PII

The SID of the application that should handle SMS messages sent to the new phone number. If an sms_application_sid is present, we ignore all of the sms_*_url urls and use those set on the application.

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

Optional

Not PII

The HTTP method that we should use to call sms_fallback_url. Can be: GET or POST and defaults to POST.

Possible values:
GETPOST
smsFallbackUrlstring<uri>

Optional

Not PII

The URL that we should call when an error occurs while requesting or executing the TwiML defined by sms_url.

smsMethodenum<http-method>

Optional

Not PII

The HTTP method that we should use to call sms_url. Can be: GET or POST and defaults to POST.

Possible values:
GETPOST
smsUrlstring<uri>

Optional

Not PII

The URL we should call when the new phone number receives an incoming SMS message.

statusCallbackstring<uri>

Optional

Not PII

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

statusCallbackMethodenum<http-method>

Optional

Not PII

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

Possible values:
GETPOST
voiceApplicationSidSID<AP>

Optional

Not PII

The SID of the application we should use to handle calls to the new phone number. If a voice_application_sid is present, we ignore all of the voice urls and use only 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
voiceCallerIdLookupboolean

Optional

Not PII

Whether to lookup the caller's name from the CNAM database and post it to your app. Can be: true or false and defaults to false.

voiceFallbackMethodenum<http-method>

Optional

Not PII

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

Possible values:
GETPOST
voiceFallbackUrlstring<uri>

Optional

Not PII

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

voiceMethodenum<http-method>

Optional

Not PII

The HTTP method that we should use to call voice_url. Can be: GET or POST and defaults to POST.

Possible values:
GETPOST
voiceUrlstring<uri>

Optional

Not PII

The URL that we should call to answer a call to the new phone number. The voice_url will not be called if a voice_application_sid or a trunk_sid is set.

emergencyStatusenum<string>

Optional

Not PII

The parameter displays if emergency calling is enabled for this number. Active numbers may place emergency calls by dialing valid emergency numbers for the country.

Possible values:
ActiveInactive
emergencyAddressSidSID<AD>

Optional

Not PII

The SID of the emergency address configuration to use for emergency calling from the new phone number.

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

Optional

Not PII

The SID of the Trunk we should use to handle calls to the new phone number. If a trunk_sid is present, we ignore all of the voice urls and voice applications and use only 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
identitySidSID<RI>

Optional

Not PII

The SID of the Identity resource that we should associate with the new phone number. Some regions require an identity to meet local regulations.

Pattern: ^RI[0-9a-fA-F]{32}$Min length: 34Max length: 34
addressSidSID<AD>

Optional

Not PII

The SID of the Address resource we should associate with the new phone number. Some regions require addresses to meet local regulations.

Pattern: ^AD[0-9a-fA-F]{32}$Min length: 34Max length: 34
voiceReceiveModeenum<string>

Optional

Not PII
Possible values:
voicefax
bundleSidSID<BU>

Optional

Not PII

The SID of the Bundle resource that you associate with the phone number. Some regions require a Bundle to meet local Regulations.

Pattern: ^BU[0-9a-fA-F]{32}$Min length: 34Max length: 34
phoneNumberstring<phone-number>
required if AreaCode is not passed
Not PII

The phone number to purchase specified 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.

areaCodestring
required if PhoneNumber is not passed
Not PII

The desired area code for your new incoming phone number. Can be any three-digit, US or Canada area code. We will provision an available phone number within this area code for you. You must provide an area_code or a phone_number. (US and Canada only).

Provision a Phone NumberLink to code sample: Provision 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 createIncomingPhoneNumber() {

11
  const incomingPhoneNumber = await client.incomingPhoneNumbers.create({

12
    phoneNumber: "+14155552344",

13
  });

14


15
  console.log(incomingPhoneNumber.accountSid);

16
}

17


18
createIncomingPhoneNumber();

Response

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "address_requirements": "none",

4
  "address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "api_version": "2010-04-01",

6
  "beta": false,

7
  "capabilities": {

8
    "voice": true,

9
    "sms": false,

10
    "mms": true,

11
    "fax": false

12
  },

13
  "date_created": "Thu, 30 Jul 2015 23:19:04 +0000",

14
  "date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",

15
  "emergency_status": "Active",

16
  "emergency_address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

17
  "emergency_address_status": "registered",

18
  "friendly_name": "friendly_name",

19
  "identity_sid": "RIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

20
  "origin": "origin",

21
  "phone_number": "+14155552344",

22
  "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

23
  "sms_application_sid": "APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

24
  "sms_fallback_method": "GET",

25
  "sms_fallback_url": "https://example.com",

26
  "sms_method": "GET",

27
  "sms_url": "https://example.com",

28
  "status_callback": "https://example.com",

29
  "status_callback_method": "GET",

30
  "trunk_sid": null,

31
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",

32
  "voice_application_sid": "APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

33
  "voice_caller_id_lookup": false,

34
  "voice_fallback_method": "GET",

35
  "voice_fallback_url": "https://example.com",

36
  "voice_method": "GET",

37
  "voice_url": "https://example.com",

38
  "bundle_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

39
  "voice_receive_mode": "voice",

40
  "status": "in-use",

41
  "subresource_uris": {

42
    "assigned_add_ons": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AssignedAddOns.json"

43
  }

44
}
Provision a Phone Number with an AddressSid and a BundleSidLink to code sample: Provision a Phone Number with an AddressSid and a BundleSid
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 createIncomingPhoneNumber() {

11
  const incomingPhoneNumber = await client.incomingPhoneNumbers.create({

12
    addressSid: "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

13
    bundleSid: "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

14
    phoneNumber: "+14155552344",

15
  });

16


17
  console.log(incomingPhoneNumber.accountSid);

18
}

19


20
createIncomingPhoneNumber();

Response

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "address_requirements": "none",

4
  "address_sid": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

5
  "api_version": "2010-04-01",

6
  "beta": false,

7
  "capabilities": {

8
    "voice": true,

9
    "sms": false,

10
    "mms": true,

11
    "fax": false

12
  },

13
  "date_created": "Thu, 30 Jul 2015 23:19:04 +0000",

14
  "date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",

15
  "emergency_status": "Active",

16
  "emergency_address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

17
  "emergency_address_status": "registered",

18
  "friendly_name": "friendly_name",

19
  "identity_sid": "RIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

20
  "origin": "origin",

21
  "phone_number": "+14155552344",

22
  "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

23
  "sms_application_sid": "APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

24
  "sms_fallback_method": "GET",

25
  "sms_fallback_url": "https://example.com",

26
  "sms_method": "GET",

27
  "sms_url": "https://example.com",

28
  "status_callback": "https://example.com",

29
  "status_callback_method": "GET",

30
  "trunk_sid": null,

31
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",

32
  "voice_application_sid": "APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

33
  "voice_caller_id_lookup": false,

34
  "voice_fallback_method": "GET",

35
  "voice_fallback_url": "https://example.com",

36
  "voice_method": "GET",

37
  "voice_url": "https://example.com",

38
  "bundle_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

39
  "voice_receive_mode": "voice",

40
  "status": "in-use",

41
  "subresource_uris": {

42
    "assigned_add_ons": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AssignedAddOns.json"

43
  }

44
}
Provision a Phone Number with a Voice URLLink to code sample: Provision a Phone Number with a Voice URL
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 createIncomingPhoneNumber() {

11
  const incomingPhoneNumber = await client.incomingPhoneNumbers.create({

12
    phoneNumber: "+14155552344",

13
    voiceUrl: "https://www.your-voice-url.com/example",

14
  });

15


16
  console.log(incomingPhoneNumber.accountSid);

17
}

18


19
createIncomingPhoneNumber();

Response

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "address_requirements": "none",

4
  "address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "api_version": "2010-04-01",

6
  "beta": false,

7
  "capabilities": {

8
    "voice": true,

9
    "sms": false,

10
    "mms": true,

11
    "fax": false

12
  },

13
  "date_created": "Thu, 30 Jul 2015 23:19:04 +0000",

14
  "date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",

15
  "emergency_status": "Active",

16
  "emergency_address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

17
  "emergency_address_status": "registered",

18
  "friendly_name": "friendly_name",

19
  "identity_sid": "RIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

20
  "origin": "origin",

21
  "phone_number": "+14155552344",

22
  "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

23
  "sms_application_sid": "APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

24
  "sms_fallback_method": "GET",

25
  "sms_fallback_url": "https://example.com",

26
  "sms_method": "GET",

27
  "sms_url": "https://example.com",

28
  "status_callback": "https://example.com",

29
  "status_callback_method": "GET",

30
  "trunk_sid": null,

31
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",

32
  "voice_application_sid": "APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

33
  "voice_caller_id_lookup": false,

34
  "voice_fallback_method": "GET",

35
  "voice_fallback_url": "https://example.com",

36
  "voice_method": "GET",

37
  "voice_url": "https://www.your-voice-url.com/example",

38
  "bundle_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

39
  "voice_receive_mode": "voice",

40
  "status": "in-use",

41
  "subresource_uris": {

42
    "assigned_add_ons": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AssignedAddOns.json"

43
  }

44
}
Provision a Phone Number with an SMS URLLink to code sample: Provision a Phone Number with an SMS URL
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 createIncomingPhoneNumber() {

11
  const incomingPhoneNumber = await client.incomingPhoneNumbers.create({

12
    phoneNumber: "+14155552344",

13
    smsUrl: "https://www.your-sms-url.com/example",

14
  });

15


16
  console.log(incomingPhoneNumber.accountSid);

17
}

18


19
createIncomingPhoneNumber();

Response

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "address_requirements": "none",

4
  "address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "api_version": "2010-04-01",

6
  "beta": false,

7
  "capabilities": {

8
    "voice": true,

9
    "sms": false,

10
    "mms": true,

11
    "fax": false

12
  },

13
  "date_created": "Thu, 30 Jul 2015 23:19:04 +0000",

14
  "date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",

15
  "emergency_status": "Active",

16
  "emergency_address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

17
  "emergency_address_status": "registered",

18
  "friendly_name": "friendly_name",

19
  "identity_sid": "RIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

20
  "origin": "origin",

21
  "phone_number": "+14155552344",

22
  "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

23
  "sms_application_sid": "APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

24
  "sms_fallback_method": "GET",

25
  "sms_fallback_url": "https://example.com",

26
  "sms_method": "GET",

27
  "sms_url": "https://www.your-sms-url.com/example",

28
  "status_callback": "https://example.com",

29
  "status_callback_method": "GET",

30
  "trunk_sid": null,

31
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",

32
  "voice_application_sid": "APaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

33
  "voice_caller_id_lookup": false,

34
  "voice_fallback_method": "GET",

35
  "voice_fallback_url": "https://example.com",

36
  "voice_method": "GET",

37
  "voice_url": "https://example.com",

38
  "bundle_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

39
  "voice_receive_mode": "voice",

40
  "status": "in-use",

41
  "subresource_uris": {

42
    "assigned_add_ons": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AssignedAddOns.json"

43
  }

44
}

Fetch an IncomingPhoneNumber resource

fetch-an-incomingphonenumber-resource page anchor

GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.json

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
accountSidSID<AC>
required
Not PII

The SID of the Account that created the IncomingPhoneNumber resource to fetch.

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

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

Pattern: ^PN[0-9a-fA-F]{32}$Min length: 34Max length: 34
Fetch an IncomingPhoneNumberLink to code sample: Fetch an IncomingPhoneNumber
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 fetchIncomingPhoneNumber() {

11
  const incomingPhoneNumber = await client

12
    .incomingPhoneNumbers("PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .fetch();

14


15
  console.log(incomingPhoneNumber.accountSid);

16
}

17


18
fetchIncomingPhoneNumber();

Response

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "address_requirements": "none",

4
  "address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "api_version": "2010-04-01",

6
  "beta": false,

7
  "capabilities": {

8
    "voice": true,

9
    "sms": false,

10
    "mms": true,

11
    "fax": false

12
  },

13
  "date_created": "Thu, 30 Jul 2015 23:19:04 +0000",

14
  "date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",

15
  "emergency_status": "Active",

16
  "emergency_address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

17
  "emergency_address_status": "registered",

18
  "friendly_name": "(808) 925-5327",

19
  "identity_sid": "RIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

20
  "origin": "origin",

21
  "phone_number": "+18089255327",

22
  "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

23
  "sms_application_sid": "",

24
  "sms_fallback_method": "POST",

25
  "sms_fallback_url": "",

26
  "sms_method": "POST",

27
  "sms_url": "",

28
  "status_callback": "",

29
  "status_callback_method": "POST",

30
  "trunk_sid": null,

31
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",

32
  "voice_application_sid": "",

33
  "voice_caller_id_lookup": false,

34
  "voice_fallback_method": "POST",

35
  "voice_fallback_url": null,

36
  "voice_method": "POST",

37
  "voice_url": null,

38
  "voice_receive_mode": "voice",

39
  "status": "in-use",

40
  "bundle_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

41
  "subresource_uris": {

42
    "assigned_add_ons": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AssignedAddOns.json"

43
  }

44
}

Read multiple IncomingPhoneNumber resources

read-multiple-incomingphonenumber-resources page anchor

GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json

Path parameters

path-parameters-2 page anchor
Property nameTypeRequiredPIIDescription
accountSidSID<AC>
required
Not PII

The SID of the Account that created the IncomingPhoneNumber resources to read.

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

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
betaboolean

Optional

Not PII

Whether to include phone numbers new to the Twilio platform. Can be: true or false and the default is true.

friendlyNamestring

Optional

PII MTL: 30 days

A string that identifies the IncomingPhoneNumber resources to read.

phoneNumberstring<phone-number>

Optional

Not PII

The phone numbers of the IncomingPhoneNumber resources to read. You can specify partial numbers and use '*' as a wildcard for any digit.

originstring

Optional

Not PII

Whether to include phone numbers based on their origin. Can be: twilio or hosted. By default, phone numbers of all origin are included.

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 all IncomingPhoneNumber resources for your accountLink to code sample: List all IncomingPhoneNumber resources for your account
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 listIncomingPhoneNumber() {

11
  const incomingPhoneNumbers = await client.incomingPhoneNumbers.list({

12
    limit: 20,

13
  });

14


15
  incomingPhoneNumbers.forEach((i) => console.log(i.accountSid));

16
}

17


18
listIncomingPhoneNumber();

Response

1
{

2
  "end": 0,

3
  "first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers.json?FriendlyName=friendly_name&Beta=true&PhoneNumber=%2B19876543210&PageSize=50&Page=0",

4
  "incoming_phone_numbers": [

5
    {

6
      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

7
      "address_requirements": "none",

8
      "address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

9
      "api_version": "2010-04-01",

10
      "beta": null,

11
      "capabilities": {

12
        "voice": true,

13
        "sms": false,

14
        "mms": true,

15
        "fax": false

16
      },

17
      "date_created": "Thu, 30 Jul 2015 23:19:04 +0000",

18
      "date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",

19
      "emergency_status": "Active",

20
      "emergency_address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

21
      "emergency_address_status": "registered",

22
      "friendly_name": "(808) 925-5327",

23
      "identity_sid": "RIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

24
      "origin": "origin",

25
      "phone_number": "+18089255327",

26
      "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

27
      "sms_application_sid": "",

28
      "sms_fallback_method": "POST",

29
      "sms_fallback_url": "",

30
      "sms_method": "POST",

31
      "sms_url": "",

32
      "status_callback": "",

33
      "status_callback_method": "POST",

34
      "trunk_sid": null,

35
      "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",

36
      "voice_application_sid": "",

37
      "voice_caller_id_lookup": false,

38
      "voice_fallback_method": "POST",

39
      "voice_fallback_url": null,

40
      "voice_method": "POST",

41
      "voice_url": null,

42
      "bundle_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

43
      "voice_receive_mode": "voice",

44
      "status": "in-use",

45
      "subresource_uris": {

46
        "assigned_add_ons": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AssignedAddOns.json"

47
      }

48
    }

49
  ],

50
  "next_page_uri": null,

51
  "page": 0,

52
  "page_size": 50,

53
  "previous_page_uri": null,

54
  "start": 0,

55
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers.json?FriendlyName=friendly_name&Beta=true&PhoneNumber=%2B19876543210&PageSize=50&Page=0"

56
}
Filter IncomingPhoneNumbers with exact matchLink to code sample: Filter IncomingPhoneNumbers with exact match
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 listIncomingPhoneNumber() {

11
  const incomingPhoneNumbers = await client.incomingPhoneNumbers.list({

12
    phoneNumber: "+14158675310",

13
    limit: 20,

14
  });

15


16
  incomingPhoneNumbers.forEach((i) => console.log(i.accountSid));

17
}

18


19
listIncomingPhoneNumber();

Response

1
{

2
  "end": 0,

3
  "first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers.json?FriendlyName=friendly_name&Beta=true&PhoneNumber=%2B19876543210&PageSize=50&Page=0",

4
  "incoming_phone_numbers": [

5
    {

6
      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

7
      "address_requirements": "none",

8
      "address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

9
      "api_version": "2010-04-01",

10
      "beta": null,

11
      "capabilities": {

12
        "voice": true,

13
        "sms": false,

14
        "mms": true,

15
        "fax": false

16
      },

17
      "date_created": "Thu, 30 Jul 2015 23:19:04 +0000",

18
      "date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",

19
      "emergency_status": "Active",

20
      "emergency_address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

21
      "emergency_address_status": "registered",

22
      "friendly_name": "(808) 925-5327",

23
      "identity_sid": "RIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

24
      "origin": "origin",

25
      "phone_number": "+18089255327",

26
      "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

27
      "sms_application_sid": "",

28
      "sms_fallback_method": "POST",

29
      "sms_fallback_url": "",

30
      "sms_method": "POST",

31
      "sms_url": "",

32
      "status_callback": "",

33
      "status_callback_method": "POST",

34
      "trunk_sid": null,

35
      "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",

36
      "voice_application_sid": "",

37
      "voice_caller_id_lookup": false,

38
      "voice_fallback_method": "POST",

39
      "voice_fallback_url": null,

40
      "voice_method": "POST",

41
      "voice_url": null,

42
      "bundle_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

43
      "voice_receive_mode": "voice",

44
      "status": "in-use",

45
      "subresource_uris": {

46
        "assigned_add_ons": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AssignedAddOns.json"

47
      }

48
    }

49
  ],

50
  "next_page_uri": null,

51
  "page": 0,

52
  "page_size": 50,

53
  "previous_page_uri": null,

54
  "start": 0,

55
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers.json?FriendlyName=friendly_name&Beta=true&PhoneNumber=%2B19876543210&PageSize=50&Page=0"

56
}
Filter IncomingPhoneNumbers with partial matchLink to code sample: Filter IncomingPhoneNumbers with partial match
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 listIncomingPhoneNumber() {

11
  const incomingPhoneNumbers = await client.incomingPhoneNumbers.list({

12
    phoneNumber: "867",

13
    limit: 20,

14
  });

15


16
  incomingPhoneNumbers.forEach((i) => console.log(i.accountSid));

17
}

18


19
listIncomingPhoneNumber();

Response

1
{

2
  "end": 0,

3
  "first_page_uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers.json?FriendlyName=friendly_name&Beta=true&PhoneNumber=%2B19876543210&PageSize=50&Page=0",

4
  "incoming_phone_numbers": [

5
    {

6
      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

7
      "address_requirements": "none",

8
      "address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

9
      "api_version": "2010-04-01",

10
      "beta": null,

11
      "capabilities": {

12
        "voice": true,

13
        "sms": false,

14
        "mms": true,

15
        "fax": false

16
      },

17
      "date_created": "Thu, 30 Jul 2015 23:19:04 +0000",

18
      "date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",

19
      "emergency_status": "Active",

20
      "emergency_address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

21
      "emergency_address_status": "registered",

22
      "friendly_name": "(808) 925-5327",

23
      "identity_sid": "RIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

24
      "origin": "origin",

25
      "phone_number": "+18089255327",

26
      "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

27
      "sms_application_sid": "",

28
      "sms_fallback_method": "POST",

29
      "sms_fallback_url": "",

30
      "sms_method": "POST",

31
      "sms_url": "",

32
      "status_callback": "",

33
      "status_callback_method": "POST",

34
      "trunk_sid": null,

35
      "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",

36
      "voice_application_sid": "",

37
      "voice_caller_id_lookup": false,

38
      "voice_fallback_method": "POST",

39
      "voice_fallback_url": null,

40
      "voice_method": "POST",

41
      "voice_url": null,

42
      "bundle_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

43
      "voice_receive_mode": "voice",

44
      "status": "in-use",

45
      "subresource_uris": {

46
        "assigned_add_ons": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AssignedAddOns.json"

47
      }

48
    }

49
  ],

50
  "next_page_uri": null,

51
  "page": 0,

52
  "page_size": 50,

53
  "previous_page_uri": null,

54
  "start": 0,

55
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers.json?FriendlyName=friendly_name&Beta=true&PhoneNumber=%2B19876543210&PageSize=50&Page=0"

56
}

Update an IncomingPhoneNumber resource

update-an-incomingphonenumber-resource page anchor

POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.json

Path parameters

path-parameters-3 page anchor
Property nameTypeRequiredPIIDescription
accountSidSID<AC>
required
Not PII

The SID of the Account that created the IncomingPhoneNumber resource to update. For more information, see Exchanging Numbers Between Subaccounts.

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

The Twilio-provided string that uniquely identifies the IncomingPhoneNumber 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
accountSidSID<AC>

Optional

Not PII

The SID of the Account that created the IncomingPhoneNumber resource to update. For more information, see Exchanging Numbers Between Subaccounts.

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

Optional

Not PII

The API version to use for incoming calls made to the phone number. The default is 2010-04-01.

friendlyNamestring

Optional

PII MTL: 30 days

A descriptive string that you created to describe this phone number. It can be up to 64 characters long. By default, this is a formatted version of the phone number.

smsApplicationSidSID<AP>

Optional

Not PII

The SID of the application that should handle SMS messages sent to the number. If an sms_application_sid is present, we ignore all of the sms_*_url urls and use those set on the application.

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

Optional

Not PII

The HTTP method that we should use to call sms_fallback_url. Can be: GET or POST and defaults to POST.

Possible values:
GETPOST
smsFallbackUrlstring<uri>

Optional

Not PII

The URL that we should call when an error occurs while requesting or executing the TwiML defined by sms_url.

smsMethodenum<http-method>

Optional

Not PII

The HTTP method that we should use to call sms_url. Can be: GET or POST and defaults to POST.

Possible values:
GETPOST
smsUrlstring<uri>

Optional

Not PII

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

statusCallbackstring<uri>

Optional

Not PII

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

statusCallbackMethodenum<http-method>

Optional

Not PII

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

Possible values:
GETPOST
voiceApplicationSidSID<AP>

Optional

Not PII

The SID of the application we should use to handle phone calls to the phone number. If a voice_application_sid is present, we ignore all of the voice urls and use only 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
voiceCallerIdLookupboolean

Optional

Not PII

Whether to lookup the caller's name from the CNAM database and post it to your app. Can be: true or false and defaults to false.

voiceFallbackMethodenum<http-method>

Optional

Not PII

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

Possible values:
GETPOST
voiceFallbackUrlstring<uri>

Optional

Not PII

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

voiceMethodenum<http-method>

Optional

Not PII

The HTTP method that we should use to call voice_url. Can be: GET or POST and defaults to POST.

Possible values:
GETPOST
voiceUrlstring<uri>

Optional

Not PII

The URL that we should call to answer a call to the phone number. The voice_url will not be called if a voice_application_sid or a trunk_sid is set.

emergencyStatusenum<string>

Optional

Not PII

The parameter displays if emergency calling is enabled for this number. Active numbers may place emergency calls by dialing valid emergency numbers for the country.

Possible values:
ActiveInactive
emergencyAddressSidSID<AD>

Optional

Not PII

The SID of the emergency address configuration to use for emergency calling from this phone number.

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

Optional

Not PII

The SID of the Trunk we should use to handle phone calls to the phone number. If a trunk_sid is present, we ignore all of the voice urls and voice applications and use only 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
voiceReceiveModeenum<string>

Optional

Not PII
Possible values:
voicefax
identitySidSID<RI>

Optional

Not PII

The SID of the Identity resource that we should associate with the phone number. Some regions require an identity to meet local regulations.

Pattern: ^RI[0-9a-fA-F]{32}$Min length: 34Max length: 34
addressSidSID<AD>

Optional

Not PII

The SID of the Address resource we should associate with the phone number. Some regions require addresses to meet local regulations.

Pattern: ^AD[0-9a-fA-F]{32}$Min length: 34Max length: 34
bundleSidSID<BU>

Optional

Not PII

The SID of the Bundle resource that you associate with the phone number. Some regions require a Bundle to meet local Regulations.

Pattern: ^BU[0-9a-fA-F]{32}$Min length: 34Max length: 34
Update IncomingPhoneNumber to include an AddressSid and an BundleSidLink to code sample: Update IncomingPhoneNumber to include an AddressSid and an BundleSid
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 updateIncomingPhoneNumber() {

11
  const incomingPhoneNumber = await client

12
    .incomingPhoneNumbers("PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .update({

14
      addressSid: "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

15
      bundleSid: "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

16
    });

17


18
  console.log(incomingPhoneNumber.accountSid);

19
}

20


21
updateIncomingPhoneNumber();

Response

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "address_requirements": "none",

4
  "address_sid": "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

5
  "api_version": "2010-04-01",

6
  "beta": false,

7
  "capabilities": {

8
    "voice": true,

9
    "sms": false,

10
    "mms": true,

11
    "fax": false

12
  },

13
  "date_created": "Thu, 30 Jul 2015 23:19:04 +0000",

14
  "date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",

15
  "emergency_status": "Inactive",

16
  "emergency_address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

17
  "emergency_address_status": "registered",

18
  "friendly_name": "(808) 925-5327",

19
  "identity_sid": "RIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

20
  "origin": "origin",

21
  "phone_number": "+18089255327",

22
  "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

23
  "sms_application_sid": "",

24
  "sms_fallback_method": "POST",

25
  "sms_fallback_url": "",

26
  "sms_method": "POST",

27
  "sms_url": "",

28
  "status_callback": "",

29
  "status_callback_method": "POST",

30
  "trunk_sid": null,

31
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",

32
  "voice_application_sid": "",

33
  "voice_caller_id_lookup": true,

34
  "voice_fallback_method": "POST",

35
  "voice_fallback_url": null,

36
  "voice_method": "POST",

37
  "voice_url": null,

38
  "voice_receive_mode": "voice",

39
  "status": "in-use",

40
  "bundle_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

41
  "subresource_uris": {

42
    "assigned_add_ons": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AssignedAddOns.json"

43
  }

44
}
Update IncomingPhoneNumber to use a new Voice URLLink to code sample: Update IncomingPhoneNumber to use a new Voice URL
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 updateIncomingPhoneNumber() {

11
  const incomingPhoneNumber = await client

12
    .incomingPhoneNumbers("PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .update({ voiceUrl: "https://www.your-new-voice-url.com/example" });

14


15
  console.log(incomingPhoneNumber.accountSid);

16
}

17


18
updateIncomingPhoneNumber();

Response

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "address_requirements": "none",

4
  "address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "api_version": "2010-04-01",

6
  "beta": false,

7
  "capabilities": {

8
    "voice": true,

9
    "sms": false,

10
    "mms": true,

11
    "fax": false

12
  },

13
  "date_created": "Thu, 30 Jul 2015 23:19:04 +0000",

14
  "date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",

15
  "emergency_status": "Inactive",

16
  "emergency_address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

17
  "emergency_address_status": "registered",

18
  "friendly_name": "(808) 925-5327",

19
  "identity_sid": "RIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

20
  "origin": "origin",

21
  "phone_number": "+18089255327",

22
  "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

23
  "sms_application_sid": "",

24
  "sms_fallback_method": "POST",

25
  "sms_fallback_url": "",

26
  "sms_method": "POST",

27
  "sms_url": "",

28
  "status_callback": "",

29
  "status_callback_method": "POST",

30
  "trunk_sid": null,

31
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",

32
  "voice_application_sid": "",

33
  "voice_caller_id_lookup": true,

34
  "voice_fallback_method": "POST",

35
  "voice_fallback_url": null,

36
  "voice_method": "POST",

37
  "voice_url": "https://www.your-new-voice-url.com/example",

38
  "voice_receive_mode": "voice",

39
  "status": "in-use",

40
  "bundle_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

41
  "subresource_uris": {

42
    "assigned_add_ons": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AssignedAddOns.json"

43
  }

44
}
Update IncomingPhoneNumber to use a new SMS URLLink to code sample: Update IncomingPhoneNumber to use a new SMS URL
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 updateIncomingPhoneNumber() {

11
  const incomingPhoneNumber = await client

12
    .incomingPhoneNumbers("PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .update({ smsUrl: "https://www.your-new-sms-url.com/example" });

14


15
  console.log(incomingPhoneNumber.accountSid);

16
}

17


18
updateIncomingPhoneNumber();

Response

1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "address_requirements": "none",

4
  "address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "api_version": "2010-04-01",

6
  "beta": false,

7
  "capabilities": {

8
    "voice": true,

9
    "sms": false,

10
    "mms": true,

11
    "fax": false

12
  },

13
  "date_created": "Thu, 30 Jul 2015 23:19:04 +0000",

14
  "date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",

15
  "emergency_status": "Inactive",

16
  "emergency_address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

17
  "emergency_address_status": "registered",

18
  "friendly_name": "(808) 925-5327",

19
  "identity_sid": "RIaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

20
  "origin": "origin",

21
  "phone_number": "+18089255327",

22
  "sid": "PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

23
  "sms_application_sid": "",

24
  "sms_fallback_method": "POST",

25
  "sms_fallback_url": "",

26
  "sms_method": "POST",

27
  "sms_url": "https://www.your-new-sms-url.com/example",

28
  "status_callback": "",

29
  "status_callback_method": "POST",

30
  "trunk_sid": null,

31
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json",

32
  "voice_application_sid": "",

33
  "voice_caller_id_lookup": true,

34
  "voice_fallback_method": "POST",

35
  "voice_fallback_url": null,

36
  "voice_method": "POST",

37
  "voice_url": null,

38
  "voice_receive_mode": "voice",

39
  "status": "in-use",

40
  "bundle_sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

41
  "subresource_uris": {

42
    "assigned_add_ons": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers/PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AssignedAddOns.json"

43
  }

44
}

Delete an IncomingPhoneNumber resource

delete-an-incomingphonenumber-resource page anchor

DELETE https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{Sid}.json

Release this phone number from your account. Twilio will no longer answer calls to this number, and you will stop being billed the monthly phone number fee. The phone number will eventually be recycled and potentially given to another customer, so use with care. If you make a mistake, contact us. We may be able to give you the number back.

Path parameters

path-parameters-4 page anchor
Property nameTypeRequiredPIIDescription
accountSidSID<AC>
required
Not PII

The SID of the Account that created the IncomingPhoneNumber resources to delete.

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

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

Pattern: ^PN[0-9a-fA-F]{32}$Min length: 34Max length: 34
Delete an IncomingPhoneNumberLink to code sample: Delete an IncomingPhoneNumber
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 deleteIncomingPhoneNumber() {

11
  await client

12
    .incomingPhoneNumbers("PNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .remove();

14
}

15


16
deleteIncomingPhoneNumber();