Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

REST API: Available Phone Numbers

The subresources of the AvailablePhoneNumbers resource let you search for local, toll-free and mobile phone numbers that are available for you to purchase. You can search for phone numbers that match a pattern, are in a certain country, are in certain area code (NPA) or exchange (NXX) or are in a specific geography.

Once you've found an available number you want to purchase, make an HTTP POST request to the IncomingPhoneNumbers list resource passing the number as the 'PhoneNumber' parameter.

We work hard to keep a wide variety of numbers in stock at all times. See our pricing pages for country availability.

AvailablePhoneNumber Local Instance Resource

Resource URI

An AvailablePhoneNumber Local instance resource has no URI. You cannot make requests directly to AvailablePhoneNumber instance resources. Instead, make a request to the local list subresource and then choose a number from the list.

Resource Properties

The following properties are available for all available phone number resources:

address_requirements
string Not PII

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
boolean Not PII

Phone numbers new to the Twilio platform are marked as beta. Possible values are either true or false.

capabilities
phone_number_capabilities Not PII

This is a set of boolean properties that indicate whether a phone number can receive calls or messages. Possible capabilities are Voice, SMS, MMS, and Fax with each having a value of either true or false.

friendly_name
phone_number Not PII

A nicely-formatted version of the phone number.

iso_country
iso_country_code Not PII

The ISO country code of this phone number.

lata
string Not PII

The LATA of this phone number. Available for phone numbers from the US and Canada.

latitude
decimal Not PII

The latitude coordinate of this phone number. Available for phone numbers from the US and Canada.

locality
string Not PII

The locality/city of this phone number.

longitude
decimal Not PII

The longitude coordinate of this phone number. Available for phone numbers from the US and Canada.

phone_number
phone_number Not PII

The phone number, in E.164 (i.e. "+1") format.

postal_code
string Not PII

The postal (zip) code of this phone number. Available for phone numbers from the US and Canada.

rate_center
string Not PII

The rate center of this phone number. Available for phone numbers from the US and Canada.

region
string Not PII

The two-letter state or province abbreviation of this phone number. Available for phone numbers from the US and Canada.

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.

AvailablePhoneNumber Toll-Free Instance Resource

You can purchase toll-free numbers from the US, Canada, and the UK.

Resource URI

An AvailablePhoneNumber Toll-Free instance resource has no URI. You cannot make requests directly to AvailablePhoneNumber instance resources. Instead, make a request to the toll-free list subresource and then choose a number from the list.

Resource Properties

address_requirements
string Not PII

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
boolean Not PII

Phone numbers new to the Twilio platform are marked as beta. Possible values are either true or false.

capabilities
phone_number_capabilities Not PII

This is a set of boolean properties that indicate whether a phone number can receive calls or messages. Possible capabilities are Voice, SMS, MMS, and Fax with each having a value of either true or false.

friendly_name
phone_number Not PII

A nicely-formatted version of the phone number.

iso_country
iso_country_code Not PII

The ISO country code of this phone number.

lata
string Not PII

The LATA of this phone number. Available for phone numbers from the US and Canada.

latitude
decimal Not PII

The latitude coordinate of this phone number. Available for phone numbers from the US and Canada.

locality
string Not PII

The locality/city of this phone number.

longitude
decimal Not PII

The longitude coordinate of this phone number. Available for phone numbers from the US and Canada.

phone_number
phone_number Not PII

The phone number, in E.164 (i.e. "+1") format.

postal_code
string Not PII

The postal (zip) code of this phone number. Available for phone numbers from the US and Canada.

rate_center
string Not PII

The rate center of this phone number. Available for phone numbers from the US and Canada.

region
string Not PII

The two-letter state or province abbreviation of this phone number. Available for phone numbers from the US and Canada.


AvailablePhoneNumber Mobile Instance Resource

Resource URI

