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

AvailablePhoneNumber Local resource


The AvailablePhoneNumberLocal resource lets you search for local 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) and a variety of other geographic parameters, detailed below.

(information)

Info

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(link takes you to an external page) for country availability.


AvailablePhoneNumberLocal Properties

availablephonenumberlocal-properties page anchor
Resource properties
friendly_nametype: string<PHONE NUMBER>Not PII

A formatted version of the phone number.


phone_numbertype: string<PHONE NUMBER>Not PII

The phone number in E.164(link takes you to an external page) format, which consists of a + followed by the country code and subscriber number.


latatype: stringNot PII

The LATA(link takes you to an external page) of this phone number. Available for only phone numbers from the US and Canada.


localitytype: stringNot PII

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


rate_centertype: stringNot PII

The rate center(link takes you to an external page) of this phone number. Available for only phone numbers from the US and Canada.


latitudetype: numberNot PII

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


longitudetype: numberNot PII

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


regiontype: stringNot PII

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


postal_codetype: stringNot PII

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


iso_countrytype: string<ISO COUNTRY CODE>Not PII

address_requirementstype: stringNot PII

The type of Address(link takes you to an external page) 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.


betatype: booleanNot PII

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


capabilitiestype: object<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.


Read multiple AvailablePhoneNumberLocal resources

read-multiple-availablephonenumberlocal-resources page anchor
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/{CountryCode}/Local.json

Parameters

list-parameters page anchor
URI parameters
AccountSidtype: SID<AC>Not PII
Path Parameter

The SID of the Account(link takes you to an external page) requesting the AvailablePhoneNumber resources.


CountryCodetype: string<ISO COUNTRY CODE>Not PII
Path Parameter

The ISO-3166-1(link takes you to an external page) country code of the country from which to read phone numbers.


AreaCodetype: integerNot PII
Query Parameter

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


Containstype: stringNot PII
Query Parameter

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(link takes you to an external page) and Example 3(link takes you to an external page). If specified, this value must have at least two characters.


SmsEnabledtype: booleanNot PII
Query Parameter

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


MmsEnabledtype: booleanNot PII
Query Parameter

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


VoiceEnabledtype: booleanNot PII
Query Parameter

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


ExcludeAllAddressRequiredtype: booleanNot PII
Query Parameter

Whether to exclude phone numbers that require an Address(link takes you to an external page). Can be: true or false and the default is false.


ExcludeLocalAddressRequiredtype: booleanNot PII
Query Parameter

Whether to exclude phone numbers that require a local Address(link takes you to an external page). Can be: true or false and the default is false.


ExcludeForeignAddressRequiredtype: booleanNot PII
Query Parameter

Whether to exclude phone numbers that require a foreign Address(link takes you to an external page). Can be: true or false and the default is false.


Betatype: booleanNot PII
Query Parameter

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


NearNumbertype: string<PHONE NUMBER>Not PII
Query Parameter

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.


NearLatLongtype: stringNot PII
Query Parameter

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


Distancetype: integerNot PII
Query Parameter

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.


InPostalCodetype: stringNot PII
Query Parameter

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.


InRegiontype: stringNot PII
Query Parameter

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.


InRateCentertype: stringNot PII
Query Parameter

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.


InLatatype: stringNot PII
Query Parameter

Limit results to a specific local access and transport area (LATA(link takes you to an external page)). Given a phone number, search within the same LATA(link takes you to an external page) as that number. Applies to only phone numbers in the US and Canada.


InLocalitytype: stringNot PII
Query Parameter

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


FaxEnabledtype: booleanNot PII
Query Parameter

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


PageSizetype: integerNot PII
Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.


Pagetype: integerNot PII
Query Parameter

The page index. This value is simply for client state.


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

Find available local phone numbers by area code

find-available-local-phone-numbers-by-area-code page anchor

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.availablePhoneNumbers('US')
_11
.local
_11
.list({areaCode: 510, limit: 20})
_11
.then(local => local.forEach(l => console.log(l.friendlyName)));

Output

