API reference

AvailablePhoneNumbers API

Search the inventory of phone numbers available to provision, filtered by country, type, and area code.

Search available numbers

GET/2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/{CountryCode}/{Type}

Return numbers available in a country. {CountryCode} is an ISO 3166-1 alpha-2 code (e.g. NG). {Type} is local, mobile, or toll_free.

Parameter	Type	Description
`AreaCode` optional	`string`	Filter by area code / prefix.
`Contains` optional	`string`	Filter by digits contained in the number.
`Page` optional	`integer`	0-indexed page.
`PageSize` optional	`integer`	Records per page (max 1000).

Response

{
  "available_phone_numbers": [
    {
      "friendly_name": "(201) 555-0123",
      "phone_number": "+23412000000",
      "locality": "Lagos",
      "region": "LA",
      "iso_country": "NG",
      "capabilities": { "voice": true, "sms": true },
      "price": "5000.00",
      "price_unit": "NGN"
    }
  ],
  "uri": "/2010-04-01/Accounts/AC…/AvailablePhoneNumbers/NG/Local"
}

With the SDK

const numbers = await client.availablePhoneNumbers.list({
  countryCode: "NG",
  type: "local",
  areaCode: "1",
});

for (const n of numbers.available_phone_numbers) {
  console.log(n.phone_number, n.locality, n.price);
}

Once you find a number, provision it with IncomingPhoneNumbers.