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:

Names in PHP format
friendlyName
phone_number Not PII

A formatted version of the phone number.

phoneNumber
phone_number Not PII

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

lata
string Not PII

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

locality
string Not PII

The locality or city of this phone number's location.

rateCenter
string Not PII

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

latitude
decimal Not PII

The latitude of this phone number's location. Available for only phone numbers from the US and Canada.

longitude
decimal Not PII

The longitude of this phone number's location. Available for only phone numbers from the US and Canada.

region
string Not PII

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

postalCode
string Not PII

The postal or ZIP code of this phone number's location. Available for only phone numbers from the US and Canada.

isoCountry
iso_country_code Not PII

The ISO country code of this phone number.

addressRequirements
string Not PII

The type of Address resource the phone number requires. Can be: none, any, local, or foreign. none means no address is required. any means an address is required, but it can be anywhere in the world. local means an address in the phone number's country is required. foreign means an address outside of the phone number's country is required.

beta
boolean Not PII

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

capabilities
phone_number_capabilities 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.

Address Requirements Values

The following are the possible values for the address_requirements 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

Twilio has a range of available toll-free numbers across different countries that you can purchase.

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

Names in PHP format
friendlyName
phone_number Not PII

A formatted version of the phone number.

phoneNumber
phone_number Not PII

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

lata
string Not PII

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

locality
string Not PII

The locality or city of this phone number's location.

rateCenter
string Not PII

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

latitude
decimal Not PII

The latitude of this phone number's location. Available for only phone numbers from the US and Canada.

longitude
decimal Not PII

The longitude of this phone number's location. Available for only phone numbers from the US and Canada.

region
string Not PII

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

postalCode
string Not PII

The postal or ZIP code of this phone number's location. Available for only phone numbers from the US and Canada.

isoCountry
iso_country_code Not PII

The ISO country code of this phone number.

addressRequirements
string Not PII

The type of Address resource the phone number requires. Can be: none, any, local, or foreign. none means no address is required. any means an address is required, but it can be anywhere in the world. local means an address in the phone number's country is required. foreign means an address outside of the phone number's country is required.

beta
boolean Not PII

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

capabilities
phone_number_capabilities 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.


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

Names in PHP format
friendlyName
phone_number Not PII

A formatted version of the phone number.

phoneNumber
phone_number Not PII

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

lata
string Not PII

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

locality
string Not PII

The locality or city of this phone number's location.

rateCenter
string Not PII

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

latitude
decimal Not PII

The latitude of this phone number's location. Available for only phone numbers from the US and Canada.

longitude
decimal Not PII

The longitude of this phone number's location. Available for only phone numbers from the US and Canada.

region
string Not PII

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

postalCode
string Not PII

The postal or ZIP code of this phone number's location. Available for only phone numbers from the US and Canada.

isoCountry
iso_country_code Not PII

The ISO country code of this phone number.

addressRequirements
string Not PII

The type of Address resource the phone number requires. Can be: none, any, local, or foreign. none means no address is required. any means an address is required, but it can be anywhere in the world. local means an address in the phone number's country is required. foreign means an address outside of the phone number's country is required.

beta
boolean Not PII

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

capabilities
phone_number_capabilities 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.

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.

Names in PHP format
accountSid
Required
get sid<AC> Not PII

The SID of the Account requesting the AvailablePhoneNumber resources.

countryCode
Required
get iso_country_code Not PII

The ISO-3166-1 country code of the country from which to read phone numbers.

areaCode
Optional
get integer Not PII

The area code of the phone numbers to read. Applies to only phone numbers in the US and Canada.

contains
Optional
get string Not PII

The pattern on which to match phone numbers. Valid characters are *, 0-9, a-z, and A-Z. The * character matches any single digit. For examples, see Example 2 and Example 3. If specified, this value must have at least two characters.

smsEnabled
Optional
get boolean Not PII

Whether the phone numbers can receive text messages. Can be: true or false.

mmsEnabled
Optional
get boolean Not PII

Whether the phone numbers can receive MMS messages. Can be: true or false.

voiceEnabled
Optional
get boolean Not PII

Whether the phone numbers can receive calls. Can be: true or false.

excludeAllAddressRequired
Optional
get boolean Not PII

Whether to exclude phone numbers that require an Address. Can be: true or false and the default is false.

excludeLocalAddressRequired
Optional
get boolean Not PII

Whether to exclude phone numbers that require a local Address. Can be: true or false and the default is false.

excludeForeignAddressRequired
Optional
get boolean Not PII

Whether to exclude phone numbers that require a foreign Address. Can be: true or false and the default is false.

beta
Optional
get boolean Not PII

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

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. Applies to only phone numbers in the US and Canada.

