---
title: "Update a phone number"
method: PUT
path: "/phone_number/{id}/"
tags: ["phone_numbers"]
---

# Update a phone number

`PUT /phone_number/{id}/`

You need the "Manage Team Phone Numbers" permission to update a group number. You can only update your own personal numbers.

You can:

- Change a `label` of your number.
- Set up call forwarding via `forward_to` and `forward_to_enabled`.
- Set up a voicemail greeting by including a URL of an mp3 recording in `voicemail_greeting_url`. We require the URL to be secure (i.e. starting with https://).
- Modify which team members are part of a group number via `participants`. This should be a list of user IDs.
- Modify which external phone numbers are part of a group number via `phone_numbers`. This should be a list of phone numbers in E.164 international format, e.g. "+16503334444".
- Change how long (in seconds, 15-90) the number rings on inbound calls before moving on (e.g. to voicemail) via `inbound_ring_duration`.

## Path parameters

- `id` string, required

## Request body

- UpdatePhoneNumber
  - `forward_to` string
  - `forward_to_enabled` boolean
  - `inbound_ring_duration` integer — Number of seconds (15-90) to ring this number on inbound calls before moving on (e.g. to voicemail).
  - `label` string
  - `participants` string[]
  - `phone_numbers` string[]
  - `press_1_to_accept` boolean
  - `voicemail_greeting_url` string, nullable

## Response `200`

Successful response

- PhoneNumber
  - `address_id` string, nullable, required
  - `bundle_id` string, nullable, required
  - `carrier` 'twilio' | 'plivo', required
  - `carrier_type` 'local' | 'national' | 'mobile' | 'tollfree' | 'shortcode', required
  - `country` string, nullable, required
  - `date_created` string, date-time, required
  - `date_updated` string, date-time, required
  - `forward_to` string, nullable
  - `forward_to_enabled` boolean
  - `forward_to_formatted` string, nullable
  - `id` string, required
  - `inbound_ring_duration` integer, nullable — Number of seconds we ring this number on inbound calls before moving on (e.g. to voicemail). `null` means the default of 30 seconds is used.
  - `is_group_number` boolean, required — Deprecated. The distinction between personal and group numbers is being removed, and `is_group_number` will be removed in a future update.
  - `is_premium` boolean, required
  - `is_verified` boolean, required
  - `label` string, required
  - `last_billed_price` number, nullable, required
  - `mms_enabled` boolean, required
  - `next_billing_on` string, date-time, nullable, required
  - `number` string, required
  - `number_formatted` string, required
  - `organization_id` string, required
  - `participants` string[]
  - `phone_numbers` string[]
  - `phone_numbers_formatted` string[]
  - `press_1_to_accept` boolean
  - `sms_enabled` boolean, required
  - `supports_mms_to_countries` string[], required
  - `supports_sms_to_countries` string[], required
  - `type` 'internal' | 'external' | 'virtual', required
  - `user_id` string, nullable, required — Deprecated. Set to the sole member's user ID for single-member numbers, otherwise `null`. `user_id` will be removed in a future update.
  - `voicemail_greeting_url` string, nullable
  - `was_ported` boolean

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Not found

---

[API](https://skmtc.net/close/apis/close-api.md) · [All operations](https://skmtc.net/close/apis/close-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/close/close-api/revisions/0dcf3303e9d7/schema)