Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

REST API: Available Numbers


(warning)

Warning

Available Numbers API is currently in closed private Developer Preview. Please use the generally available Available Phone Numbers API if you do not have access.

The Available Numbers endpoint provides a rich view into Twilio's inventory of phone numbers available for purchase. As we've worked with operators across the globe to offer numbers that cover over 100 countries, we've learned that not all numbers are created equal. Phone numbers differ broadly in characteristics and regulatory requirements. Through the /AvailableNumbers endpoint, every number is described by a set of attributes, grouped in four categories: capabilities (voice, sms, mms), geography, regulatory requirements, and pricing. With granular search filters to select numbers with the right attributes for your application, you can narrow down search results to find the perfect number for your use case.

For number pricing and availability please refer to the Support Number Catalog(link takes you to an external page).

To keep things simple, we're introducing the ability to search for numbers based on what you're building - simply pass your use case as a search parameter and we'll return numbers that have the right characteristics for your application. Once you've found an available number you want to purchase, make an HTTP POST request to the /ActiveNumbers list resource passing the number as the PhoneNumber parameter.


AvailableNumbers Instance Resource

available-numbers-instance page anchor

Resource URI

available-instance-uri page anchor

You can make a request directly to AvailableNumbers instance resource and choose from any of the numbers that appear in the search as a result of the filters you've specified.


_10
https://preview.twilio.com/AvailableNumbers

Basic Capability Properties

basic-capability-properties page anchor

The table below states basic properties of the phone number that associate the number to a unique group within Twilio's inventory system.

PropertyDescription
PhoneNumberThe phone number, in E.164(link takes you to an external page) (i.e. "+1") format.
TypeThe type of phone number (i.e., local, mobile, tollfree, shortcode, etc.).
LifecycleThe lifecycle the number is in (i.e., developer-preview, beta, generally-available, exhausted).
BaseRecurringPriceBase recurring price for a number. (i.e., $1.00). This price will be recurring until the number is released. Please note this does not take into account PricingModels.
BaseSetupPriceBase setup price for a number. (i.e., $1.00). This price is charged to your account one time when the number is first purchased.

Voice Capability Properties

voice-capability-properties page anchor

Voice calling is provided by utilizing the Public Switch Telephone Network (PSTN)(link takes you to an external page), the aggregate of the world's circuit-switched telephone networks that are operated by national, regional, or local telephony operators, providing infrastructure and services for public telecommunication.

PropertyDescription
Capabilities.Voice.InboundConnectivityIndicates whether a number has inbound voice connectivity in to Twilio.
Capabilities.Voice.OutboundConnectivityIndicates whether a number has outbound voice connectivity out of Twilio.
Capabilities.Voice.E911[Emergency 911][e911] connectivity capable number.
Capabilities.Voice.Fax[Fax][fax] capable number.
Capabilities.Voice.SipTrunkingSip Trunking(link takes you to an external page) capable number.
Capabilities.Voice.CallsPerSecondInteger stating how many calls can be initiated per second. Please refer to Twilio's CPS Support article(link takes you to an external page) for more information.
Capabilities.Voice.ConcurrentCallsLimitInteger stating how many calls can be active at one time.
Capabilities.Voice.InboundCalledDtmfDual-Tone Multi Frequency(link takes you to an external page) with inbound called party.
Capabilities.Voice.InboundCallerDtmfDual-Tone Multi Frequency(link takes you to an external page) with inbound caller party.
Capabilities.Voice.InboundCallerIdPreservationInbound voice Caller ID (+E.164 format)(link takes you to an external page) preservation of a number. Can be - International, Domestic, or None.
Capabilities.Voice.InboundReachabilityInbound Voice reachability of a number. Can be - Domestic, Foreign, or Global.
Capabilities.Voice.LongRecordLengthThe length in seconds that a number can record a voicemail.

Sms Capability Properties

sms-capability-properties page anchor

Short Messaging Service (SMS)(link takes you to an external page) is a text messaging service component of most telephone, World Wide Web, and mobile telephony systems.

