numbers

Get an available phone number

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.

get/v1/numbers/available/{number}

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/numbers/available/{number}
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Path parameters

numberstring required

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

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

The available phone number.

numberstring required

Phone number in E.164 format.

country_codestring required

ISO 3166-1 alpha-2 country code.

number_typestring required

Physical type of a phone number. New number types may be added over time, so treat unrecognized values as supported types rather than errors.

capabilitiesNumberCapability[] required

Capabilities supported by this number.

ownership_registration_requiredboolean required

Whether ownership paperwork must be approved before outbound SMS and voice use. Customer availability accounts for organization exemptions; admin supplier searches report the general country and number-type requirement. You can acquire the number, including Bird stock, and submit paperwork afterward. Any pricing.setup_price is charged during purchase, plus any tax. The recurring charge, net of tax pricing.recurring_price multiplied by pricing.intervals_per_charge, is taken with any tax at assignment and at each renewal, even while approval is pending; assignment may follow completion of a pending supplier order.

ownership_address_scopestring

Where the carrier requires the business address on this number's ownership registration to be. Present only when the carrier itself registers the number before it carries traffic and states a rule; omitted otherwise. An address that does not meet the rule is refused after purchase, and only an address that meets it can fix the registration.

  • anywhere: any business address.
  • country: a business address in the number's country.
  • number_area: a business address inside the number's own area code, for example in Amsterdam for an Amsterdam (020) number.

Example response

{
  "country_code": "US",
  "pricing": {
    "setup_price": {
      "amount": "0.00995",
      "currency_code": "EUR"
    },
    "recurring_price": {
      "amount": "0.00995",
      "currency_code": "EUR"
    },
    "recurring_period": {
      "unit": "month",
      "count": 3
    },
    "intervals_per_charge": 12
  }
}

Changes

No recorded changes to this operation across all 3 revisions of this API.