Sign inGet Started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

List the numbers you can use for voice

GET
/v1/voice/numbers
for await (const number of bird.voice.numbers.list()) {
  console.log(number.id, number.phone_number, number.country_code);
}
Risposta200
{
  "data": [
    {
      "id": "vnu_01krdgeqcxet5s7t44vh8rt9mg",
      "phone_number": "+14155551234",
      "country_code": "US",
      "name": "Support line",
      "provider": {
        "type": "allocation",
        "number_id": "nda_01krdgeqcxet5s7t44vh8rt9mg"
      },
      "inbound_configuration": {
        "route": {
          "type": "reject"
        },
        "configuration_error": "unsupported_route_type",
        "forward_as_options": [
          "dialed_number",
          "calling_number"
        ]
      }
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

Lists the phone numbers your workspace can use for voice: the voice-capable numbers we allocated to you, and the numbers from other carriers you registered and verified. One list, ordered by number.

Each entry is one phone number, and provider says which of the two it is.

This is one cursor page, not the whole set. It returns 25 numbers unless you ask for more with limit, so follow the cursor until it stops rather than treating the first page as everything you have.

Parametri di query

searchstring

Matches part of the phone number or name, ignoring case. Characters such as % and _ match literally.

providerstring

Filter by number source. allocation selects numbers we allocated to your workspace. verified_number selects numbers from another carrier that you registered for use as caller IDs.

Possible values: allocation, verified_number

routestring

Filter by the answer incoming calls get. A number without a route of its own matches the route of your workspace's default.

  • reject: rejects incoming calls.
  • trunk: delivers calls to a SIP trunk.
  • forward: connects calls to the configured forwarding number.
  • sequence: runs the selected voice sequence entry.

Numbers with an unsupported route are excluded when this filter is set.

Possible values: reject, trunk, forward, sequence

sortstring

Field to sort by.

Possible values: phone_number

orderstring

Sort direction. Defaults to asc, which sorts alphabetically or from oldest to newest, depending on the selected sort field.

Possible values: asc, desc

limitinteger

Maximum number of items to return per page.

starting_afterstring

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

ending_beforestring

Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

Payload di risposta

data
array of object
obbligatorio
Mostra attributi secondari
data.id
string
obbligatorio

Identifier of this number, to pass to the operations that read and change it. A number you registered as a caller ID carries the same identifier there, with the caller-ID prefix.

data.phone_number
string
obbligatorio

The phone number in E.164 format.

data.country_code
nullable string
obbligatorio

Country the number belongs to. Null when the number is not geographic or its country cannot be determined.

data.name
nullable string
obbligatorio

Your own label for this number, to tell several apart. Null when it has none. Only you see it, so it never affects what a caller sees.

data.provider
object
obbligatorio

Where this number came from, and the facts that belong to that answer. The type selects the shape. allocation is a number we allocated to your workspace, and it carries that allocation's identifier. verified_number is a number from another carrier, and it carries how far proving control of it has got.

Mostra attributi secondari
data.directions
object
obbligatorio

Which directions this number can carry. Both follow from the number itself, so neither is yours to change. On a SIP trunk each direction is a setting you turn on; here it is a fact about the number.

Mostra attributi secondari
data.directions.inbound
boolean
obbligatorio

Whether calls to this number arrive here. False for a number from another carrier, whose calls that carrier routes, and for one allocated to you that cannot carry calls.

data.directions.outbound
boolean
obbligatorio

Whether this number can be presented on a call you place. Buying a number does not grant this on its own: proving control of it does.

data.inbound_configuration
object
obbligatorio

What happens to a call arriving for this number.

Mostra attributi secondari
data.created_at
string
obbligatorio

When this number became usable for voice: when it was allocated to you, or when you first registered it, whichever this number is.

next_cursor
nullable string
obbligatorio

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

prev_cursor
nullable string
obbligatorio

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

refresh_cursor
nullable string
obbligatorio

Refresh anchor, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

Risorse correlate

Continua con la documentazione, le guide e gli esempi per questo argomento.

Ottieni un brief di implementazione