_24
{
_24
"available_phone_numbers": [
_24
{
_24
"address_requirements": "none",
_24
"beta": false,
_24
"capabilities": {
_24
"mms": true,
_24
"sms": false,
_24
"voice": true
_24
},
_24
"friendly_name": "(808) 925-1571",
_24
"iso_country": "US",
_24
"lata": "834",
_24
"latitude": "19.720000",
_24
"locality": "Hilo",
_24
"longitude": "-155.090000",
_24
"phone_number": "+18089251571",
_24
"postal_code": "96720",
_24
"rate_center": "HILO",
_24
"region": "HI"
_24
}
_24
],
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers/US/Local.json"
_24
}

Find phone numbers by number pattern

find-phone-numbers-by-number-pattern page anchor

Find local phone numbers in the United States starting with 510555

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.availablePhoneNumbers('US')
_11
.local
_11
.list({contains: '510555****', limit: 20})
_11
.then(local => local.forEach(l => console.log(l.friendlyName)));

Output

_24
{
_24
"available_phone_numbers": [
_24
{
_24
"address_requirements": "none",
_24
"beta": false,
_24
"capabilities": {
_24
"mms": true,
_24
"sms": false,
_24
"voice": true
_24
},
_24
"friendly_name": "(808) 925-1571",
_24
"iso_country": "US",
_24
"lata": "834",
_24
"latitude": "19.720000",
_24
"locality": "Hilo",
_24
"longitude": "-155.090000",
_24
"phone_number": "+18089251571",
_24
"postal_code": "96720",
_24
"rate_center": "HILO",
_24
"region": "HI"
_24
}
_24
],
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers/US/Local.json"
_24
}

Find phone numbers by character pattern

find-phone-numbers-by-character-pattern page anchor

Find local phone numbers that match the pattern 'STORM'

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.availablePhoneNumbers('US')
_11
.local
_11
.list({contains: 'STORM', limit: 20})
_11
.then(local => local.forEach(l => console.log(l.friendlyName)));

Output

_24
{
_24
"available_phone_numbers": [
_24
{
_24
"address_requirements": "none",
_24
"beta": false,
_24
"capabilities": {
_24
"mms": true,
_24
"sms": false,
_24
"voice": true
_24
},
_24
"friendly_name": "(808) 925-1571",
_24
"iso_country": "US",
_24
"lata": "834",
_24
"latitude": "19.720000",
_24
"locality": "Hilo",
_24
"longitude": "-155.090000",
_24
"phone_number": "+18089251571",
_24
"postal_code": "96720",
_24
"rate_center": "HILO",
_24
"region": "HI"
_24
}
_24
],
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers/US/Local.json"
_24
}

Find available phone numbers by state

find-available-phone-numbers-by-state page anchor

Find available phone numbers in Arkansas

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.availablePhoneNumbers('US')
_11
.local
_11
.list({inRegion: 'AR', limit: 20})
_11
.then(local => local.forEach(l => console.log(l.friendlyName)));

Output

_24
{
_24
"available_phone_numbers": [
_24
{
_24
"address_requirements": "none",
_24
"beta": false,
_24
"capabilities": {
_24
"mms": true,
_24
"sms": false,
_24
"voice": true
_24
},
_24
"friendly_name": "(808) 925-1571",
_24
"iso_country": "US",
_24
"lata": "834",
_24
"latitude": "19.720000",
_24
"locality": "Hilo",
_24
"longitude": "-155.090000",
_24
"phone_number": "+18089251571",
_24
"postal_code": "96720",
_24
"rate_center": "HILO",
_24
"region": "HI"
_24
}
_24
],
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers/US/Local.json"
_24
}

Find available local phone numbers by prefix

find-available-local-phone-numbers-by-prefix page anchor

Find a phone number in the London prefix (+4420)

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.availablePhoneNumbers('GB')
_11
.local
_11
.list({contains: '+4420', limit: 20})
_11
.then(local => local.forEach(l => console.log(l.friendlyName)));

Output

