Phone Numbers

This endpoint shows you all the phone numbers that exist in your organization and lets you rent new numbers. It lets you label them and configure their settings.

There are a few types of phone numbers:

• internal - means the number is owned and controlled by Close.
• external - the number is owned by you and can only be used for outbound Close calls as a caller ID (e.g. it could be your company cell phone number).
• virtual - the number is owned by you, but the calls are routed to Close via BYOC.

Whether a given phone number belongs to an individual user or to a group of users is determined by the is_group_number boolean. Learn more about group numbers.

If a given phone number is a group number, it will list all of its participating users' IDs in participants and all of the participating phone numbers in phone_numbers.

List or search for phone numbers.

GET /phone_number/{?number, user_id, is_group_number}

Retrieve a single phone number.

GET /phone_number/{id}/

Update a phone number.

PUT /phone_number/{id}/

You need the "Manage Group 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".

Delete a phone number.

DELETE /phone_number/{id}/

You need the "Manage Group Phone Numbers" permission to delete a group number. You can only delete your own personal numbers.

Rent an internal phone number.

POST /api/v1/phone_number/request/internal/

Renting a phone number incurs a cost. You need the "Manage Group Phone Numbers" permission to rent group numbers.

Accepts the following fields:

• country (required): A two letter ISO country code (e.g. US for United States).
• sharing (required): personal for a number that belongs to an individual user, or group for a group number.
• prefix (optional): A string with the phone number prefix or area code, not including the country code.
• with_sms (optional): 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 (see below).
• with_mms (optional): 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.

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.