PropertyDescription
Capabilities.Sms.InboundConnectivityIndicates whether a number has inbound sms connectivity in to Twilio.
Capabilities.Sms.OutboundConnectivityIndicates whether a number has outbound sms connectivity out of Twilio.
Capabilities.Sms.Gsm7GSM-7 is a character encoding standard which packs the most commonly used letters and symbols in many languages into 7 bits each for usage on GSM networks. See What is GSM-7 Character Encoding(link takes you to an external page).
Capabilities.Sms.Ucs2UCS-2 is a character encoding standard in which characters are represented by a fixed-length 16 bits (2 bytes). See What is UCS-2 Character Encoding?(link takes you to an external page).
Capabilities.Sms.Gsm7ConcatenationConcatenated short message service (or concatenated SMS)(link takes you to an external page) is used overcome the limitation on the number of characters that can be sent in a single SMS text message transmission (which is usually 160), and split the sms into smaller messages by the sending device and recombined at the receiving end.
Capabilities.Sms.Ucs2ConcatenationConcatenated short message service (or concatenated SMS)(link takes you to an external page) is used overcome the limitation on the number of characters that can be sent in a single SMS text message transmission (which is usually 160), and split the sms into smaller messages by the sending device and recombined at the receiving end.
Capabilities.Sms.InboundSenderIdPreservationInbound voice Sender ID (+E.164 format)(link takes you to an external page) preservation of a number. Can be - International, Domestic, or None.
Capabilities.Sms.InboundReachabilityInbound SMS reachability of a number. Can be - Domestic, Foreign, or Global.
Capabilities.Sms.InboundMpsInteger showing the SMS inbound message per second limit. Please refer to Twilio's MPS Support article(link takes you to an external page) for more information.

Mms Capability Properties

mms-capability-properties page anchor

Multimedia Messaging Service (MMS)(link takes you to an external page) is a standard way to send messages that include multimedia content to and from a mobile phone over a cellular network.

PropertyDescription
Capabilities.Mms.InboundconnectivityIndicates whether a number has inbound MMS connectivity into Twilio.
Capabilities.Mms.OutboundconnectivityIndicates whether a number has outbound MMS connectivity into Twilio.
Capabilities.Mms.InboundReachabilityInbound MMS reachability of a number. Can be - Domestic, Foreign, or Global.
Capabilities.Mms.InboundMpsInteger showing the MMS inbound message per second limit. Please refer to Twilio's MPS Support article(link takes you to an external page) for more information.

Regulations that pertain to this specific number that may deal with Addresses and/or Identities to be required and completed as a pre-request before purchasing.

PropertyDescription
Regulatory.AddressRequirementsThis indicates whether the phone number requires you or your customer to have an Address(link takes you to an external page) registered with Twilio. Possible values are listed below.

Address Requirement Values

address-requirement-values page anchor

The following are the possible values for the address_required property.

StatusDescription
noneAn Address(link takes you to an external page) is not required for this phone number.
anyYour account must have an Address(link takes you to an external page), but it can be anywhere in the world.
localYour account must have an Address(link takes you to an external page) within the phone number's country.
foreignYour account must have an Address(link takes you to an external page) outside the phone number's country.

A phone number's specific geography associated with a number. Some numbers are country level only, and others have specific latitude and longitude associated with them. To understand more, please visit List of Country Codes(link takes you to an external page).

PropertyDescription
Geography.IsoCountryThe ISO country code(link takes you to an external page) of this phone number.
Geography.LataThe LATA(link takes you to an external page) of this phone number. Only available for countries in the North American Numbering Plan (NANPA)(link takes you to an external page).
Geography.RateCenterThe rate center(link takes you to an external page) of this phone number. Only available for countries in the North American Numbering Plan (NANPA)(link takes you to an external page).
Geography.LatitudeThe latitude coordinate of this phone number.
Geography.LongitudeThe longitude coordinate of this phone number.
Geography.RegionThe two-letter state or province abbreviation of this phone number.
Geography.LocalityThe locality/city of this phone number.
Geography.PostalCodeThe postal (zip) code of this phone number.

Search for Toll Free US numbers

search-for-toll-free-us-numbers page anchor
curl

_10
$ curl -G https://preview.twilio.com/Numbers/AvailableNumbers \
_10
-d "Type=tollfree" \
_10
-d "Geography.IsoCountry=US" \
_10
-u '<ACCOUNT_SID:AUTH_TOKEN>'

Output

_66
{
_66
"items": [
_66
{
_66
"phone_number": "+18005559306",
_66
"base_setup_price": "0.0",
_66
"base_recurring_price": "2.0",
_66
"capabilities": {
_66
"voice": {
_66
"inbound_connectivity": true,
_66
"outbound_connectivity": true,
_66
"e911": true,
_66
"fax": true,
_66
"sip_trunking": true,
_66
"calls_per_second": 1,
_66
"concurrent_calls_limit": 1,
_66
"long_record_length": 30,
_66
"inbound_called_dtmf": true,
_66
"inbound_caller_dtmf": true,
_66
"inbound_caller_id_preservation": "international",
_66
"inbound_reachability": "global"
_66
},
_66
"sms": {
_66
"inbound_connectivity": true,
_66
"outbound_connectivity": true,
_66
"gsm7": true,
_66
"ucs2": true,
_66
"gsm7_concatenation": true,
_66
"ucs2_concatenation": true,
_66
"inbound_sender_id_preservation": "international",
_66
"inbound_reachability": "global",
_66
"inbound_mps": -1
_66
},
_66
"mms": {
_66
"inbound_connectivity": true,
_66
"outbound_connectivity": true,
_66
"inbound_reachability": "global",
_66
"inbound_mps": -1
_66
}
_66
},
_66
"regulatory": {
_66
"address_requirements": "none"
_66
},
_66
"type": "tollfree",
_66
"lifecycle": "generally-available",
_66
"geography": {
_66
"iso_country": "US",
_66
"lata": null,
_66
"rate_center": null,
_66
"latitude": null,
_66
"longitude": null,
_66
"region": null,
_66
"locality": null,
_66
"postal_code": null
_66
}
_66
}
_66
],
_66
"meta": {
_66
"page": 0,
_66
"page_size": 50,
_66
"first_page_url": "https://preview.twilio.com/Numbers/AvailableNumbers?Type=tollfree&PageSize=50&Page=0",
_66
"previous_page_url": null,
_66
"url": "https://preview.twilio.com/Numbers/AvailableNumbers?Type=tollfree&PageSize=50&Page=0",
_66
"next_page_url": null,
_66
"key": "items"
_66
}
_66
}

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

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

ParameterDescription
SavedSearchFind phone numbers that can support a specific Twilio use case, or a custom saved search that you've constructed. See below for a list of pre-defined use case saved searches. Ability to create and save custom searches is forthcoming.
MinBaseRecurringPriceMinimum base recurring price for a number. (i.e., >= $1.00). Combined with Maximum, this filter acts as a BETWEEN filter.
MaxBaseRecurringPriceMaximum base recurring price for a number. (i.e., <= $2.00). Combined with Minimum, this filter acts as a BETWEEN filter.
MinBaseSetupPriceMinimum base setup price for a number. (i.e., >= $1.00). Combined with Maximum, this filter acts as a BETWEEN filter.
MaxBaseSetupPriceMaximum base setup price for a number. (i.e., <= $2.00). Combined with Minimum, this filter acts as a BETWEEN filter.
curl

_10
$ curl -G https://preview.twilio.com/Numbers/AvailableNumbers \
_10
-d "SavedSearch=twilio.use-case.conversations.voice" \
_10
-d "SavedSearch=twilio.use-case.conversations.sms" \
_10
-d "Geography.IsoCountry=US" \
_10
-u '<ACCOUNT_SID:AUTH_TOKEN>'

Output

_66
{
_66
"items": [
_66
{
_66
"phone_number": "+14155558143",
_66
"base_setup_price": "0.0",
_66
"base_recurring_price": "2.0",
_66
"capabilities": {
_66
"voice": {
_66
"inbound_connectivity": true,
_66
"outbound_connectivity": true,
_66
"e911": true,
_66
"fax": true,
_66
"sip_trunking": true,
_66
"calls_per_second": 1,
_66
"concurrent_calls_limit": 1,
_66
"long_record_length": 30,
_66
"inbound_called_dtmf": true,
_66
"inbound_caller_dtmf": true,
_66
"inbound_caller_id_preservation": "international",
_66
"inbound_reachability": "global"
_66
},
_66
"sms": {
_66
"inbound_connectivity": true,
_66
"outbound_connectivity": true,
_66
"gsm7": true,
_66
"ucs2": true,
_66
"gsm7_concatenation": true,
_66
"ucs2_concatenation": true,
_66
"inbound_sender_id_preservation": "international",
_66
"inbound_reachability": "global",
_66
"inbound_mps": -1
_66
},
_66
"mms": {
_66
"inbound_connectivity": true,
_66
"outbound_connectivity": true,
_66
"inbound_reachability": "global",
_66
"inbound_mps": -1
_66
}
_66
},
_66
"regulatory": {
_66
"address_requirements": "none"
_66
},
_66
"type": "tollfree",
_66
"lifecycle": "generally-available",
_66
"geography": {
_66
"iso_country": "US",
_66
"lata": null,
_66
"rate_center": null,
_66
"latitude": null,
_66
"longitude": null,
_66
"region": null,
_66
"locality": null,
_66
"postal_code": null
_66
}
_66
}
_66
],
_66
"meta": {
_66
"page": 0,
_66
"page_size": 50,
_66
"first_page_url": "https://preview.twilio.com/Numbers/AvailableNumbers?Type=tollfree&PageSize=50&Page=0",
_66
"previous_page_url": null,
_66
"url": "https://preview.twilio.com/Numbers/AvailableNumbers?Type=tollfree&PageSize=50&Page=0",
_66
"next_page_url": null,
_66
"key": "items"
_66
}
_66
}

Saved Search allows you to search for numbers that meet your application's or project's specific criteria. Twilio has pre-defined 7 distinct use case saved search macros for you. The capability (Voice or Sms) must be included, and to have both voice and sms, you can specify multiple Saved Search filters. To see the exact filters being used for the 7 default use case saved search macros, please refer to the Global Phone Numbers Catalog FAQ(link takes you to an external page).

SavedSearchDescription
twilio.use-case.conversations.(capability)The Conversations use case allows numbers to setup multi-tenant conversations, and is available for both Voice and Sms. Please refer to Proxy(link takes you to an external page) for more information.
twilio.use-case.marketing.(capability)The marketing use case ensures you purchase numbers that are designated for marketing traffic by local telecom regulators. The marketing saved search is available for both Voice and Sms. Please refer to Twilio's Marketing site(link takes you to an external page) for more information.
twilio.use-case.notifications.(capability)The Notifications use case allows numbers to be used to notification purposes, and is available for both Voice and Sms. Please refer to Twilio's Account Notifications site(link takes you to an external page) for more information.
twilio.use-case.verifications.(capability)The Verifications use case allows numbers to be used for security verification purposes, and is available for both Voice and Sms. Please refer to Twilio's Verification site(link takes you to an external page) for more information.
twilio.use-case.pbx-collaborations.VoiceThe PBX Collaborations(link takes you to an external page) use case allows numbers to be used for your private branch exchange network, and is available for Voice only. Please refer to Twilio's Elastic SIP Trunking site(link takes you to an external page) for more information.
twilio.use-case.contact-centers.(capability)The Contact Centers use case allows numbers to be used for information and communication exchange between the contact center and end users. The Contact Centers is available for both Voice and Sms. Please refer to Twilio's Contact Center site(link takes you to an external page) for more information.
twilio.use-case.call-tracking.(capability)The Call Tracking use case allows you to take control over how you track and route calls and texts from any traffic source. The Call Tracking use case is available for Voice only. Please refer to Twilio's Call Tracking site(link takes you to an external page) for more information.

Search for US 2-way Voice numbers

search-for-us-2-way-voice-numbers page anchor
curl