nearLatLong
Optional
get string Not PII

Given a latitude/longitude pair lat,long find geographically close numbers within distance miles. Applies to only phone numbers in the US and Canada.

distance
Optional
get integer Not PII

The search radius, in miles, for a near_ query. Can be up to 500 and the default is 25. Applies to only phone numbers in the US and Canada.

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. Applies to only phone numbers in the US and Canada.

inRegion
Optional
get string Not PII

Limit results to a particular region, state, or province. Given a phone number, search within the same region as that number. Applies to only phone numbers in the US and Canada.

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 in_lata to be set as well. Applies to only phone numbers in the US and Canada.

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. Applies to only phone numbers in the US and Canada.

inLocality
Optional
get string Not PII

Limit results to a particular locality or city. Given a phone number, search within the same Locality as that number.

faxEnabled
Optional
get boolean Not PII

Whether the phone numbers can receive faxes. Can be: true or false.

Find available local phone numbers

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

        
        
        
        

        Find phone numbers by number pattern

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

              
              
              
              

              Find phone numbers by pattern

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

                    
                    
                    
                    

                    Find available phone numbers by state

                    Find available phone numbers in Arkansas.

                          
                          
                          
                          

                          Find available local phone numbers

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

                                
                                
                                
                                

                                Find regional phone numbers by feature

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

                                      
                                      
                                      
                                      
                                            
                                            
                                            
                                            
                                                  
                                                  
                                                  
                                                  

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

                                                        
                                                        
                                                        
                                                        

                                                        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:

                                                        Names in PHP format
                                                        accountSid
                                                        Required
                                                        get sid<AC> Not PII

                                                        The SID of the Account requesting the AvailablePhoneNumber resources.

                                                        countryCode
                                                        Required
                                                        get iso_country_code Not PII

                                                        The ISO-3166-1 country code of the country from which to read phone numbers.

                                                        areaCode
                                                        Optional
                                                        get integer Not PII

                                                        The area code of the phone numbers to read. Applies to only phone numbers in the US and Canada.

                                                        contains
                                                        Optional
                                                        get string Not PII

                                                        The pattern on which to match phone numbers. Valid characters are *, 0-9, a-z, and A-Z. The * character matches any single digit. For examples, see Example 2 and Example 3. If specified, this value must have at least two characters.

                                                        smsEnabled
                                                        Optional
                                                        get boolean Not PII

                                                        Whether the phone numbers can receive text messages. Can be: true or false.

                                                        mmsEnabled
                                                        Optional
                                                        get boolean Not PII

                                                        Whether the phone numbers can receive MMS messages. Can be: true or false.

                                                        voiceEnabled
                                                        Optional
                                                        get boolean Not PII

                                                        Whether the phone numbers can receive calls. Can be: true or false.

                                                        excludeAllAddressRequired
                                                        Optional
                                                        get boolean Not PII

                                                        Whether to exclude phone numbers that require an Address. Can be: true or false and the default is false.

                                                        excludeLocalAddressRequired
                                                        Optional
                                                        get boolean Not PII

                                                        Whether to exclude phone numbers that require a local Address. Can be: true or false and the default is false.

                                                        excludeForeignAddressRequired
                                                        Optional
                                                        get boolean Not PII

                                                        Whether to exclude phone numbers that require a foreign Address. Can be: true or false and the default is false.

                                                        beta
                                                        Optional
                                                        get boolean Not PII

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

                                                        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. Applies to only phone numbers in the US and Canada.

                                                        nearLatLong
                                                        Optional
                                                        get string Not PII

                                                        Given a latitude/longitude pair lat,long find geographically close numbers within distance miles. Applies to only phone numbers in the US and Canada.

                                                        distance
                                                        Optional
                                                        get integer Not PII

                                                        The search radius, in miles, for a near_ query. Can be up to 500 and the default is 25. Applies to only phone numbers in the US and Canada.

                                                        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. Applies to only phone numbers in the US and Canada.

                                                        inRegion
                                                        Optional
                                                        get string Not PII

                                                        Limit results to a particular region, state, or province. Given a phone number, search within the same region as that number. Applies to only phone numbers in the US and Canada.

                                                        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 in_lata to be set as well. Applies to only phone numbers in the US and Canada.

                                                        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. Applies to only phone numbers in the US and Canada.

                                                        inLocality
                                                        Optional
                                                        get string Not PII

                                                        Limit results to a particular locality or city. Given a phone number, search within the same Locality as that number.

                                                        faxEnabled
                                                        Optional
                                                        get boolean Not PII

                                                        Whether the phone numbers can receive faxes. Can be: true or false.

                                                              
                                                              
                                                              
                                                              

                                                              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: