Skip to navigation
API ReferencePhone Numbers

List available numbers to purchase

GET /api/v1/phone/numbers/twilio/available

Query Parameters:

  • providerId (required): Provider ID
  • countryCode (required): ISO country code (e.g., “US”, “GB”)
  • numberType (optional): “local”, “toll_free”, or “mobile” (default: “local”)
  • areaCode (optional): Area code filter (US/Canada only)
  • contains (optional): Pattern to match (supports wildcards: *, %)
  • inPostalCode (optional): Filter by postal/ZIP code
  • inRegion (optional): Filter by state/region
  • inRateCenter (optional): Filter by rate center
  • inLata (optional): Filter by LATA
  • inLocality (optional): Filter by city
  • nearNumber (optional): Find numbers near this phone number
  • nearLatLong (optional): Find numbers near lat,long
  • distance (optional): Radius in miles (default: 25, max: 500)
  • smsEnabled (optional): Filter SMS-capable numbers
  • mmsEnabled (optional): Filter MMS-capable numbers
  • voiceEnabled (optional): Filter voice-capable numbers
  • faxEnabled (optional): Filter fax-capable numbers
  • beta (optional): Filter beta numbers
  • excludeAllAddressRequired (optional): Exclude numbers requiring any address
  • excludeLocalAddressRequired (optional): Exclude numbers requiring local address
  • excludeForeignAddressRequired (optional): Exclude numbers requiring foreign address
  • limit (optional): Max results (default: 20, max: 1000)

Authentication

AuthorizationBearer

Pass a JWT access token or an API key (prefixed with tif_live_) as a Bearer token.

Query parameters

providerIdstringRequired

Provider ID (required)

countryCodestringRequired

ISO country code (required, e.g. “US”, “GB”, “CA”)

numberTypestringOptional

Number type: “local”, “toll_free”, or “mobile” (default: “local”)

areaCodestringOptional

Area code filter (US/Canada only)

containsstringOptional

Pattern to match in the phone number (supports wildcards: *, %)

inPostalCodestringOptional

Filter by postal/ZIP code (US/Canada only)

inRegionstringOptional

Filter by state/region (US/Canada only)

inRateCenterstringOptional

Filter by rate center (US/Canada only, requires in_lata)

inLatastringOptional

Filter by LATA (US/Canada only)

inLocalitystringOptional

Filter by locality/city

nearNumberstringOptional
Find numbers geographically close to this phone number
nearLatLongstringOptional

Find numbers near lat,long (e.g. “37.7749,-122.4194”)

distanceintegerOptional>=0

Distance radius in miles for geographic searches (default: 25, max: 500)

smsEnabledbooleanOptional

Filter for SMS-capable numbers

mmsEnabledbooleanOptional

Filter for MMS-capable numbers

voiceEnabledbooleanOptional

Filter for voice-capable numbers

faxEnabledbooleanOptional

Filter for fax-capable numbers

betabooleanOptional

Filter for beta numbers (new to Twilio)

excludeAllAddressRequiredbooleanOptional
Exclude numbers that require any address
excludeLocalAddressRequiredbooleanOptional
Exclude numbers that require a local address
excludeForeignAddressRequiredbooleanOptional
Exclude numbers that require a foreign address
limitintegerOptional>=0

Maximum number of results (default: 20, max: 1000)

Response

Available numbers and the search that produced them
numberslist of objects
Numbers available for purchase
queryobject
The search criteria that produced this result

Errors

401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error
500
Internal Server Error