_10
$ curl -G https://preview.twilio.com/Numbers/AvailableNumbers \
_10
-d "Geography.IsoCountry=US" \
_10
-d "Capabilities.Voice.InboundConnectivity=true" \
_10
-d "Capabilities.Voice.OutboundConnectivity=true" \
_10
-d "Capabilities.Voice.InboundCallerIdPreservation=international" \
_10
-u '<ACCOUNT_SID:AUTH_TOKEN>'

Output

_66
{
_66
"items": [
_66
{
_66
"phone_number": "+18005559306",
_66
"base_setup_price": "0.0",
_66
"base_recurring_price": "2.0",
_66
"capabilities": {
_66
"voice": {
_66
"inbound_connectivity": true,
_66
"outbound_connectivity": true,
_66
"e911": true,
_66
"fax": true,
_66
"sip_trunking": true,
_66
"calls_per_second": 1,
_66
"concurrent_calls_limit": 1,
_66
"long_record_length": 30,
_66
"inbound_called_dtmf": true,
_66
"inbound_caller_dtmf": true,
_66
"inbound_caller_id_preservation": "international",
_66
"inbound_reachability": "global"
_66
},
_66
"sms": {
_66
"inbound_connectivity": true,
_66
"outbound_connectivity": true,
_66
"gsm7": true,
_66
"ucs2": true,
_66
"gsm7_concatenation": true,
_66
"ucs2_concatenation": true,
_66
"inbound_sender_id_preservation": "international",
_66
"inbound_reachability": "global",
_66
"inbound_mps": -1
_66
},
_66
"mms": {
_66
"inbound_connectivity": true,
_66
"outbound_connectivity": true,
_66
"inbound_reachability": "global",
_66
"inbound_mps": -1
_66
}
_66
},
_66
"regulatory": {
_66
"address_requirements": "none"
_66
},
_66
"type": "tollfree",
_66
"lifecycle": "generally-available",
_66
"geography": {
_66
"iso_country": "US",
_66
"lata": null,
_66
"rate_center": null,
_66
"latitude": null,
_66
"longitude": null,
_66
"region": null,
_66
"locality": null,
_66
"postal_code": null
_66
}
_66
}
_66
],
_66
"meta": {
_66
"page": 0,
_66
"page_size": 50,
_66
"first_page_url": "https://preview.twilio.com/Numbers/AvailableNumbers?PageSize=50&Page=0",
_66
"previous_page_url": null,
_66
"url": "https://preview.twilio.com/Numbers/AvailableNumbers?PageSize=50&Page=0",
_66
"next_page_url": null,
_66
"key": "items"
_66
}
_66
}

Search for US 2-way SMS numbers

search-for-us-2-way-sms-numbers page anchor
curl

_10
$ curl -G https://preview.twilio.com/Numbers/AvailableNumbers \
_10
-d "Geography.IsoCountry=US" \
_10
-d "Capabilities.Sms.InboundConnectivity=true" \
_10
-d "Capabilities.Sms.OutboundConnectivity=true" \
_10
-d "Capabilities.Sms.InboundSenderIdPreservation=international" \
_10
-u '<ACCOUNT_SID:AUTH_TOKEN>'

Output

