REST API: Incoming Phone Numbers

An IncomingPhoneNumber instance resource represents a Twilio phone number purchased from Twilio or ported 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.

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.

IncomingPhoneNumber Instance Resource

Resource URI

/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{IncomingPhoneNumberSid}

Resource Properties

Property Description
Sid A 34 character string that uniquely identifies this resource.
DateCreated The date that this resource was created, given as GMT RFC 2822 format.
DateUpdated The date that this resource was last updated, given as GMT RFC 2822 format.
FriendlyName A human readable descriptive text for this resource, up to 64 characters long. By default, the FriendlyName is a nicely formatted version of the phone number.
AccountSid The unique id of the Account responsible for this phone number.
PhoneNumber The incoming phone number. e.g., +16175551212 (E.164 format)
ApiVersion Calls to this phone number will start a new TwiML session with this API version.
VoiceCallerIdLookup Look up the caller's caller-ID name from the CNAM database ($0.01 per look up). Either true or false.
VoiceUrl The URL Twilio will request when this phone number receives a call. The VoiceURL will no longer be used if a VoiceApplicationSid or a TrunkSid is set.
VoiceMethod The HTTP method Twilio will use when requesting the above Url. Either GET or POST.
VoiceFallbackUrl The URL that Twilio will request if an error occurs retrieving or executing the TwiML requested by Url.
VoiceFallbackMethod The HTTP method Twilio will use when requesting the VoiceFallbackUrl. Either GET or POST.
StatusCallback The URL that Twilio will request to pass status parameters (such as call ended) to your application.
StatusCallbackMethod The HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST.
VoiceApplicationSid The 34 character sid of the application Twilio should use to handle phone calls to this number. If a VoiceApplicationSid is present, Twilio will ignore all of the voice urls above and use those set on the application. Setting a VoiceApplicationSid will automatically delete your TrunkSid and vice versa.
TrunkSid The 34 character sid of the Trunk Twilio should use to handle phone calls to this number. If a TrunkSid is present, Twilio will ignore all of the voice urls and voice applications above and use those set on the Trunk. Setting a TrunkSid will automatically delete your VoiceApplicationSid and vice versa.
SmsUrl The URL Twilio will request when receiving an incoming SMS message to this number.
SmsMethod The HTTP method Twilio will use when making requests to the SmsUrl. Either GET or POST.
SmsFallbackUrl The URL that Twilio will request if an error occurs retrieving or executing the TwiML from SmsUrl.
SmsFallbackMethod The HTTP method Twilio will use when requesting the above URL. Either GET or POST.
SmsApplicationSid The 34 character sid of the application Twilio should use to handle SMSs sent to this number. If a SmsApplicationSid is present, Twilio will ignore all of the SMS urls above and use those set on the application.
Capabilities This is a set of boolean properties that indicate whether a phone number can receive calls or messages. Possible capabilities are Voice, SMS, and MMS with each having a value of either true or false.
AddressRequirements This indicates whether the phone number requires you or your customer to have an Address registered with Twilio. Possible values are none, any, local, or foreign.
Beta Phone numbers new to the Twilio platform are marked as beta. Possible values are either true or false.
Uri The URI for this resource, relative to https://api.twilio.com.

Address Requirement Values

The following are the possible values for the address_required property.

Status Description
none An Address is not required for this phone number.
any Your account must have an Address, but it can be anywhere in the world.
local Your account must have an Address within the phone number's country.
foreign Your account must have an Address outside the phone number's country.

HTTP GET

Example
Get an IncomingPhoneNumber
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "{{ auth_token }}";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var number = twilio.GetIncomingPhoneNumber("PN2a0747eba6abf96b7e3c3ff0b4530f6e");
    
    Console.WriteLine(number.PhoneNumber);
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.instance.IncomingPhoneNumber;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "{{ auth_token }}";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Get an object from its sid. If you do not have a sid,
    // check out the list resource examples on this page
    IncomingPhoneNumber number = client.getAccount().getIncomingPhoneNumber("PN2a0747eba6abf96b7e3c3ff0b4530f6e");
    System.out.println(number.getPhoneNumber());
    
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "{{ auth_token }}";
var client = require('twilio')(accountSid, authToken);

