Get an available phone number

GET

/v1/numbers/available/{number}

// A number a carrier supplies is only on sale while the carrier still has it,
// so a 404 here means someone else took it.
const candidate = await bird.numbers.available.get("+447700900201");
console.log(candidate.country_code, candidate.capabilities);

# A number a carrier supplies is only on sale while the carrier still has
# it, so a 404 here means someone else took it.
candidate = client.numbers.available.get("+447700900201")
print(candidate.country_code, candidate.capabilities)

candidate, err := client.Numbers.Available.Get(context.Background(), "+447700900201")
if err != nil {
	log.Fatal(err)
}
fmt.Println(candidate.CountryCode)

// A number a carrier supplies is only on sale while the carrier still has it,
// so a 404 here means someone else took it.
$candidate = $bird->numbers->available->get('+447700900201');
echo $candidate->getCountryCode(), "\n";

bird numbers available get <number>

curl -X GET "https://us1.platform.bird.com/v1/numbers/available/{number}" \
  -H "Authorization: Bearer $TOKEN"

Response200

{
  "country_code": "US",
  "number_type": "mobile",
  "capabilities": [
    "sms"
  ]
}

Returns a single phone number available for purchase, whether it is already in inventory or can be acquired for you. Numbers supplied through a carrier remain available only while the carrier has them, so a number listed a moment ago may already be gone. A 404 means the number is currently unavailable for sale.

Parameters

number

string

Phone number in E.164 format. The leading + is optional.

Response Payload

number

string

required

Phone number in E.164 format.

country_code

string

required

ISO 3166-1 alpha-2 country code.

number_type

string

required

Physical type of this phone number.

capabilities

array of string

required

Capabilities supported by this number.

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Understand the conceptWhat is a virtual phone number (VMN)?Explore the capabilitySMS numbers Implementation guideNumber types

Get an implementation brief

// A number a carrier supplies is only on sale while the carrier still has it,
// so a 404 here means someone else took it.
const candidate = await bird.numbers.available.get("+447700900201");
console.log(candidate.country_code, candidate.capabilities);

# A number a carrier supplies is only on sale while the carrier still has
# it, so a 404 here means someone else took it.
candidate = client.numbers.available.get("+447700900201")
print(candidate.country_code, candidate.capabilities)

candidate, err := client.Numbers.Available.Get(context.Background(), "+447700900201")
if err != nil {
	log.Fatal(err)
}
fmt.Println(candidate.CountryCode)

// A number a carrier supplies is only on sale while the carrier still has it,
// so a 404 here means someone else took it.
$candidate = $bird->numbers->available->get('+447700900201');
echo $candidate->getCountryCode(), "\n";

bird numbers available get <number>

curl -X GET "https://us1.platform.bird.com/v1/numbers/available/{number}" \
  -H "Authorization: Bearer $TOKEN"

Response200

{
  "country_code": "US",
  "number_type": "mobile",
  "capabilities": [
    "sms"
  ]
}