---
title: "List the numbers you can use for voice"
method: GET
path: "/v1/voice/numbers"
tags: ["voice-numbers"]
---

# List the numbers you can use for voice

`GET /v1/voice/numbers`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/voice/numbers`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

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.

## Query parameters

- `search` string
- `provider` 'allocation' | 'verified_number': Where a number came from. `allocation` is a number we allocated to your workspace, and the only kind whose calls reach us. `verified_number` is a number from another carrier that you registered and proved you control, so it can be presented on a call you place.
- `route` 'reject' | 'trunk' | 'forward' | 'sequence': Which answer a number carries. - `reject`: refuses the call. - `trunk`: delivers the call to one of your SIP trunks. - `forward`: places a call to one of your verified caller IDs and connects the two. - `sequence`: runs the configured sequence from its selected voice-call entry. It selects the answer's own shape, so a new way to answer a call arrives as a new value alongside a new set of fields.
- `sort` 'phone_number': Field used to sort the list.
- `order` 'asc' | 'desc': Sort direction, ascending or descending.
- `limit` integer
- `starting_after` string
- `ending_before` string

## Headers

- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

Paginated list of the numbers the workspace can use for voice.

- VoiceNumberList
  - `data` VoiceNumber[], required
    - `id` string, required
    - `phone_number` string, required: The phone number in E.164 format.
    - `country_code` string, required: ISO 3166-1 alpha-2 country code.
    - `name` string, nullable, required: 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.
    - `provider` union, required: 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.
      - VoiceNumberProviderAllocation
        - `type` 'allocation' | 'verified_number', required: Where a number came from. `allocation` is a number we allocated to your workspace, and the only kind whose calls reach us. `verified_number` is a number from another carrier that you registered and proved you control, so it can be presented on a call you place.
        - `number_id` string, required: Identifier of a number allocated to your workspace, as returned in the id field of `GET /v1/numbers`.
      - VoiceNumberProviderVerifiedNumber
        - `type` 'allocation' | 'verified_number', required: Where a number came from. `allocation` is a number we allocated to your workspace, and the only kind whose calls reach us. `verified_number` is a number from another carrier that you registered and proved you control, so it can be presented on a call you place.
        - `status` string, required: Verification state of the verified number. - `pending`: the number is registered but ownership has not yet been proven. - `verified`: the workspace proved ownership of the number. Check the resource's activation or direction fields for outbound availability. - `failed`: terminal because the verification challenge expired or the attempt limit was exhausted. Delete the verified number and register it again to retry. Open enum: additional states may be added over time, so treat an unrecognized value as a future state rather than an error.
        - `verified_at` string, date-time, nullable, required: When control of this number was last proven. Null until it is.
    - `directions` VoiceNumberDirections, required
      - `inbound` boolean, required: 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.
      - `outbound` boolean, required: 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.
    - `inbound_configuration` VoiceInboundConfiguration, required
      - `route` union, required: What happens to a call arriving for this number, as it is configured now. Its `type` selects the shape, and each answer carries its own fields. Setting a route is a separate shape, and it does not offer every variant reported here.
        - VoiceCallRouteReject
          - `type` 'reject' | 'trunk' | 'forward' | 'sequence', required: Which answer a number carries. - `reject`: refuses the call. - `trunk`: delivers the call to one of your SIP trunks. - `forward`: places a call to one of your verified caller IDs and connects the two. - `sequence`: runs the configured sequence from its selected voice-call entry. It selects the answer's own shape, so a new way to answer a call arrives as a new value alongside a new set of fields.
        - VoiceCallRouteTrunk
          - `type` 'reject' | 'trunk' | 'forward' | 'sequence', required: Which answer a number carries. - `reject`: refuses the call. - `trunk`: delivers the call to one of your SIP trunks. - `forward`: places a call to one of your verified caller IDs and connects the two. - `sequence`: runs the configured sequence from its selected voice-call entry. It selects the answer's own shape, so a new way to answer a call arrives as a new value alongside a new set of fields.
          - `trunk_id` string, required
        - VoiceCallRouteForward
          - `type` 'reject' | 'trunk' | 'forward' | 'sequence', required: Which answer a number carries. - `reject`: refuses the call. - `trunk`: delivers the call to one of your SIP trunks. - `forward`: places a call to one of your verified caller IDs and connects the two. - `sequence`: runs the configured sequence from its selected voice-call entry. It selects the answer's own shape, so a new way to answer a call arrives as a new value alongside a new set of fields.
          - `forward_to` string, required: 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.
          - `forward_as` 'dialed_number' | 'calling_number', required: Which of a forwarded call's two numbers it shows as the caller. `dialed_number` presents the Bird number the caller dialed. Whoever answers sees which of your numbers was called. Older configurations without a stored choice use this value. Carrier screening can still affect delivery. `calling_number` presents the caller's own number, so the phone rings as though they had dialed it directly and the call can be returned from the call log. Because the number is not one you own, some carriers (most often in the US and parts of Europe) mark such calls as unverified, replace the number, or screen them.
        - VoiceCallRouteSequence (unresolved $ref)
      - `configuration_error` 'unsupported_route_type'
      - `forward_as_options` VoiceInboundForwardAs[]: Caller identities available when configuring a forward. Use these values to populate the choice in your editor. The current choices are `dialed_number` and `calling_number`.
    - `created_at` string, date-time, required: 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` string, nullable, required: Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.
  - `prev_cursor` string, nullable, required: Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.
  - `refresh_cursor` string, nullable, required: 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`.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)