CLclose
phone_numbers

Update a phone number

Changed on

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 label of the 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 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. You cannot disable this setting while a voice agent uses the number.
  • 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).

put/phone_number/{id}/

Request

  • Base URL
    https://api.close.com/api/v1
  • URL
    https://api.close.com/api/v1/phone_number/{id}/
  • Auth
    • HTTP basic
    • or OAuth 2
      Authorization code: https://app.close.com/oauth2/authorize/
      Token URL: https://api.close.com/oauth2/token/

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
local_presence_enabledboolean

Whether Local Presence can pick this phone number by proximity for a call or SMS made as a user.

non_member_caller_id_enabledboolean

Whether users who are not members of this phone number can use it as their outbound caller ID.

participant_groupsstring[]
participantsstring[]
phone_numbersstring[]
press_1_to_acceptboolean
voice_agent_caller_id_enabledboolean

Deprecated. Use voice_agents_local_presence_enabled. This field is an alias of voice_agents_local_presence_enabled, and it will be removed in a future update. If you send both fields, they must have the same value.

voice_agents_local_presence_enabledboolean

Whether Local Presence can pick this phone number for calls and SMS that voice agents make in Auto caller ID mode.

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 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.

is_premiumboolean required

This field is deprecated and will be removed in a future update. Until then, it is always false.

is_verifiedboolean required
labelstring required
last_billed_pricenumber nullable required
local_presence_enabledboolean required

Whether Local Presence can pick this phone number by proximity for a call or SMS made as a user.

mms_enabledboolean required
next_billing_onstring date-time nullable required
non_member_caller_id_enabledboolean required

Whether users who are not members of this phone number can use it as their outbound caller ID.

numberstring required
number_formattedstring required
organization_idstring required
participant_groupsstring[] required

IDs of the Groups assigned to this phone number. Members of these Groups ring on inbound calls, receive notifications for the number, and can use it as outbound caller ID. See the Groups API.

participantsstring[]

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.

phone_numbersstring[]

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

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

voice_agent_caller_id_enabledboolean required

Deprecated. Use voice_agents_local_presence_enabled. This field has the same value as voice_agents_local_presence_enabled, and it will be removed in a future update.

voice_agents_local_presence_enabledboolean required

Whether Local Presence can pick this phone number for calls and SMS that voice agents make in Auto caller ID mode.

voicemail_greeting_urlstring nullable
was_portedboolean

Changes

  • 2ff98656cc2aRevision changes
    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

  • 12a3f88e92e5Revision changes
    • info

      response property is_premium deprecated