client.incomingPhoneNumbers("PN2a0747eba6abf96b7e3c3ff0b4530f6e").get(function(err, number) {
    console.log(number.phoneNumber);
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "{{ auth_token }}"; 
$client = new Services_Twilio($sid, $token);

// Get an object from its sid. If you do not have a sid,
// check out the list resource examples on this page
$number = $client->account->incoming_phone_numbers->get("PN2a0747eba6abf96b7e3c3ff0b4530f6e");
echo $number->phone_number;
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "{{ auth_token }}"
client = TwilioRestClient(account_sid, auth_token)

number = client.phone_numbers.get("PN2a0747eba6abf96b7e3c3ff0b4530f6e")
print number.phone_number
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = '{{ auth_token }}'
@client = Twilio::REST::Client.new account_sid, auth_token

# Get an object from its sid. If you do not have a sid,
# check out the list resource examples on this page
@number = @client.account.incoming_phone_numbers.get("PN2a0747eba6abf96b7e3c3ff0b4530f6e")
puts @number.phone_number
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PN2a0747eba6abf96b7e3c3ff0b4530f6e \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PN2a0747eba6abf96b7e3c3ff0b4530f6e.json \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
Show Output
  • JSON
  • XML
{
	"sid": "PN2a0747eba6abf96b7e3c3ff0b4530f6e",
	"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	"friendly_name": "My Company Line",
	"phone_number": "+15105647903",
	"voice_url": "http://demo.twilio.com/docs/voice.xml",
	"voice_method": "POST",
	"voice_fallback_url": null,
	"voice_fallback_method": "POST",
	"status_callback": null,
	"status_callback_method": null,
	"voice_caller_id_lookup": null,
	"voice_application_sid": null,
	"date_created": "Mon, 16 Aug 2010 23:00:23 +0000",
	"date_updated": "Mon, 16 Aug 2010 23:00:23 +0000",
	"sms_url": null,
	"sms_method": "POST",
	"sms_fallback_url": null,
	"sms_fallback_method": "GET",
	"sms_application_sid": "AP9b2e38d8c592488c397fc871a82a74ec",
	"capabilities": {
		"voice": true,
		"sms": true,
		"mms": false
	},
	"api_version": "2010-04-01",
	"uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/IncomingPhoneNumbers\/PN2a0747eba6abf96b7e3c3ff0b4530f6e.json"
}
<TwilioResponse>
	<IncomingPhoneNumber>
		<Sid>PN2a0747eba6abf96b7e3c3ff0b4530f6e</Sid>
		<AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
		<FriendlyName>My Company Line</FriendlyName>
		<PhoneNumber>+15105647903</PhoneNumber>
		<VoiceUrl>http://demo.twilio.com/docs/voice.xml</VoiceUrl>
		<VoiceMethod>POST</VoiceMethod>
		<VoiceFallbackUrl/>
		<VoiceFallbackMethod>POST</VoiceFallbackMethod>
		<StatusCallback/>
		<StatusCallbackMethod/>
		<VoiceCallerIdLookup>false</VoiceCallerIdLookup>
		<VoiceApplicationSid/>
		<DateCreated>Mon, 16 Aug 2010 23:00:23 +0000</DateCreated>
		<DateUpdated>Mon, 16 Aug 2010 23:00:23 +0000</DateUpdated>
		<SmsUrl/>
		<SmsMethod>POST</SmsMethod>
		<SmsFallbackUrl/>
		<SmsFallbackMethod>GET</SmsFallbackMethod>
		<SmsApplicationSid>AP9b2e38d8c592488c397fc871a82a74ec</SmsApplicationSid>
		<Capabilities>
			<Voice>true</Voice>
			<SMS>true</SMS>
			<MMS>false</MMS>
		</Capabilities>
		<ApiVersion>2010-04-01</ApiVersion>
		<Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PN2a0747eba6abf96b7e3c3ff0b4530f6e</Uri>
	</IncomingPhoneNumber>
</TwilioResponse>

HTTP POST and PUT

Tries to update the incoming phone number's properties, and returns the updated resource representation if successful. The returned response is identical to that returned above when making a GET request.

Optional Parameters

You may specify one or more of the following parameters to update this phone number's respective properties:

Parameter Description
FriendlyName A human readable description of the new incoming phone number resource, with maximum length 64 characters.
ApiVersion Calls to this phone number will start a new TwiML session with this API version. Either 2010-04-01 or 2008-08-01.
VoiceUrl The URL that Twilio should request when somebody dials the phone number. The VoiceURL will no longer be used if a VoiceApplicationSid or a TrunkSid is set.
VoiceMethod The HTTP method that should be used to request the VoiceUrl. Either GET or POST.
VoiceFallbackUrl A URL that Twilio will request if an error occurs requesting or executing the TwiML defined by VoiceUrl.
VoiceFallbackMethod The HTTP method that should be used to request the VoiceFallbackUrl. Either GET or POST.
StatusCallback The URL that Twilio will request to pass status parameters (such as call ended) to your application.
StatusCallbackMethod The HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST.
VoiceCallerIdLookup Do a lookup of a caller's name from the CNAM database and post it to your app. Either true or false.
VoiceApplicationSid The 34 character sid of the application Twilio should use to handle phone calls to this number. If a VoiceApplicationSid is present, Twilio will ignore all of the voice urls above and use those set on the application instead. Setting a VoiceApplicationSid will automatically delete your TrunkSid and vice versa.
TrunkSid The 34 character sid of the Trunk Twilio should use to handle phone calls to this number. If a TrunkSid is present, Twilio will ignore all of the voice urls and voice applications above and use those set on the Trunk. Setting a TrunkSid will automatically delete your VoiceApplicationSid and vice versa.
SmsUrl The URL that Twilio should request when somebody sends an SMS to the new phone number.
SmsMethod The HTTP method that should be used to request the SmsUrl. Either GET or POST.
SmsFallbackUrl A URL that Twilio will request if an error occurs requesting or executing the TwiML defined by SmsUrl.
SmsFallbackMethod The HTTP method that should be used to request the SmsFallbackUrl. Either GET or POST.
SmsApplicationSid The 34 character sid of the application Twilio should use to handle SMSs sent to this number. If a SmsApplicationSid is present, Twilio will ignore all of the SMS urls above and use those set on the application instead.
AccountSid The unique 34 character id of the account to which you wish to transfer this phone number. See Exchanging Numbers Between Subaccounts.
Example 1

Set the VoiceUrl and SmsUrl on a phone number

Update an IncomingPhoneNumber
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "{{ auth_token }}";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var options = new PhoneNumberOptions();
    options.VoiceUrl = "http://demo.twilio.com/docs/voice.xml";
    options.SmsUrl = "http://demo.twilio.com/docs/sms.xml";
    
    twilio.UpdateIncomingPhoneNumber("PN2a0747eba6abf96b7e3c3ff0b4530f6e", options);
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.instance.IncomingPhoneNumber;
import com.twilio.sdk.resource.list.IncomingPhoneNumberList;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "{{ auth_token }}";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Get an object from its sid. If you do not have a sid,
    // check out the list resource examples on this page
    IncomingPhoneNumber number = client.getAccount().getIncomingPhoneNumber("PN2a0747eba6abf96b7e3c3ff0b4530f6e");
    // Build a filter for the IncomingPhoneNumberList
    List<NameValuePair> params = new ArrayList<NameValuePair>();
    params.add(new BasicNameValuePair("VoiceUrl", "http://demo.twilio.com/docs/voice.xml"));
    params.add(new BasicNameValuePair("SmsUrl", "http://demo.twilio.com/docs/sms.xml"));
    number.update(params); 
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "{{ auth_token }}";
var client = require('twilio')(accountSid, authToken);

client.incomingPhoneNumbers("PN2a0747eba6abf96b7e3c3ff0b4530f6e").update({
    voiceUrl: "http://demo.twilio.com/docs/voice.xml",
    smsUrl: "http://demo.twilio.com/docs/sms.xml"
}, function(err, number) {
    console.log(number.voiceUrl);
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "{{ auth_token }}"; 
$client = new Services_Twilio($sid, $token);

// Get an object from its sid. If you do not have a sid,
// check out the list resource examples on this page
$number = $client->account->incoming_phone_numbers->get("PN2a0747eba6abf96b7e3c3ff0b4530f6e");
$number->update(array(
        "VoiceUrl" => "http://demo.twilio.com/docs/voice.xml",
    "SmsUrl" => "http://demo.twilio.com/docs/sms.xml"
    ));
echo $number->voice_url;
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "{{ auth_token }}"
client = TwilioRestClient(account_sid, auth_token)

number = client.phone_numbers.update("PN2a0747eba6abf96b7e3c3ff0b4530f6e", voice_url="http://demo.twilio.com/docs/voice.xml",
    sms_url="http://demo.twilio.com/docs/sms.xml")
print number.voice_url
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = '{{ auth_token }}'
@client = Twilio::REST::Client.new account_sid, auth_token

# Get an object from its sid. If you do not have a sid,
# check out the list resource examples on this page
@number = @client.account.incoming_phone_numbers.get("PN2a0747eba6abf96b7e3c3ff0b4530f6e")
@number.update(:voice_url => "http://demo.twilio.com/docs/voice.xml",
    :sms_url => "http://demo.twilio.com/docs/sms.xml")
puts @number.voice_url
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PN2a0747eba6abf96b7e3c3ff0b4530f6e \
    -d "VoiceUrl=http://demo.twilio.com/docs/voice.xml" \
    -d "SmsUrl=http://demo.twilio.com/docs/sms.xml" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PN2a0747eba6abf96b7e3c3ff0b4530f6e.json \
    -d "VoiceUrl=http://demo.twilio.com/docs/voice.xml" \
    -d "SmsUrl=http://demo.twilio.com/docs/sms.xml" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
Show Output
  • JSON
  • XML
{
	"sid": "PN2a0747eba6abf96b7e3c3ff0b4530f6e",
	"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	"friendly_name": "My Company Line",
	"phone_number": "+15105647903",
	"voice_url": "http://demo.twilio.com/docs/voice.xml",
	"voice_method": "POST",
	"voice_fallback_url": null,
	"voice_fallback_method": "POST",
	"voice_caller_id_lookup": null,
	"voice_application_sid": null,
	"date_created": "Mon, 16 Aug 2010 23:00:23 +0000",
	"date_updated": "Mon, 16 Aug 2010 23:00:23 +0000",
	"sms_url": "http://demo.twilio.com/docs/sms.xml",
	"sms_method": "POST",
	"sms_fallback_url": null,
	"sms_fallback_method": "GET",
	"sms_application_sid": null,
	"capabilities": {
		"voice": true,
		"sms": true,
		"mms": false
	},
	"status_callback": null,
	"status_callback_method": null,
	"api_version": "2010-04-01",
	"uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/IncomingPhoneNumbers\/PN2a0747eba6abf96b7e3c3ff0b4530f6e.json"
}
<TwilioResponse>
	<IncomingPhoneNumber>
		<Sid>PN2a0747eba6abf96b7e3c3ff0b4530f6e</Sid>
		<AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
		<FriendlyName>My Company Line</FriendlyName>
		<PhoneNumber>+15105647903</PhoneNumber>
		<VoiceUrl>http://demo.twilio.com/docs/voice.xml</VoiceUrl>
		<VoiceMethod>POST</VoiceMethod>
		<VoiceFallbackUrl/>
		<VoiceFallbackMethod>POST</VoiceFallbackMethod>
		<VoiceCallerIdLookup>false</VoiceCallerIdLookup>
		<VoiceApplicationSid/>
		<DateCreated>Mon, 16 Aug 2010 23:00:23 +0000</DateCreated>
		<DateUpdated>Mon, 16 Aug 2010 23:00:23 +0000</DateUpdated>
		<SmsUrl>http://demo.twilio.com/docs/sms.xml</SmsUrl>
		<SmsMethod>POST</SmsMethod>
		<SmsFallbackUrl/>
		<SmsFallbackMethod>GET</SmsFallbackMethod>
		<SmsApplicationSid/>
		<Capabilities>
			<Voice>true</Voice>
			<SMS>true</SMS>
			<MMS>false</MMS>
		</Capabilities>
		<StatusCallback/>
		<StatusCallbackMethod/>
		<ApiVersion>2010-04-01</ApiVersion>
		<Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PN2a0747eba6abf96b7e3c3ff0b4530f6e</Uri>
	</IncomingPhoneNumber>
</TwilioResponse>

HTTP DELETE

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.

If successful, returns an HTTP 204 response with no body.

IncomingPhoneNumbers List Resource

Resource URI

/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers

HTTP GET

Returns a list of IncomingPhoneNumber resource representations, each representing a phone number given to your account. The list includes paging information.

List Filters

The following query string parameters allow you to limit the list returned. Note, parameters are case-sensitive:

Parameter Description
PhoneNumber Only show the incoming phone number resources that match this pattern. You can specify partial numbers and use '*' as a wildcard for any digit.
FriendlyName Only show the incoming phone number resources with friendly names that exactly match this name.
Beta Include phone numbers new to the Twilio platform. Possible values are either true or false. Default is true.
Example 1
List all IncomingPhoneNumber of your Account
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "{{ auth_token }}";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var numbers = twilio.ListIncomingPhoneNumbers(null, null, null, null);
    
    foreach (var number in numbers.IncomingPhoneNumbers)
    {
      Console.WriteLine(number.PhoneNumber);
    }
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.instance.IncomingPhoneNumber;
import com.twilio.sdk.resource.list.IncomingPhoneNumberList;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "{{ auth_token }}";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);
    
    IncomingPhoneNumberList numbers = client.getAccount().getIncomingPhoneNumbers();
    
    // Loop over numbers and print out a property for each one.
    for (IncomingPhoneNumber number : numbers) {
      System.out.println(number.getPhoneNumber());
    } 
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "{{ auth_token }}";
var client = require('twilio')(accountSid, authToken);

client.incomingPhoneNumbers.list(function(err, data) {
    data.numbers.forEach(function(number) {
        console.log(number.phoneNumber);
    });
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "{{ auth_token }}"; 
$client = new Services_Twilio($sid, $token);

// Loop over the list of numbers and echo a property for each one
foreach ($client->account->incoming_phone_numbers as $number) {
    echo $number->phone_number;
}
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "{{ auth_token }}"
client = TwilioRestClient(account_sid, auth_token)

# A list of number objects with the properties described above
numbers = client.phone_numbers.list()
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = '{{ auth_token }}'
@client = Twilio::REST::Client.new account_sid, auth_token


# Loop over numbers and print out a property for each one
@client.account.incoming_phone_numbers.list.each do |number|
    puts number.phone_number
end
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers.json \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
Show Output
  • JSON
  • XML
{
	"page": 0,
	"page_size": 50,
	"uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/IncomingPhoneNumbers.json",
	"first_page_uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/IncomingPhoneNumbers.json?Page=0&PageSize=50",
	"previous_page_uri": null,
	"next_page_uri": null,
	"incoming_phone_numbers": [
		{
			"sid": "PN3f94c94562ac88dccf16f8859a1a8b25",
			"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
			"friendly_name": "Long Play",
			"phone_number": "+14152374451",
			"voice_url": "http:\/\/demo.twilio.com\/docs/voice.xml",
			"voice_method": "GET",
			"voice_fallback_url": null,
			"voice_fallback_method": null,
			"voice_caller_id_lookup": null,
			"voice_application_sid": null,
			"date_created": "Thu, 13 Nov 2008 07:56:24 +0000",
			"date_updated": "Thu, 13 Nov 2008 08:45:58 +0000",
			"sms_url": null,
			"sms_method": null,
			"sms_fallback_url": null,
			"sms_fallback_method": null,
			"sms_application_sid": AP9b2e38d8c592488c397fc871a82a74ec,
			"capabilities": {
				"voice": true,
				"sms": false,
				"mms": false
			},
			"status_callback": null,
			"status_callback_method": null,
			"api_version": "2010-04-01",
			"uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/IncomingPhoneNumbers\/PN3f94c94562ac88dccf16f8859a1a8b25.json"
		},
		...
	]
}
<TwilioResponse>
	<IncomingPhoneNumbers page="0" pagesize="50" uri="/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers" firstpageuri="/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers?Page=0&PageSize=50" previouspageuri="" nextpageuri="">
		<IncomingPhoneNumber>
			<Sid>PN3f94c94562ac88dccf16f8859a1a8b25</Sid>
			<AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
			<FriendlyName>Long Play</FriendlyName>
			<PhoneNumber>+14152374451</PhoneNumber>
			<VoiceUrl>http://demo.twilio.com/docs/voice.xml</VoiceUrl>
			<VoiceMethod>GET</VoiceMethod>
			<VoiceFallbackUrl/>
			<VoiceFallbackMethod/>
			<VoiceCallerIdLookup>false</VoiceCallerIdLookup>
			<VoiceApplicationSid/>
			<DateCreated>Thu, 13 Nov 2008 07:56:24 +0000</DateCreated>
			<DateUpdated>Thu, 13 Nov 2008 08:45:58 +0000</DateUpdated>
			<SmsUrl/>
			<SmsMethod/>
			<SmsFallbackUrl/>
			<SmsFallbackMethod/>
			<SmsApplicationSid>AP9b2e38d8c592488c397fc871a82a74ec</SmsApplicationSid>
			<Capabilities>
				<Voice>true</Voice>
				<SMS>false</SMS>
				<MMS>false</MMS>
			</Capabilities>
			<StatusCallback/>
			<StatusCallbackMethod/>
			<ApiVersion>2010-04-01</ApiVersion>
			<Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PN3f94c94562ac88dccf16f8859a1a8b25</Uri>
		</IncomingPhoneNumber>
		...
	</IncomingPhoneNumbers>
</TwilioResponse>
Example 2

Return the set of phone numbers that match exactly (415) 867-5309.

Filter IncomingPhoneNumbers with Exact Match
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "{{ auth_token }}";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var numbers = twilio.ListIncomingPhoneNumbers("+14158675309", null, null, null);
    
    foreach (var number in numbers.IncomingPhoneNumbers)
    {
      Console.WriteLine(number.PhoneNumber);
    }
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.instance.IncomingPhoneNumber;
import com.twilio.sdk.resource.list.IncomingPhoneNumberList;
import java.util.HashMap;
import java.util.Map;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "{{ auth_token }}";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Build a filter for the IncomingPhoneNumberList
    Map<String, String> params = new HashMap<String, String>();
    
    params.put("PhoneNumber", "+14158675309");
    
    IncomingPhoneNumberList numbers = client.getAccount().getIncomingPhoneNumbers(params);
    
    // Loop over numbers and print out a property for each one.
    for (IncomingPhoneNumber number : numbers) {
      System.out.println(number.getPhoneNumber());
    } 
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "{{ auth_token }}";
var client = require('twilio')(accountSid, authToken);

client.incomingPhoneNumbers.list({ 
  phoneNumber: "+14158675309" 
  }, function(err, data) {
    data.numbers.forEach(function(number) {
        console.log(number.phoneNumber);
    });
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "{{ auth_token }}"; 
$client = new Services_Twilio($sid, $token);

// Loop over the list of numbers and echo a property for each one
foreach ($client->account->incoming_phone_numbers->getIterator(0, 50, array(
        "PhoneNumber" => "+14158675309"
    )) as $number
) {
    echo $number->phone_number;
}
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "{{ auth_token }}"
client = TwilioRestClient(account_sid, auth_token)

# A list of number objects with the properties described above
numbers = client.phone_numbers.list(phone_number="+14158675309")
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = '{{ auth_token }}'
@client = Twilio::REST::Client.new account_sid, auth_token


# Loop over numbers and print out a property for each one
@client.account.incoming_phone_numbers.list({
    :phone_number => "+14158675309"}).each do |number|
    puts number.phone_number
end
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers \
    -d "PhoneNumber=%2B14158675309" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers.json \
    -d "PhoneNumber=%2B14158675309" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
Show Output
  • JSON
  • XML
{
    "page": 0,
    "page_size": 50,
    "uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/IncomingPhoneNumbers.xml?PhoneNumber=%2B14158675309",
    "first_page_uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/IncomingPhoneNumbers.xml?PhoneNumber=%2B18675309&Page=0&PageSize=50",
    "previous_page_uri": null,
    "next_page_uri": null,
    "incoming_phone_numbers": [
        {
            "sid": "PN3f94c94562ac88dccf16f8859a1a8b25",
            "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "friendly_name": "Jenny",
            "phone_number": "+14158675309",
            "voice_url": "http:\/\/demo.twilio.com\/docs/voice.xml",
            "voice_method": "GET",
            "voice_fallback_url": null,
            "voice_fallback_method": null,
            "voice_caller_id_lookup": null,
            "voice_application_sid": null,
            "date_created": "Thu, 13 Nov 2008 07:56:24 +0000",
            "date_updated": "Thu, 13 Nov 2008 08:45:58 +0000",
            "sms_url": null,
            "sms_method": null,
            "sms_fallback_url": null,
            "sms_fallback_method": null,
            "sms_application_sid": AP9b2e38d8c592488c397fc871a82a74ec,
            "capabilities": {
                "voice": true,
                "sms": false,
                "mms": false
            },
            "status_callback": null,
            "status_callback_method": null,
            "api_version": "2010-04-01",
            "uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/IncomingPhoneNumbers\/PN3f94c94562ac88dccf16f8859a1a8b26.json"
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
    <IncomingPhoneNumbers page="0" pagesize="50" uri="/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers.xml?PhoneNumber=%2B14158675309" firstpageuri="/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers.xml?PhoneNumber=%2B14158675309&Page=0&PageSize=50" previouspageuri="" nextpageuri="">
        <IncomingPhoneNumber>
            <Sid>PN3f94c94562ac88dccf16f8859a1a8b25</Sid>
            <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
            <FriendlyName>Jenny</FriendlyName>
            <PhoneNumber>+14158675309</PhoneNumber>
            <VoiceUrl>http://demo.twilio.com/docs/voice.xml</VoiceUrl>
            <VoiceMethod>GET</VoiceMethod>
            <VoiceFallbackUrl/>
            <VoiceFallbackMethod/>
            <VoiceCallerIdLookup>false</VoiceCallerIdLookup>
            <VoiceApplicationSid/>
            <DateCreated>Thu, 13 Nov 2008 07:56:24 +0000</DateCreated>
            <DateUpdated>Thu, 13 Nov 2008 08:45:58 +0000</DateUpdated>
            <SmsUrl/>
            <SmsMethod/>
            <SmsFallbackUrl/>
            <SmsFallbackMethod/>
            <SmsApplicationSid>AP9b2e38d8c592488c397fc871a82a74ec</SmsApplicationSid>
            <Capabilities>
                <Voice>true</Voice>
                <SMS>false</SMS>
                <MMS>false</MMS>
            </Capabilities>
            <StatusCallback/>
            <StatusCallbackMethod/>
            <ApiVersion>2010-04-01</ApiVersion>
            <Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PN3f94c94562ac88dccf16f8859a1a8b26</Uri>
        </IncomingPhoneNumber>
    </IncomingPhoneNumbers>
</TwilioResponse>
Example 3

Return the set of all phone numbers containing the digits 867.

Filter IncomingPhoneNumbers with Partial Match
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "{{ auth_token }}";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var numbers = twilio.ListIncomingPhoneNumbers("867", null, null, null);
    
    foreach (var number in numbers.IncomingPhoneNumbers)
    {
      Console.WriteLine(number.VoiceUrl);
    }
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.instance.IncomingPhoneNumber;
import com.twilio.sdk.resource.list.IncomingPhoneNumberList;
import java.util.HashMap;
import java.util.Map;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "{{ auth_token }}";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Build a filter for the IncomingPhoneNumberList
    Map<String, String> params = new HashMap<String, String>();
    
    params.put("PhoneNumber", "867");
    
    IncomingPhoneNumberList numbers = client.getAccount().getIncomingPhoneNumbers(params);
    
    // Loop over numbers and print out a property for each one.
    for (IncomingPhoneNumber number : numbers) {
      System.out.println(number.getVoiceUrl());
    } 
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "{{ auth_token }}";
var client = require('twilio')(accountSid, authToken);

client.incomingPhoneNumbers.list({ 
  phoneNumber: "867" 
  }, function(err, data) {
    data.numbers.forEach(function(number) {
        console.log(number.voiceUrl);
    });
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "{{ auth_token }}"; 
$client = new Services_Twilio($sid, $token);

// Loop over the list of numbers and echo a property for each one
foreach ($client->account->incoming_phone_numbers->getIterator(0, 50, array(
        "PhoneNumber" => "867"
    )) as $number
) {
    echo $number->voice_url;
}
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "{{ auth_token }}"
client = TwilioRestClient(account_sid, auth_token)

# A list of number objects with the properties described above
numbers = client.phone_numbers.list(phone_number="867")
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = '{{ auth_token }}'
@client = Twilio::REST::Client.new account_sid, auth_token

# Loop over numbers and print out a property for each one
@client.account.incoming_phone_numbers.list({
    :phone_number => "867"}).each do |number|
    puts number.voice_url
end
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers \
    -d "PhoneNumber=867" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers.json \
    -d "PhoneNumber=867" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
Show Output
  • JSON
  • XML
{
    "page": 0,
    "page_size": 50,
    "uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/IncomingPhoneNumbers.xml?PhoneNumber=415",
    "first_page_uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/IncomingPhoneNumbers.xml?PhoneNumber=415&Page=0&PageSize=50",
    "previous_page_uri": null,
    "next_page_uri": null,
    "incoming_phone_numbers": [
        {
            "sid": "PN3f94c94562ac88dccf16f8859a1a8b25",
            "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "friendly_name": "Jenny",
            "phone_number": "+14158675309",
            "voice_url": "http:\/\/demo.twilio.com\/docs/voice.xml",
            "voice_method": "GET",
            "voice_fallback_url": null,
            "voice_fallback_method": null,
            "voice_caller_id_lookup": null,
            "voice_application_sid": null,
            "date_created": "Thu, 13 Nov 2008 07:56:24 +0000",
            "date_updated": "Thu, 13 Nov 2008 08:45:58 +0000",
            "sms_url": null,
            "sms_method": null,
            "sms_fallback_url": null,
            "sms_fallback_method": null,
            "sms_application_sid": AP9b2e38d8c592488c397fc871a82a74ec,
            "capabilities": {
                "voice": true,
                "sms": false,
                "mms": false
            },
            "status_callback": null,
            "status_callback_method": null,
            "api_version": "2010-04-01",
            "uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/IncomingPhoneNumbers\/PN3f94c94562ac88dccf16f8859a1a8b26.json"
        },
        ...
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<TwilioResponse>
    <IncomingPhoneNumbers page="0" pagesize="50" uri="/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers.xml?PhoneNumber=%2B14158675309" firstpageuri="/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers.xml?PhoneNumber=%2B14158675309&Page=0&PageSize=50" previouspageuri="" nextpageuri="">
        <IncomingPhoneNumber>
            <Sid>PN3f94c94562ac88dccf16f8859a1a8b25</Sid>
            <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
            <FriendlyName>Jenny</FriendlyName>
            <PhoneNumber>+14158675309</PhoneNumber>
            <VoiceUrl>http://demo.twilio.com/docs/voice.xml</VoiceUrl>
            <VoiceMethod>GET</VoiceMethod>
            <VoiceFallbackUrl/>
            <VoiceFallbackMethod/>
            <VoiceCallerIdLookup>false</VoiceCallerIdLookup>
            <VoiceApplicationSid/>
            <DateCreated>Thu, 13 Nov 2008 07:56:24 +0000</DateCreated>
            <DateUpdated>Thu, 13 Nov 2008 08:45:58 +0000</DateUpdated>
            <SmsUrl/>
            <SmsMethod/>
            <SmsFallbackUrl/>
            <SmsFallbackMethod/>
            <SmsApplicationSid>AP9b2e38d8c592488c397fc871a82a74ec</SmsApplicationSid>
            <Capabilities>
                <Voice>true</Voice>
                <SMS>false</SMS>
                <MMS>false</MMS>
            </Capabilities>
            <StatusCallback/>
            <StatusCallbackMethod/>
            <ApiVersion>2010-04-01</ApiVersion>
            <Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PN3f94c94562ac88dccf16f8859a1a8b26</Uri>
        </IncomingPhoneNumber>
		...
    </IncomingPhoneNumbers>
</TwilioResponse>

HTTP POST

Purchases a new phone number for your account. If a phone number is found for your request, Twilio will add it to your account and bill you for the first month's cost of the phone number. If Twilio cannot find a phone number to match your request, you will receive an HTTP 400 with Twilio error code 21452.

To find an available phone number to POST, use the subresources of the AvailablePhoneNumbers list resource.

Required Parameters

Your request must include exactly one of the following parameters:

Parameter Description
PhoneNumber The phone number you want to purchase. The number should be formatted starting with a '+' followed by the country code and the number in E.164 format e.g., '+15105555555'. You must include either this or an AreaCode parameter to have your POST succeed.
AreaCode The desired area code for your new incoming phone number. Any three digit, US or Canada area code is valid. Twilio will provision a random phone number within this area code for you. You must include either this or a PhoneNumber parameter to have your POST succeed. (US and Canada only)

If you include both parameters, we will use the AreaCode parameter and ignore the PhoneNumber provided.

Optional Parameters

Your request may include the following parameters:

Parameter Description
FriendlyName A human readable description of the new incoming phone number. Maximum 64 characters. Defaults to a formatted version of the number.
VoiceUrl The URL that Twilio should request when somebody dials the new phone number. The VoiceURL will no longer be used if a VoiceApplicationSid or a TrunkSid is set.
VoiceMethod The HTTP method that should be used to request the VoiceUrl. Must be either GET or POST. Defaults to POST.
VoiceFallbackUrl A URL that Twilio will request if an error occurs requesting or executing the TwiML at Url.
VoiceFallbackMethod The HTTP method that should be used to request the VoiceFallbackUrl. Either GET or POST. Defaults to POST.
StatusCallback The URL that Twilio will request to pass status parameters (such as call ended) to your application.
StatusCallbackMethod The HTTP method Twilio will use to make requests to the StatusCallback URL. Either GET or POST. Defaults to POST.
VoiceCallerIdLookup Do a lookup of a caller's name from the CNAM database and post it to your app. Either true or false. Defaults to false.
VoiceApplicationSid The 34 character sid of the application Twilio should use to handle phone calls to the new number. If a VoiceApplicationSid is present, Twilio will ignore all of the voice urls above and use those set on the application. Setting a VoiceApplicationSid will automatically delete your TrunkSid and vice versa.
TrunkSid The 34 character sid of the Trunk Twilio should use to handle phone calls to this number. If a TrunkSid is present, Twilio will ignore all of the voice urls and voice applications above and use those set on the Trunk. Setting a TrunkSid will automatically delete your VoiceApplicationSid and vice versa.
SmsUrl The URL that Twilio should request when somebody sends an SMS to the phone number.
SmsMethod The HTTP method that should be used to request the SmsUrl. Must be either GET or POST. Defaults to POST.
SmsFallbackUrl A URL that Twilio will request if an error occurs requesting or executing the TwiML defined by SmsUrl.
SmsFallbackMethod The HTTP method that should be used to request the SmsFallbackUrl. Must be either GET or POST. Defaults to POST.
SmsApplicationSid The 34 character sid of the application Twilio should use to handle SMSs sent to the new number. If a SmsApplicationSid is present, Twilio will ignore all of the SMS urls above and use those set on the application.
ApiVersion The Twilio REST API version to use for incoming calls made to this number. If omitted, uses 2010-04-01.

If successful, Twilio responds with a representation of the new phone number that was assigned to your account.

NOTE: You cannot request numbers while you are using a Free Trial account. You must upgrade your account to purchase a Twilio phone number.
Example
Create a New IncomingPhoneNumber
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "{{ auth_token }}";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var options = new PhoneNumberOptions();
    options.FriendlyName = "My Company Line";
    options.VoiceUrl = "http://demo.twilio.com/docs/voice.xml";
    options.PhoneNumber = "+15105647903";
    options.VoiceMethod = "GET";
    var number = twilio.AddIncomingPhoneNumber(options);
    
    Console.WriteLine(number.Sid);
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.factory.IncomingPhoneNumberFactory;
import com.twilio.sdk.resource.instance.IncomingPhoneNumber;
import com.twilio.sdk.resource.list.IncomingPhoneNumberList;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "{{ auth_token }}";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Build a filter for the IncomingPhoneNumberList
    List<NameValuePair> params = new ArrayList<NameValuePair>();
    params.add(new BasicNameValuePair("FriendlyName", "My Company Line"));
    params.add(new BasicNameValuePair("VoiceUrl", "http://demo.twilio.com/docs/voice.xml"));
    params.add(new BasicNameValuePair("PhoneNumber", "+15105647903"));
    params.add(new BasicNameValuePair("VoiceMethod", "GET"));
    
    IncomingPhoneNumberFactory numberFactory = client.getAccount().getIncomingPhoneNumberFactory();
    IncomingPhoneNumber number = numberFactory.create(params);
    System.out.println(number.getSid());
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "{{ auth_token }}";
var client = require('twilio')(accountSid, authToken);

client.incomingPhoneNumbers.create({
    friendlyName: "My Company Line",
    voiceUrl: "http://demo.twilio.com/docs/voice.xml",
    phoneNumber: "+15105647903",
    voiceMethod: "GET"
}, function(err, number) {
    console.log(number.sid);
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "{{ auth_token }}"; 
$client = new Services_Twilio($sid, $token);

$number = $client->account->incoming_phone_numbers->create(array(
        "FriendlyName" => "My Company Line",
    "VoiceUrl" => "http://demo.twilio.com/docs/voice.xml",
    "PhoneNumber" => "+15105647903",
    "VoiceMethod" => "GET"
    ));
echo $number->sid;
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "{{ auth_token }}"
client = TwilioRestClient(account_sid, auth_token)

number = client.phone_numbers.purchase(friendly_name="My Company Line",
    voice_url="http://demo.twilio.com/docs/voice.xml",
    phone_number="+15105647903",
    voice_method="GET")
print number.sid
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = '{{ auth_token }}'
@client = Twilio::REST::Client.new account_sid, auth_token

number = @client.account.incoming_phone_numbers.create(:friendly_name => "My Company Line",
    :voice_url => "http://demo.twilio.com/docs/voice.xml",
    :phone_number => "+15105647903",
    :voice_method => "GET")
puts number.sms_url
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers \
    -d "FriendlyName=My%20Company%20Line" \
    -d "VoiceUrl=http://demo.twilio.com/docs/voice.xml" \
    -d "PhoneNumber=%2B15105647903" \
    -d "VoiceMethod=GET" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers.json \
    -d "FriendlyName=My%20Company%20Line" \
    -d "VoiceUrl=http://demo.twilio.com/docs/voice.xml" \
    -d "PhoneNumber=%2B15105647903" \
    -d "VoiceMethod=GET" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:{{ auth_token }}'
Show Output
  • JSON
  • XML
{
	"sid": "PN2a0747eba6abf96b7e3c3ff0b4530f6e",
	"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
	"friendly_name": "My Company Line",
	"phone_number": "+15105647903",
	"voice_url": "http://demo.twilio.com/docs/voice.xml",
	"voice_method": "POST",
	"voice_fallback_url": null,
	"voice_fallback_method": "POST",
	"voice_caller_id_lookup": null,
	"voice_application_sid": null,
	"date_created": "Mon, 16 Aug 2010 23:31:47 +0000",
	"date_updated": "Mon, 16 Aug 2010 23:31:47 +0000",
	"sms_url": null,
	"sms_method": "POST",
	"sms_fallback_url": null,
	"sms_fallback_method": "GET",
	"sms_application_sid": null,
	"capabilities": {
		"voice": true,
		"sms": true
		"mms": false
	},
	"status_callback": null,
	"status_callback_method": null,
	"api_version": "2010-04-01",
	"uri": "\/2010-04-01\/Accounts\/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\/IncomingPhoneNumbers\/PN2a0747eba6abf96b7e3c3ff0b4530f6e.json"
}
<TwilioResponse>
	<IncomingPhoneNumber>
		<Sid>PN2a0747eba6abf96b7e3c3ff0b4530f6e</Sid>
		<AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
		<FriendlyName>My Company Line</FriendlyName>
		<PhoneNumber>+15105647903</PhoneNumber>
		<VoiceUrl>http://demo.twilio.com/docs/voice.xml</VoiceUrl>
		<VoiceMethod>GET</VoiceMethod>
		<VoiceFallbackUrl></VoiceFallbackUrl>
		<VoiceFallbackMethod>POST</VoiceFallbackMethod>
		<VoiceCallerIdLookup>false</VoiceCallerIdLookup>
		<VoiceApplicationSid/>
		<DateCreated>Mon, 16 Aug 2010 23:00:23 +0000</DateCreated>
		<DateUpdated>Mon, 16 Aug 2010 23:00:23 +0000</DateUpdated>
		<SmsUrl></SmsUrl>
		<SmsMethod>POST</SmsMethod>
		<SmsFallbackUrl></SmsFallbackUrl>
		<SmsFallbackMethod>GET</SmsFallbackMethod>
		<SmsApplicationSid/>
		<Capabilities>
			<Voice>true</Voice>
			<SMS>true</SMS>
			<MMS>false</MMS>
		</Capabilities>
		<StatusCallback/>
		<StatusCallbackMethod/>
		<ApiVersion>2010-04-01</ApiVersion>
		<Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PN2a0747eba6abf96b7e3c3ff0b4530f6e</Uri>
	</IncomingPhoneNumber>
</TwilioResponse>

HTTP PUT

Not Supported.

HTTP DELETE

Not Supported.

Local IncomingPhoneNumber Factory Resource

POSTing to this resource allows you to request a new local phone number be added to your account. This subresource represents only Local phone numbers, i.e. not toll-free numbers.

Resource URI

/2010-04-01/Accounts/{YourAccountSid}/IncomingPhoneNumbers/Local

HTTP Methods

HTTP GET

Returns a list of local <IncomingPhoneNumber> elements, each representing a local (not toll-free) phone number given to your account, under an <IncomingPhoneNumbers> list element that includes paging information. Works exactly the same as the IncomingPhoneNumber resource, but filters out toll-free numbers.

HTTP POST

Adds a new phone number to your account. If a phone number is found for your request, Twilio will add it to your account and bill you for the first month's cost of the phone number. If Twilio can't find a phone number to match your request, you will receive an HTTP 400 with Twilio error code 21452.

To find an available phone number to POST, use the subresources of the AvailablePhoneNumbers list resource.

Required Parameters

Your request must include PhoneNumber. We do not support AreaCode for this subresource:

Parameter Description
PhoneNumber The phone number you want to purchase. The number should be formatted starting with a '+' followed by the country code and the number in E.164 format e.g., '+15105555555'. You must include this to have your POST succeed.
Optional Parameters

The optional parameters for this request are exactly the same as POSTing directly to the IncomingPhoneNumbers/ resource.

If successful, Twilio responds with a representation of the new phone number that was assigned to your account.

NOTE: You cannot request numbers while you are using a Free Trial account. You must upgrade your account to purchase a Twilio phone number.

HTTP PUT

Not Supported.

HTTP DELETE

Not Supported.

Toll-Free IncomingPhoneNumber Factory Resource

This subresource represents only toll-free phone numbers. POSTing to this resource allows you to request a new toll-free phone number be added to your account.

Resource URI

/2010-04-01/Accounts/{YourAccountSid}/IncomingPhoneNumbers/TollFree

HTTP Methods

HTTP GET

Returns a list of local <IncomingPhoneNumber> elements, each representing a toll-free phone number given to your account, under an <IncomingPhoneNumbers> list element that includes paging information. Works exactly the same as the IncomingPhoneNumber resource, but filters out all numbers that aren't toll-free.

HTTP POST

Adds a new phone number to your account. If a phone number is found for your request, Twilio will add it to your account and bill you for the first month's cost of the phone number. If Twilio can't find a phone number to match your request, you will receive an HTTP 400 with Twilio error code 21452.

To find an available phone number to POST, use the subresources of the AvailablePhoneNumbers list resource.

Required Parameters

Your request must include PhoneNumber. We do not support AreaCode for this subresource:

Parameter Description
PhoneNumber The phone number you want to purchase. The number should be formatted starting with a '+' followed by the country code and the number in E.164 format e.g., '+15105555555'. You must include this to have your POST succeed.
Optional Parameters

The optional parameters for this request are exactly the same as POSTing directly to the IncomingPhoneNumbers/ resource.

If successful, Twilio will respond with a representation of the new phone number that was assigned to your account.

NOTE: You can only request phone numbers with a full Twilio account, not in the Twilio Free Trial. If you would like to buy a Twilio phone number, you must upgrade your account.

HTTP PUT

Not Supported.

HTTP DELETE

Not Supported.

Mobile IncomingPhoneNumber Factory Resource

POSTing to this resource allows you to request a new mobile phone number be added to your account. This subresource represents only mobile phone numbers, i.e. not toll free numbers or local numbers.

Resource URI

/2010-04-01/Accounts/{YourAccountSid}/IncomingPhoneNumbers/Mobile

HTTP Methods

HTTP GET

Returns a list of local <IncomingPhoneNumber> elements, each representing a mobile phone number given to your account, under an <IncomingPhoneNumbers> list element that includes paging information. Works exactly the same as the IncomingPhoneNumber resource, but filters out local and toll free numbers.

HTTP POST

Adds a new phone number to your account. If a phone number is found for your request, Twilio will add it to your account and bill you for the first month's cost of the phone number. If Twilio can't find a phone number to match your request, you will receive an HTTP 400 with Twilio error code 21452.

To find an available phone number to POST, use the subresources of the AvailablePhoneNumbers list resource.

Required Parameters

Your request must include PhoneNumber. We do not support AreaCode for this subresource:

Parameter Description
PhoneNumber The phone number you want to purchase. The number should be formatted starting with a '+' followed by the country code and the number in E.164 format e.g., '+15105555555'. You must include this to have your POST succeed.
Optional Parameters

The optional parameters for this request are exactly the same as POSTing directly to the IncomingPhoneNumbers/ resource.

If successful, Twilio will respond with a representation of the new phone number that was assigned to your account.

NOTE: You cannot request numbers while you are using a Free Trial account. You must upgrade your account to purchase a Twilio phone number.

HTTP PUT

Not Supported.

HTTP DELETE

Not Supported.