An AvailablePhoneNumber mobile instance resource has no URI. You cannot make requests directly to AvailablePhoneNumber instance resources. Instead, make a request to the mobile list subresource and then choose a number from the list.

Resource Properties

address_requirements
string Not PII

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
boolean Not PII

Phone numbers new to the Twilio platform are marked as beta. Possible values are either true or false.

capabilities
phone_number_capabilities Not PII

This is a set of boolean properties that indicate whether a phone number can receive calls or messages. Possible capabilities are Voice, SMS, MMS, and Fax with each having a value of either true or false.

friendly_name
phone_number Not PII

A nicely-formatted version of the phone number.

iso_country
iso_country_code Not PII

The ISO country code of this phone number.

lata
string Not PII

The LATA of this phone number. Available for phone numbers from the US and Canada.

latitude
decimal Not PII

The latitude coordinate of this phone number. Available for phone numbers from the US and Canada.

locality
string Not PII

The locality/city of this phone number.

longitude
decimal Not PII

The longitude coordinate of this phone number. Available for phone numbers from the US and Canada.

phone_number
phone_number Not PII

The phone number, in E.164 (i.e. "+1") format.

postal_code
string Not PII

The postal (zip) code of this phone number. Available for phone numbers from the US and Canada.

rate_center
string Not PII

The rate center of this phone number. Available for phone numbers from the US and Canada.

region
string Not PII

The two-letter state or province abbreviation of this phone number. Available for phone numbers from the US and Canada.

Search and Buy Phone Numbers

Buy combining the AvailablePhoneNumbers lookup (examples below) with an IncomingPhoneNumbers purchase you can purchase any number based on a wide set of criteria. You can search for available numbers that match a specific pattern, are in a specific geographic area,or are near other numbers just to name a few. Once you've found a number you'd like to buy you simply POST the number to the IncomingPhoneNumbers resource.

AvailablePhoneNumbers Local List Subresource

Resource URI

/2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/{IsoCountryCode}/Local

{IsoCountryCode} is a country code in ISO 3166-1 alpha-2 format. For example, the IsoCountryCode for Canada is CA. See Supported Countries for a full list of countries and IsoCountryCodes supported by Twilio.

HTTP GET

Returns a list of local AvailablePhoneNumber resource representations that match the specified filters, each representing a phone number that is currently available for provisioning within your account.

Basic List Filters

The following basic GET query string parameters allow you to filter the list of numbers returned by Twilio. Note, parameters are case-sensitive.

AreaCode
Optional
get integer Not PII

Find phone numbers in the specified area code. (US and Canada only)

Beta
Optional
get boolean Not PII

Include phone numbers new to the Twilio platform. Possible values are either true or false. Default is true.

Contains
Optional
get string Not PII

A pattern on which to match phone numbers. Valid characters are '*' and [0-9a-zA-Z]. The '*' character will match any single digit. See Example 2 and Example 3 below. NOTE: Patterns must be at least two characters long.

Distance
Optional
get integer Not PII

Specifies the search radius for a Near- query in miles. If not specified this defaults to 25 miles. Maximum searchable distance is 500 miles. Limited to US and Canadian phone numbers.

ExcludeAllAddressRequired
Optional
get boolean Not PII

Indicates whether the response includes phone numbers which require any Address. Possible values are true or false. If not specified, the default is false, and results could include phone numbers with an Address required.

ExcludeForeignAddressRequired
Optional
get boolean Not PII

Indicates whether the response includes phone numbers which require a foreign Address. Possible values are true or false. If not specified, the default is false, and results could include phone numbers with a foreign Address required.

ExcludeLocalAddressRequired
Optional
get boolean Not PII

Indicates whether the response includes phone numbers which require a local Address. Possible values are true or false. If not specified, the default is false, and results could include phone numbers with a local Address required.

FaxEnabled
Optional
get boolean Not PII

This indicates whether the phone numbers can receive faxes. Possible values are true or false.

InLata
Optional
get string Not PII

Limit results to a specific Local access and transport area (LATA). Given a phone number, search within the same LATA as that number. Limited to US and Canadian phone numbers.

InLocality
Optional
get string Not PII

Limit results to a particular locality (i.e. City). Given a phone number, search within the same Locality as that number. Limited to US and Canadian phone numbers.

InPostalCode
Optional
get string Not PII

Limit results to a particular postal code. Given a phone number, search within the same postal code as that number. Limited to US and Canadian phone numbers.

InRateCenter
Optional
get string Not PII

Limit results to a specific rate center, or given a phone number search within the same rate center as that number. Requires InLata to be set as well. Limited to US and Canadian phone numbers.

InRegion
Optional
get string Not PII

Limit results to a particular region (i.e. State/Province). Given a phone number, search within the same Region as that number. Limited to US and Canadian phone numbers.

MmsEnabled
Optional
get boolean Not PII

This indicates whether the phone numbers can receive MMS messages. Possible values are true or false.

NearLatLong
Optional
get string Not PII

Given a latitude/longitude pair lat,long find geographically close numbers within Distance miles. Limited to US and Canadian phone numbers.

NearNumber
Optional
get phone_number<e164> Not PII

Given a phone number, find a geographically close number within Distance miles. Distance defaults to 25 miles. Limited to US and Canadian phone numbers.

SmsEnabled
Optional
get boolean Not PII

This indicates whether the phone numbers can receive text messages. Possible values are true or false.

VoiceEnabled
Optional
get boolean Not PII

This indicates whether the phone numbers can receive calls. Possible values are true or false.

Find available local phone numbers

Find available local phone numbers in the United States in the 510 area code.

