# Update a voice number

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

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. Type "reject" refuses calls and is where every number
starts, so sending it clears a trunk or forward you set earlier.
"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" needs sequence_id and entry_node_id from an existing active
publication in your workspace. Setting this route requires sequence preview
access. Sequence management remains in the dashboard;
no sequence endpoints are part of the public API.

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.

## Code samples

**TypeScript**

```ts
const number = await bird.voice.numbers.update("number-id", { name: "Support line" });
console.log(number.id, number.name);
```

Examples: [TypeScript](/docs/api/reference/update-voice-number.ts.md) · [Python](/docs/api/reference/update-voice-number.py.md) · [Go](/docs/api/reference/update-voice-number.go.md) · [PHP](/docs/api/reference/update-voice-number.php.md) · [CLI](/docs/api/reference/update-voice-number.cli.md) · [cURL](/docs/api/reference/update-voice-number.curl.md)

## Example response `200`

```json
{
  "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"
    ]
  }
}
```

## Path parameters

- `number_id` (string)

## Request body

- `name` (nullable string): Your own label for this number. Send null to remove the one it has. Omit the field to leave it alone.
- `inbound_configuration` (object)

  What should happen to calls arriving for this number. The route replaces
  whatever was set before, because a number has exactly one answer at a time,
  and type "reject" is how you stop it answering. Omit the field to leave the
  answer alone.

  Only a number that can receive calls carries a route, so it is refused on
  one whose directions do not include inbound.
- `inbound_configuration.route` (object, 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. An unconfigured number uses "reject".
  - Variant `reject`
    - `inbound_configuration.route.type` (string, required)

      Refuses the call. Every number starts here, and setting it again is how you stop a number answering without giving it up.

      Value: `reject`
  - Variant `trunk`
    - `inbound_configuration.route.type` (string, required)

      Delivers the call to one of your SIP trunks.

      Value: `trunk`
    - `inbound_configuration.route.trunk_id` (string, required): 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".
  - Variant `forward`
    - `inbound_configuration.route.type` (string, required)

      Places a call to another of your numbers and connects the two.

      Value: `forward`
    - `inbound_configuration.route.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.
    - `inbound_configuration.route.forward_as` (string, required)

      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`

## Response body

- `id` (string, required): 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.
- `phone_number` (string, required): The phone number in E.164 format.
- `country_code` (nullable string, required): Country the number belongs to. Null when the number is not geographic or its country cannot be determined.
- `name` (nullable string, 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` (object, 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.
  - Variant `allocation`
    - `provider.type` (string, required)

      A number we allocated to your workspace.

      Value: `allocation`
    - `provider.number_id` (nullable string, required): Identifier of this number's allocation, to pass to the numbers operations. Null when the allocation behind this number cannot be resolved.
  - Variant `verified_number`
    - `provider.type` (string, required)

      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`
    - `provider.status` (string, required)

      How far proving control of this number has got.

      Possible values (may grow over time): `pending`, `verified`, `failed`
    - `provider.verified_at` (nullable string, required): When control of this number was last proven. Null until it is.
- `directions` (object, required): 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.
- `directions.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.
- `directions.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` (object, required): What happens to a call arriving for this number.
- `inbound_configuration.route` (nullable object, required): Null when the stored route type is unsupported; inspect configuration_error before changing it.
  - Variant `reject`
    - `inbound_configuration.route.type` (string, required)

      Refuses the call. Every number starts here, and setting it again is how you stop a number answering without giving it up.

      Value: `reject`
  - Variant `trunk`
    - `inbound_configuration.route.type` (string, required)

      Delivers the call to one of your SIP trunks.

      Value: `trunk`
    - `inbound_configuration.route.trunk_id` (string, required): 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".
  - Variant `forward`
    - `inbound_configuration.route.type` (string, required)

      Places a call to another of your numbers and connects the two.

      Value: `forward`
    - `inbound_configuration.route.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.
    - `inbound_configuration.route.forward_as` (string, required)

      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`
  - Variant `sequence`
    - `inbound_configuration.route.type` (string, required)

      Runs the named sequence's active publication from the selected voice-call entry.

      Value: `sequence`
    - `inbound_configuration.route.sequence_id` (string, required): Named sequence whose active publication handles the call.
    - `inbound_configuration.route.entry_node_id` (string, required): Voice-call entry in the sequence's active publication.
- `inbound_configuration.configuration_error` (string): Possible values: `unsupported_route_type`
- `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.
- `created_at` (string, required): When this number became usable for voice: when it was allocated to you, or when you first registered it, whichever this number is.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)