Update a phone number
You need the “Manage Team Phone Numbers” permission to change most settings. If you’re the only member of a number and no Group is assigned to it, you can change its label, voicemail greeting, and call forwarding without that permission.
You can:
- Change the
labelof the number. - Set up call forwarding via
forward_toandforward_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 users are assigned directly to the number via
participants. This should be a list of user IDs. - Modify which Groups are assigned to the number via
participant_groups. This should be a list of Group IDs from the Groups API. Members of these Groups, including users added to a Group later, ring on inbound calls, receive notifications for the number, and can use it as outbound Caller ID. You can assign at most 40 Groups. - Modify which external phone numbers the number dials 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. - Let users who are not members of the number use it as their outbound Caller ID via
non_member_caller_id_enabled. - Let Local Presence pick the number for calls and SMS that voice agents make in Auto Caller ID mode via
voice_agents_local_presence_enabled. A voice agent in Fixed Caller ID mode can use the number when this setting is off. - Let Local Presence pick the number by proximity for calls and SMS via
local_presence_enabled.
You can set at most 40 users and external phone numbers combined in participants and phone_numbers.
A number’s ring order is set in Close. A number that rings its members all at once rings at most 40 users and external phone numbers per inbound call. The users in participants and the external phone numbers in phone_numbers take priority. Members of the number’s Groups who are allowed to make calls are added, chosen at random for each call, until 40 users and external phone numbers are ringing.
The per-call limit does not apply to a number that rings its members one at a time (round-robin).
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Request
Number of seconds (15-90) to ring this number on inbound calls before moving on (e.g. to voicemail).
Response
Monthly rate of the last charge for this number. null before the first charge, and for numbers that Close does not bill.
Date on which the next monthly charge for this number is due. A past date means that the charge did not go through yet, for example right after Close rents the number. null for numbers that Close does not bill, such as external numbers.
IDs of the users assigned directly to this phone number. Members of the Groups in participant_groups also ring on inbound calls, receive notifications for the number, and can use it as outbound Caller ID.
This field is deprecated and will be removed in a future update. Until then, it is set to false when participants has exactly one user and the phone number doesn’t have any of the “shared” configuration set up (e.g. a phone menu, lead-based routing, a dial-out list, an assigned Group, a non-default ring order, etc.), and true otherwise.
This field is deprecated. See the participants and participant_groups fields 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 dial-out list, an assigned Group, a non-default ring order, etc.).
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.
Present unless participants has exactly one user and the phone number has no shared-number configuration (a phone menu, lead-based routing, a dial-out list, an assigned Group, or a non-default ring order).
Present under the same condition as phone_numbers, with each value formatted for display.