---
title: "Get a voice number"
method: GET
path: "/v1/voice/numbers/{number_id}"
tags: ["voice-numbers"]
---

# Get a voice number

`GET /v1/voice/numbers/{number_id}`

## Request

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

Returns one of the numbers your workspace can use for voice.

A number with no route of its own reads back with a null route and follows
your workspace's default inbound route, which
[Get the voice settings](/docs/api/reference/get-voice-settings) returns.

## Headers

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

## Response `200`

The number.

- VoiceNumber
  - `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.

## 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/3e2a50466454?raw)