_24
{
_24
"available_phone_numbers": [
_24
{
_24
"address_requirements": "none",
_24
"beta": false,
_24
"capabilities": {
_24
"mms": true,
_24
"sms": false,
_24
"voice": true
_24
},
_24
"friendly_name": "(808) 925-1571",
_24
"iso_country": "US",
_24
"lata": "834",
_24
"latitude": "19.720000",
_24
"locality": "Hilo",
_24
"longitude": "-155.090000",
_24
"phone_number": "+18089251571",
_24
"postal_code": "96720",
_24
"rate_center": "HILO",
_24
"region": "HI"
_24
}
_24
],
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers/US/Local.json"
_24
}

Find regional phone numbers by feature

find-regional-phone-numbers-by-feature page anchor

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.availablePhoneNumbers('GB')
_11
.local
_11
.list({smsEnabled: true, voiceEnabled: true, limit: 20})
_11
.then(local => local.forEach(l => console.log(l.friendlyName)));

Output

_24
{
_24
"available_phone_numbers": [
_24
{
_24
"address_requirements": "none",
_24
"beta": false,
_24
"capabilities": {
_24
"mms": true,
_24
"sms": false,
_24
"voice": true
_24
},
_24
"friendly_name": "(808) 925-1571",
_24
"iso_country": "US",
_24
"lata": "834",
_24
"latitude": "19.720000",
_24
"locality": "Hilo",
_24
"longitude": "-155.090000",
_24
"phone_number": "+18089251571",
_24
"postal_code": "96720",
_24
"rate_center": "HILO",
_24
"region": "HI"
_24
}
_24
],
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers/US/Local.json"
_24
}

Find phone numbers without address requirements

find-phone-numbers-without-address-requirements page anchor

Find available local phone numbers that have no address requirements

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.availablePhoneNumbers('US')
_11
.local
_11
.list({excludeAllAddressRequired: true, limit: 20})
_11
.then(local => local.forEach(l => console.log(l.friendlyName)));

Output

_24
{
_24
"available_phone_numbers": [
_24
{
_24
"address_requirements": "none",
_24
"beta": false,
_24
"capabilities": {
_24
"mms": true,
_24
"sms": false,
_24
"voice": true
_24
},
_24
"friendly_name": "(808) 925-1571",
_24
"iso_country": "US",
_24
"lata": "834",
_24
"latitude": "19.720000",
_24
"locality": "Hilo",
_24
"longitude": "-155.090000",
_24
"phone_number": "+18089251571",
_24
"postal_code": "96720",
_24
"rate_center": "HILO",
_24
"region": "HI"
_24
}
_24
],
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers/US/Local.json"
_24
}

Advanced list filter example

advanced-list-filter-example page anchor

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_17
// Download the helper library from https://www.twilio.com/docs/node/install
_17
// Find your Account SID and Auth Token at twilio.com/console
_17
// and set the environment variables. See http://twil.io/secure
_17
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_17
const authToken = process.env.TWILIO_AUTH_TOKEN;
_17
const client = require('twilio')(accountSid, authToken);
_17
_17
client.availablePhoneNumbers('US')
_17
.local
_17
.list({
_17
nearLatLong: '37.840699,-122.461853',
_17
distance: 50,
_17
contains: '555',
_17
inRegion: 'CA',
_17
limit: 20
_17
})
_17
.then(local => local.forEach(l => console.log(l.friendlyName)));

Output

_24
{
_24
"available_phone_numbers": [
_24
{
_24
"address_requirements": "none",
_24
"beta": false,
_24
"capabilities": {
_24
"mms": true,
_24
"sms": false,
_24
"voice": true
_24
},
_24
"friendly_name": "(808) 925-1571",
_24
"iso_country": "US",
_24
"lata": "834",
_24
"latitude": "19.720000",
_24
"locality": "Hilo",
_24
"longitude": "-155.090000",
_24
"phone_number": "+18089251571",
_24
"postal_code": "96720",
_24
"rate_center": "HILO",
_24
"region": "HI"
_24
}
_24
],
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/AvailablePhoneNumbers/US/Local.json"
_24
}


Rate this page: