Skip to navigation
Communication ConfigurationPhone Numbers

Retrieve a single phone number

View as Markdown

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.

Path parameters

idstringRequired

Query parameters

_fieldsstringOptional

Comma-separated list of fields to include in the response.

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

voice_agent_caller_id_enabledbooleanDeprecated

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.

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
404
Not Found Error
429
Too Many Requests Error