Loading Code Sample...
      
      
      
      

      Find phone numbers by number pattern

      Find local phone numbers in the United States starting with 510555.

      Loading Code Sample...
          
          
          
          

          Find phone numbers by pattern

          Find local phone numbers that match the pattern 'STORM'.

          Loading Code Sample...
              
              
              
              

              Find available phone numbers by state

              Find available phone numbers in Arkansas.

              Loading Code Sample...
                  
                  
                  
                  

                  Find available local phone numbers

                  Find a phone number in the London prefix (+4420) which is SMS-enabled.

                  Loading Code Sample...
                      
                      
                      
                      

                      Find regional phone numbers by feature

                      Find a phone number in the UK which is Voice- and SMS-enabled.

                      Loading Code Sample...
                          
                          
                          
                          
                          Loading Code Sample...
                              
                              
                              
                              
                              Loading Code Sample...
                                  
                                  
                                  
                                  

                                  Advanced List Filter Example

                                  These features are limited to US and Canadian phone numbers. Find local phone numbers within 50 miles of San Francisco, CA (37.840699,-122.461853) that contain the digits '555'.

                                  Loading Code Sample...
                                      
                                      
                                      
                                      

                                      HTTP POST

                                      Not Supported.

                                      HTTP PUT

                                      Not Supported.

                                      HTTP DELETE

                                      Not Supported.

                                      AvailablePhoneNumbers Toll-Free List Subresource

                                      Resource URI

                                      /2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/{IsoCountryCode}/TollFree
                                      

                                      Note that {IsoCountryCode} is a country code in ISO 3166-1 alpha-2 format ('US' for United States, 'CA' for Canada, 'GB' for United Kingdom).

                                      HTTP GET

                                      Returns a list of toll-free AvailablePhoneNumber elements that match the specified filters, each representing a phone number that is currently available for provisioning within your account. To provision an available phone number, POST the number to the IncomingPhoneNumbers resource.

                                      List Filters

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

                                      AreaCode
                                      Optional
                                      get integer Not PII

                                      Find phone numbers in the specified area code. (US and Canada only)

                                      Beta
                                      Optional
                                      get boolean Not PII

                                      Include phone numbers new to the Twilio platform. Possible values are either true or false. Default is true.

                                      Contains
                                      Optional
                                      get string Not PII

                                      A pattern on which to match phone numbers. Valid characters are '*' and [0-9a-zA-Z]. The '*' character will match any single digit. See Example 2 and Example 3 below. NOTE: Patterns must be at least two characters long.

                                      Distance
                                      Optional
                                      get integer Not PII

                                      Specifies the search radius for a Near- query in miles. If not specified this defaults to 25 miles. Maximum searchable distance is 500 miles. Limited to US and Canadian phone numbers.

                                      ExcludeAllAddressRequired
                                      Optional
                                      get boolean Not PII

                                      Indicates whether the response includes phone numbers which require any Address. Possible values are true or false. If not specified, the default is false, and results could include phone numbers with an Address required.

                                      ExcludeForeignAddressRequired
                                      Optional
                                      get boolean Not PII

                                      Indicates whether the response includes phone numbers which require a foreign Address. Possible values are true or false. If not specified, the default is false, and results could include phone numbers with a foreign Address required.

                                      ExcludeLocalAddressRequired
                                      Optional
                                      get boolean Not PII

                                      Indicates whether the response includes phone numbers which require a local Address. Possible values are true or false. If not specified, the default is false, and results could include phone numbers with a local Address required.

                                      FaxEnabled
                                      Optional
                                      get boolean Not PII

                                      This indicates whether the phone numbers can receive faxes. Possible values are true or false.

                                      InLata
                                      Optional
                                      get string Not PII

                                      Limit results to a specific Local access and transport area (LATA). Given a phone number, search within the same LATA as that number. Limited to US and Canadian phone numbers.

                                      InLocality
                                      Optional
                                      get string Not PII

                                      Limit results to a particular locality (i.e. City). Given a phone number, search within the same Locality as that number.

                                      InPostalCode
                                      Optional
                                      get string Not PII

                                      Limit results to a particular postal code. Given a phone number, search within the same postal code as that number. Limited to US and Canadian phone numbers.

                                      InRateCenter
                                      Optional
                                      get string Not PII

                                      Limit results to a specific rate center, or given a phone number search within the same rate center as that number. Requires InLata to be set as well. Limited to US and Canadian phone numbers.

                                      InRegion
                                      Optional
                                      get string Not PII

                                      Limit results to a particular region (i.e. State/Province). Given a phone number, search within the same Region as that number. Limited to US and Canadian phone numbers.

                                      MmsEnabled
                                      Optional
                                      get boolean Not PII

                                      This indicates whether the phone numbers can receive MMS messages. Possible values are true or false.

                                      NearLatLong
                                      Optional
                                      get string Not PII

                                      Given a latitude/longitude pair lat,long find geographically close numbers within Distance miles. Limited to US and Canadian phone numbers.

                                      NearNumber
                                      Optional
                                      get phone_number<e164> Not PII

                                      Given a phone number, find a geographically close number within Distance miles. Distance defaults to 25 miles. Limited to US and Canadian phone numbers.

                                      SmsEnabled
                                      Optional
                                      get boolean Not PII

                                      This indicates whether the phone numbers can receive text messages. Possible values are true or false.

                                      VoiceEnabled
                                      Optional
                                      get boolean Not PII

                                      This indicates whether the phone numbers can receive calls. Possible values are true or false.

                                      Loading Code Sample...
                                          
                                          
                                          
                                          

                                          Find a toll-free number by string

                                          Let's find a phone number containing a specific string. Contains=866 will match toll-free phone numbers that contain 866, like 866-555-3455 or 888-866-0555. Contains=866***EPIC matches numbers starting with 866 followed by any three digits and then the numbers 3742 (EPIC). To find a toll-free phone number that matches the pattern 'STORM', we make the following request:

                                          Loading Code Sample...
                                              
                                              
                                              
                                              

                                              Find a toll-free number by pattern

                                              Find toll-free phone numbers in the 800 area code that contain the pattern 'KYLO'.

                                              Loading Code Sample...