_66
{
_66
"items": [
_66
{
_66
"phone_number": "+18005559306",
_66
"base_setup_price": "0.0",
_66
"base_recurring_price": "2.0",
_66
"capabilities": {
_66
"voice": {
_66
"inbound_connectivity": true,
_66
"outbound_connectivity": true,
_66
"e911": true,
_66
"fax": true,
_66
"sip_trunking": true,
_66
"calls_per_second": 1,
_66
"concurrent_calls_limit": 1,
_66
"long_record_length": 30,
_66
"inbound_called_dtmf": true,
_66
"inbound_caller_dtmf": true,
_66
"inbound_caller_id_preservation": "international",
_66
"inbound_reachability": "global"
_66
},
_66
"sms": {
_66
"inbound_connectivity": true,
_66
"outbound_connectivity": true,
_66
"gsm7": true,
_66
"ucs2": true,
_66
"gsm7_concatenation": true,
_66
"ucs2_concatenation": true,
_66
"inbound_sender_id_preservation": "international",
_66
"inbound_reachability": "global",
_66
"inbound_mps": -1
_66
},
_66
"mms": {
_66
"inbound_connectivity": true,
_66
"outbound_connectivity": true,
_66
"inbound_reachability": "global",
_66
"inbound_mps": -1
_66
}
_66
},
_66
"regulatory": {
_66
"address_requirements": "none"
_66
},
_66
"type": "tollfree",
_66
"lifecycle": "generally-available",
_66
"geography": {
_66
"iso_country": "US",
_66
"lata": null,
_66
"rate_center": null,
_66
"latitude": null,
_66
"longitude": null,
_66
"region": null,
_66
"locality": null,
_66
"postal_code": null
_66
}
_66
}
_66
],
_66
"meta": {
_66
"page": 0,
_66
"page_size": 50,
_66
"first_page_url": "https://preview.twilio.com/Numbers/AvailableNumbers?PageSize=50&Page=0",
_66
"previous_page_url": null,
_66
"url": "https://preview.twilio.com/Numbers/AvailableNumbers?PageSize=50&Page=0",
_66
"next_page_url": null,
_66
"key": "items"
_66
}
_66
}

curl

_10
$ curl -G https://preview.twilio.com/Numbers/AvailableNumbers \
_10
-d "Type=local" \
_10
-d "Capabilities.Mms.OutboundConnectivity=true" \
_10
-d "Capabilities.Mms.InboundReachability=global" \
_10
-u '<ACCOUNT_SID:AUTH_TOKEN>'

Output

_67
{
_67
"items": [
_67
{
_67
"phone_number": "+16315550000",
_67
"capabilities": {
_67
"voice": {
_67
"inbound_connectivity": true,
_67
"outbound_connectivity": true,
_67
"e911": true,
_67
"fax": true,
_67
"sip_trunking": true,
_67
"calls_per_second": 30,
_67
"concurrent_calls_limit": 30,
_67
"long_record_length": 30,
_67
"inbound_called_dtmf": true,
_67
"inbound_caller_dtmf": true,
_67
"inbound_caller_id_preservation": "international",
_67
"inbound_reachability": "global",
_67
"codecs": [
_67
"g711u"
_67
]
_67
},
_67
"sms": {
_67
"inbound_connectivity": true,
_67
"outbound_connectivity": true,
_67
"gsm7": true,
_67
"ucs2": true,
_67
"gsm7_concatenation": true,
_67
"ucs2_concatenation": true,
_67
"inbound_sender_id_preservation": "international",
_67
"inbound_reachability": "global",
_67
"inbound_mps": -1
_67
},
_67
"mms": {
_67
"inbound_connectivity": true,
_67
"outbound_connectivity": true,
_67
"inbound_reachability": "global",
_67
"inbound_mps": -1
_67
}
_67
},
_67
"regulatory": {
_67
"address_requirements": "none"
_67
},
_67
"type": "local",
_67
"lifecycle": "generally-available",
_67
"geography": {
_67
"iso_country": "US",
_67
"lata": 132,
_67
"rate_center": "HUNTINGTON",
_67
"latitude": 40.8719,
_67
"longitude": -73.4347,
_67
"region": "NY",
_67
"locality": "HUNTINGTON",
_67
"postal_code": "11743"
_67
}
_67
}
_67
],
_67
"meta": {
_67
"page": 0,
_67
"page_size": 50,
_67
"first_page_url": "https://preview.twilio.com/Numbers/AvailableNumbers/US?Type=local&Capabilities.Mms.OutboundConnectivity=true&Capabilities.Mms.InboundReachability=global&PageSize=50&Page=0",
_67
"previous_page_url": null,
_67
"url": "https://preview.twilio.com/Numbers/AvailableNumbers/US?Type=local&Capabilities.Mms.OutboundConnectivity=true&Capabilities.Mms.InboundReachability=global&PageSize=50&Page=0",
_67
"next_page_url": null,
_67
"key": "items"
_67
}
_67
}


Rate this page: