List available phone numbers

GET

/v1/numbers/available

// The search is always country-scoped, so country_code is required.
const page = await bird.numbers.available.list({
  country_code: "GB",
  capabilities: ["sms", "voice"],
});
for (const candidate of page.data) {
  console.log(candidate.number, candidate.number_type);
}

# The search is always country-scoped, so country_code is required.
page = client.numbers.available.list(country_code="GB", capabilities=["sms", "voice"])
for candidate in page.data:
    print(candidate.number, candidate.number_type)

for candidate, err := range client.Numbers.Available.List(context.Background(), bird.NumbersAvailableListParams{
	CountryCode:  "GB",
	Capabilities: []string{"sms", "voice"},
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(candidate.Number, candidate.NumberType)
}

// The search is always country-scoped, so country_code is required.
$page = $bird->numbers->available->list([
    'country_code' => 'GB',
    'capabilities' => ['sms', 'voice'],
]);
foreach ($page as $candidate) {
    echo $candidate->getNumber(), ' ', $candidate->getNumberType(), "\n";
}

curl -X GET "https://us1.platform.bird.com/v1/numbers/available" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "limit=25"

Response200

{
  "data": [
    {
      "country_code": "US",
      "number_type": "mobile",
      "capabilities": [
        "sms"
      ]
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

Returns phone numbers available for purchase in a country, newest first. Narrow the search with number_type, capabilities, and prefix. Inventory numbers are returned first and support pagination. The final page can include a live snapshot of numbers available from suppliers.

Parámetros de consulta

country_code

string

ISO 3166-1 alpha-2 country code to search in.

number_type

string

Return only numbers of this physical type after applying the country and prefix filters.

Possible values (may grow over time): mobile, local, national, short_code, short_code_fteu, toll_free

prefix

string

Return only numbers that start with these digits, matched right after the country dial code: with country_code=US, prefix=212 matches +1 212 area-code numbers and prefix=833 matches 833 toll-free numbers. Digits only. Leave out the country dial code and any national dialing prefix such as a leading 0. Short codes never match a prefix search.

capabilities

array

Filter by channel capability. Repeat the parameter to require several at once: capabilities=sms&capabilities=voice returns only numbers that support both.

limit

integer

Maximum number of items to return per page.

starting_after

string

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_before

string

Cursor from the prev_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order.

Carga de respuesta

data

array of object

obligatorio

Mostrar atributos secundarios

data.number

string

obligatorio

Phone number in E.164 format.

data.country_code

string

obligatorio

ISO 3166-1 alpha-2 country code.

data.number_type

string

obligatorio

Physical type of this phone number.

data.capabilities

array of string

obligatorio

Channel capabilities supported by this number.

next_cursor

nullable string

obligatorio

Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.

prev_cursor

nullable string

obligatorio

Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.

refresh_cursor

nullable string

obligatorio

Refresh anchor. Pass back as ending_before later to fetch items that have appeared since this response. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

// The search is always country-scoped, so country_code is required.
const page = await bird.numbers.available.list({
  country_code: "GB",
  capabilities: ["sms", "voice"],
});
for (const candidate of page.data) {
  console.log(candidate.number, candidate.number_type);
}

# The search is always country-scoped, so country_code is required.
page = client.numbers.available.list(country_code="GB", capabilities=["sms", "voice"])
for candidate in page.data:
    print(candidate.number, candidate.number_type)

for candidate, err := range client.Numbers.Available.List(context.Background(), bird.NumbersAvailableListParams{
	CountryCode:  "GB",
	Capabilities: []string{"sms", "voice"},
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(candidate.Number, candidate.NumberType)
}

// The search is always country-scoped, so country_code is required.
$page = $bird->numbers->available->list([
    'country_code' => 'GB',
    'capabilities' => ['sms', 'voice'],
]);
foreach ($page as $candidate) {
    echo $candidate->getNumber(), ' ', $candidate->getNumberType(), "\n";
}

curl -X GET "https://us1.platform.bird.com/v1/numbers/available" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "limit=25"

Response200

{
  "data": [
    {
      "country_code": "US",
      "number_type": "mobile",
      "capabilities": [
        "sms"
      ]
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}