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

# Update a voice number

`PATCH /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`

Changes what you have said about this number: the label you gave it, and what
happens when a call arrives for it. Omit a field to leave it as it is.

The route replaces whatever was set before, because a number has exactly one
answer at a time. A null route returns the number to your workspace's
default inbound route, set with
[Update the voice settings](/docs/api/reference/update-voice-settings).
Type "reject" refuses calls whatever the default is.
"trunk" needs a trunk_id: the trunk must be yours and must have inbound
calling enabled. "forward" needs a forward_to, which 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.

Sequence management remains in the dashboard. A `sequence` route needs
`sequence_id` and `entry_node_id` from an existing active publication in your
workspace. Binding a sequence with recording commands or managed recording
transfers requires organization preview access. Sequence management endpoints
are not available through the public API; see the
[call sequences guide](https://bird.com/docs/guides/voice/call-sequences).

Only a number whose calls arrive here can carry a route. A number from
another carrier is somewhere calls can be sent to, and that carrier routes
the calls made to it, so inbound_configuration is refused on it. The label
can be set on either.

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- VoiceNumberUpdate
  - `name` string, nullable: Your own label for this number. Send null to remove the one it has. Omit the field to leave it alone.
  - `inbound_configuration` VoiceInboundConfigurationPut
    - `route` union, required: What happens to a call arriving for this number. Its `type` selects the shape, and each answer carries its own fields; the variants below are the full set you can set.
      - 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.

## Response `200`

The number as it now stands.

- 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
- `409`: Resource conflict
- `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
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[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)