Sign in
phone_numbers

Update a phone number

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.
put/phone_number/{id}/

Path parameters

idstring required

Request body

forward_tostring
forward_to_enabledboolean
inbound_ring_durationinteger

Number of seconds (15-90) to ring this number on inbound calls before moving on (e.g. to voicemail).

labelstring
participantsstring[]
phone_numbersstring[]
press_1_to_acceptboolean
voicemail_greeting_urlstring nullable

Response

Successful response

address_idstring nullable required
bundle_idstring nullable required
carrier'twilio' | 'plivo' required
carrier_type'local' | 'national' | 'mobile' | 'tollfree' | 'shortcode' required
countrystring nullable required
date_createdstring date-time required
date_updatedstring date-time required
forward_tostring nullable
forward_to_enabledboolean
forward_to_formattedstring nullable
idstring required
inbound_ring_durationinteger 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_numberboolean required

This field is deprecated and will be removed in a future update. Until then, it is set to false when the phone number has exactly one member (as defined by the participants field) and doesn't have any of the "shared" configuration set up (e.g. a phone menu, lead-based routing, a non-default ring order, etc.), and true otherwise.

is_premiumboolean required
is_verifiedboolean required
labelstring required
last_billed_pricenumber nullable required
mms_enabledboolean required
next_billing_onstring date-time nullable required
numberstring required
number_formattedstring required
organization_idstring required
participantsstring[]

Every member of the phone number, as user IDs. If this field is absent, see user_id for the sole member.

phone_numbersstring[]

Present unless the phone number has exactly one member and no shared-number configuration (a phone menu, lead-based routing, a dial-out list, or a non-default ring order).

phone_numbers_formattedstring[]

Present under the same condition as phone_numbers, with each value formatted for display.

press_1_to_acceptboolean
sms_enabledboolean required
supports_mms_to_countriesstring[] required
supports_sms_to_countriesstring[] required
type'internal' | 'external' | 'virtual' required
user_idstring nullable required

This field is deprecated. See the participants field instead to learn who's assigned to this phone number. This user_id field will be removed in a future update. Until then, it is set to a specific user ID only if the given phone number has a single participant and no additional "shared" configuration (e.g. a phone menu, lead-based routing, a non-default ring order, etc.).

voicemail_greeting_urlstring nullable
was_portedboolean

Changes