Skip to navigation

Request an internal phone number

View as Markdown

Renting a phone number incurs a cost. The new number is assigned to you unless you name other users via assign_to, which requires the “Manage Team Phone Numbers” permission.

If a number was rented, a 201 response is returned with the new number. If no number was rented (4xx response code), the response contains a status field which may contain one of the values below. New statuses may be added in the future.

  • has-voice-only: This country/prefix combination only has non-SMS-capable numbers. You can attempt renting the number by passing with_sms as false.
  • needs-more-info: More information (such as proof of address) is needed to rent this number. This number can only be rented by contacting Close support.
  • billing-error: An error related to billing has occurred. For example, the telephony budget has been reached, or there are not enough funds and recharging failed.
  • error: An error has occurred while renting this number. A human-readable message is returned in the error field.

Authentication

AuthorizationBasic
Use your API key as the username and leave the password empty.
OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
countrystringRequired

A two letter ISO country code (e.g. US for United States).

assign_tolist of strings or nullOptional
IDs of the users the new phone number is assigned to. When omitted, the number is assigned to the user making the request. Assigning it to anyone else requires the "Manage Team Phone Numbers" permission, and every user must be an active member of the organization who is allowed to make calls.
bundle_idstring or nullOptional
carrier_typeenum or nullOptional
Allowed values:
prefixstringOptional<=5 charactersDefaults to
A string with the phone number prefix or area code, not including the country code.
with_mmsboolean or nullOptional

By default, MMS-capable numbers are rented if Close supports MMS for the given country. Renting an MMS-capable number can be forced by setting this flag to true. If set to false, certain prefixes that don’t support MMS can be rented in countries where Close supports MMS. In most scenarios, this flag should not be passed. When you request an MMS number, you must set with_sms to true as well.

with_smsboolean or nullOptional

By default, SMS-capable numbers are rented if Close supports SMS for the given country. Renting an SMS-capable number can be forced by setting this flag to true. If set to false, certain prefixes that don’t support SMS can be rented in countries where Close supports SMS. In most scenarios, this flag should not be passed unless a has-voice-only error status is received.

sharingenumOptionalDeprecated

Deprecated. personal for a number that belongs to an individual user, or group for a group number. The distinction between personal and group numbers is being removed, and this field will be removed in a future update. When omitted, defaults to personal.

Allowed values:

Response

Successful response
address_idstring or null
bundle_idstring or null
carrierenum or null
Allowed values:
carrier_typeenum or null
Allowed values:
countrystring or null
date_createddatetime
date_updateddatetime
idstring
labelstring
last_billed_pricedouble or null

Monthly rate of the last charge for this number. null before the first charge, and for numbers that Close does not bill.

local_presence_enabledboolean
Whether Local Presence can pick this phone number by proximity for a call or SMS made as a user. It has no effect on a plan that doesn't include Local Presence.
mms_enabledboolean
next_billing_ondate or null

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.

non_member_caller_id_enabledboolean
Whether users who are not members of this phone number can use it as their outbound Caller ID.
numberstring
number_formattedstring
organization_idstring
participant_groupslist of strings
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.
participantslist of strings

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.

sms_enabledboolean
supports_mms_to_countrieslist of strings
supports_sms_to_countrieslist of strings
typeenum
Allowed values:
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.
is_group_numberbooleanDeprecated

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_premiumbooleanDeprecated

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

user_idstring or nullDeprecated

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

forward_tostring or nullOptional
forward_to_enabledbooleanOptional
forward_to_formattedstring or nullOptional
inbound_ring_durationinteger or nullOptional

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.

phone_numberslist of stringsOptional

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_formattedlist of stringsOptional

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

press_1_to_acceptbooleanOptional
voicemail_greeting_urlstring or nullOptional
was_portedbooleanOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error