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);
}for number in client.voice.numbers.list():
print(number.id, number.phone_number, number.country_code)for number, err := range client.Voice.Numbers.List(context.Background(), bird.VoiceNumbersListParams{}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(number.Id, number.PhoneNumber, number.CountryCode)
}foreach ($bird->voice->numbers->list() as $number) {
echo $number->getId(), ' ', $number->getPhoneNumber(), "\n";
}bird voice numbers listcurl -X GET "https://us1.platform.bird.com/v1/voice/numbers" \
-H "Authorization: Bearer $TOKEN" \
--url-query "sort=phone_number" \
--url-query "order=asc" \
--url-query "limit=25"Réponse200
{
"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": [
"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.
Paramètres de requête
sort
string
Field to sort by.
Possible values: phone_number
order
string
Sort direction. Defaults to asc, which sorts alphabetically or from oldest to newest, depending on the selected sort field.
Possible values: asc, desc
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 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.
Contenu de la réponse
data
array of object
obligatoire
Afficher les attributs enfants
data.id
string
obligatoire
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
obligatoire
The phone number in E.164 format.
data.country_code
nullable string
obligatoire
Country the number belongs to. Null when the number is not geographic or its country cannot be determined.
data.name
nullable string
obligatoire
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
obligatoire
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.
Afficher les attributs enfants
data.provider.type
string
obligatoire
A number we allocated to your workspace.
Value: allocation
data.provider.number_id
nullable string
obligatoire
Identifier of this number's allocation, to pass to the numbers operations. Null when the allocation behind this number cannot be resolved.
data.provider.type
string
obligatoire
A number from another carrier that you registered here. That carrier decides where calls to it go; we only present it on calls you place.
Value: verified_number
data.provider.status
string
obligatoire
How far proving control of this number has got.
Possible values (may grow over time): pending, verified, failed
data.provider.verified_at
nullable string
obligatoire
When control of this number was last proven. Null until it is.
data.directions
object
obligatoire
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.
Afficher les attributs enfants
data.directions.inbound
boolean
obligatoire
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
obligatoire
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
obligatoire
What happens to a call arriving for this number.
Afficher les attributs enfants
data.inbound_configuration.route
nullable object
obligatoire
Null when the stored route type is unsupported; inspect configuration_error before changing it.
Afficher les attributs enfants
data.inbound_configuration.route.type
string
obligatoire
Refuses the call. Every number starts here, and setting it again is how you stop a number answering without giving it up.
Value: reject
data.inbound_configuration.route.type
string
obligatoire
Delivers the call to one of your SIP trunks.
Value: trunk
data.inbound_configuration.route.trunk_id
string
obligatoire
The SIP trunk that answers calls to this number. It must be one of yours and must have inbound calling enabled. Turning that trunk's inbound calling off, or deleting it, puts this number back on "reject".
data.inbound_configuration.route.type
string
obligatoire
Places a call to another of your numbers and connects the two.
Value: forward
data.inbound_configuration.route.forward_to
string
obligatoire
The number calls are forwarded to, in E.164 format. It has to be one of your verified caller IDs. That is checked when you set it and again on every call it forwards, so a caller ID you later remove stops forwarding rather than carrying on.
data.inbound_configuration.route.forward_as
string
obligatoire
Which of the forwarded call's two numbers it shows as the caller. State it on every write: there is no default to fall back on, and a number configured before this option existed reads back the value its calls carry rather than nothing.
On read it is always that value, which can differ from what was last written. Where your workspace is not approved to place calls from numbers you bought from us, a forward shows the calling number whatever it was set to, and this field says so.
Possible values: dialed_number, calling_number
data.inbound_configuration.route.type
string
obligatoire
Runs the named sequence's active publication from the selected voice-call entry.
Value: sequence
data.inbound_configuration.route.sequence_id
string
obligatoire
Named sequence whose active publication handles the call.
data.inbound_configuration.route.entry_node_id
string
obligatoire
Voice-call entry in the sequence's active publication.
data.inbound_configuration.configuration_error
string
Possible values: unsupported_route_type
data.inbound_configuration.forward_as_options
array of string
Which numbers a forward from this number may be set to show as the caller. A value outside this list is refused on write.
"dialed_number" is present only where your workspace is approved to place calls from numbers you bought from us.
data.created_at
string
obligatoire
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
obligatoire
Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.
prev_cursor
nullable string
obligatoire
Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.
refresh_cursor
nullable string
obligatoire
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.
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Comprendre le conceptShould I use a Bird SDK or call the API directly?Suivre le parcours d'apprentissageBuild your first integrationGuide d'implémentationSend your first email
Obtenir un guide d'implémentation