This API lets you manage the phone numbers in your Zendesk voice account. See Managing Zendesk Talk lines in Zendesk help. You can also use it to search for available phone numbers.

JSON format

Phone numbers are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
brand_idintegerfalsefalseid of brand associated with the phone number
call_recording_consentstringfalsefalseWhat call recording consent is set to
capabilitiesobjectfalsefalseWhether a phone number has mms, sms, or voice capability. See the Capabilities section below.
categorised_greetingsobjecttruefalseGreeting category ids and names. See Greeting Category JSON Format
categorised_greetings_with_sub_settingsobjecttruefalseThe id and any settings associated with each greeting category. If the category has no settings, it defaults to the category name. See Managing outgoing greetings in Zendesk help
country_codestringtruefalseThe ISO code of the country for this number
created_atstringtruefalseThe date and time the phone number was created
default_greeting_idsarraytruefalseThe names of default system greetings associated with the phone number. See Managing outgoing greetings in Zendesk help
default_group_idintegerfalsefalseDefault group id. *Writeable on most of the plans.
display_numberstringtruefalseThe formatted phone number
externalbooleantruefalseThe external caller id number
failover_numberstringfalsefalseFailover number associated with the phone number
greeting_idsarrayfalsefalseCustom greetings associated with the phone number. See Create Greetings in the Talk API docs and Managing outgoing greetings in Zendesk help
group_idsarrayfalsefalseAn array of associated groups. *Writeable on most plans. If omnichannel routing is enabled, only the first group_id provided is accepted for routing purposes
idintegertruefalseAutomatically assigned upon creation
ivr_idintegerfalsefalseid of IVR associated with the phone number
line_typestringfalsefalseThe type line, either phone or digital
locationstringtruefalseThe number's geographical location. For example, "CA" or "Leeds"
namestringtruefalseThe nickname if one is set. Otherwise the display_number
nicknamestringfalsefalseThe nickname of the number if one is set
numberstringtruefalseThe phone number digits
outbound_enabledbooleanfalsefalseWhether or not the phone number has outbound enabled
post_call_voice_ai_enabledbooleanfalsefalseIf true, the phone number has voice AI enabled
priorityintegerfalsefalseLevel of priority associated with the phone number
recordedbooleanfalsefalseWhether calls for the number are recorded or not
schedule_idintegerfalsefalseid of schedule associated with the phone number
sms_enabledbooleanfalsefalseWhether or not the phone number has sms enabled
sms_group_idintegerfalsefalseThe group associated with this phone number
tokenstringfalsefalseA generated token, unique for each phone number and used when provisioning the number. *Writeable on create only.
toll_freebooleantruefalseWhether the number is toll-free or local
transcriptionbooleanfalsefalseWhether voicemail calls for the number are transcribed or not
voice_enabledbooleanfalsefalseWhether or not the phone number has voice enabled
voice_qa_enabledbooleanfalsefalseIf true, the phone number has voice QA enabled

Capabilities

NameTypeRead-onlyMandatoryDescription
smsbooleantruefalseWhether phone number has sms capability
mmsbooleantruefalseWhether phone number has mms capability
voicebooleantruefalseWhether phone number has voice capability
emergency_addressbooleantruefalseWhether the phone number can be associated with an emergency address

Example

{  "brand_id": 1,  "capabilities": {    "emergency_address": false,    "mms": false,    "sms": true,    "voice": true  },  "categorised_greetings": {    "1": "voicemail_en",    "2": "available_en"  },  "categorised_greetings_with_sub_settings": {    "1": {      "voicemail_off_inside_business_hours": "voicemail_en_voicemail_config,",      "voicemail_off_outside_business_hours": "voicemail_en_voicemail_config",      "voicemail_on_inside_business_hours": "voicemail_en,"    },    "2": {      "voicemail_off": "available_en_voicemail_config",      "voicemail_on": "available_en,"    }  },  "country_code": "US",  "created_at": "2013-04-13T16:02:33Z",  "default_greeting_ids": [    "voicemail_en",    "available_jp"  ],  "default_group_id": 1,  "display_number": "+353 76 680 1402",  "external": false,  "greeting_ids": [    1,    2  ],  "group_ids": [    1,    2  ],  "id": 6,  "location": "TX",  "name": "Awesome Support Line",  "nickname": "Awesome Support Line",  "number": "+353766801402",  "post_call_voice_ai_enabled": false,  "recorded": true,  "sms_group_id": 7,  "toll_free": false,  "transcription": false,  "voice_qa_enabled": true}

List Phone Numbers

  • GET /api/v2/channels/voice/phone_numbers

This endpoint is not available for Trial accounts.

Allowed For

  • Agents

Minimizing the results

You can reduce the number of properties per phone number in the response with the minimal_mode=true query string parameter. Example:

/api/v2/channels/voice/phone_numbers?minimal_mode=true

The minimized results include the following properties:

  • id
  • country_code
  • external
  • nickname
  • display_number
  • capabilities (sms, mms, voice)
  • sms_enabled
  • priority
  • outbound_enabled

Parameters

NameTypeInRequiredDescription
minimal_modebooleanQueryfalseEnable minimized results

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers.json \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/channels/voice/phone_numbers?minimal_mode="	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/channels/voice/phone_numbers")		.newBuilder()		.addQueryParameter("minimal_mode", "");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/channels/voice/phone_numbers',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },  params: {    'minimal_mode': '',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/channels/voice/phone_numbers?minimal_mode="headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://support.zendesk.com/api/v2/channels/voice/phone_numbers")uri.query = URI.encode_www_form("minimal_mode": "")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "count": 1,  "next_page": null,  "phone_numbers": [    {      "capabilities": {        "emergency_address": true,        "mms": false,        "sms": true,        "voice": true      },      "categorised_greetings": {        "1": "voicemail_en",        "2": "available_en"      },      "categorised_greetings_with_sub_settings": {        "1": {          "voicemail_off_inside_business_hours": "voicemail_en_voicemail_config,",          "voicemail_off_outside_business_hours": "voicemail_en_voicemail_config",          "voicemail_on_inside_business_hours": "voicemail_en"        },        "2": {          "voicemail_off": "available_en_voicemail_config",          "voicemail_on": "available_en"        }      },      "country_code": "US",      "created_at": "2013-04-13T16:02:33Z",      "default_greeting_ids": [        "voicemail_en",        "available_jp"      ],      "default_group_id": 1,      "display_number": "+353 76 680 1402",      "external": false,      "greeting_ids": [        1,        2      ],      "group_ids": [        1,        2      ],      "id": 6,      "location": "TX",      "name": "Awesome Support Line",      "nickname": "Awesome Support Line",      "number": "+353766801402",      "recorded": true,      "sms_group_id": 7,      "toll_free": false,      "transcription": false    }  ],  "previous_page": null}

Search for Available Phone Numbers

  • GET /api/v2/channels/voice/phone_numbers/search?country={country}

Returns available phone numbers.

This endpoint is not available for Trial accounts.

Allowed For

  • Agents

JSON Format of Available Phone Numbers

NameTypeComments
numberstringThe phone number digits
display_numberstringThe formatted phone number
toll_freebooleanWhether the number is toll-free or local
locationstringThe number's geographical location. For example, "CA" or "Leeds"
country_codestringThe ISO code of the country for the phone number
tokenstringA generated token unique for each phone number and used when provisioning the number
pricestringThe monthly cost of the phone number
address_requirementsstringThe type of address that must be supplied when purchasing the phone number (based on specific country regulations). Possible values: "none", "local", "any", or "foreign"

Example Queries

Search queryReturns
"country=US&toll_free=true"Toll free phone numbers from the US
"country=US&area_code=510"Phone numbers in the '510' area code from the US
"country=US&contains=pizza"Phone numbers matched to 'pizza' from the US
{  "phone_number":{    "number":         "+353766801402",    "display_number": "+353 76 680 1402",    "toll_free":      false,    "location":       "TX",    "country_code":   "US",    "token":          "24a407cef67213be6d26b4c02d7d86c0",    "price":          "$1.0"  }}

Parameters

NameTypeInRequiredDescription
area_codestringQueryfalseFind phone numbers in the specified area code. (US and Canada only)
containsstringQueryfalseThe regular expression used to search for phone numbers. Valid characters are '' and [0-9a-zA-Z]. The '' character will match any single digit
countrystringQuerytrueThe ISO country code
toll_freebooleanQueryfalseWhether the number should be toll-free or local

Code Samples

curl
curl "https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers/search.json?country={country_code}&toll_free={toll_free}&area_code={area_code}&contains={contains}" \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/channels/voice/phone_numbers/search?area_code=510&contains=&country=US&toll_free=true"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/channels/voice/phone_numbers/search")		.newBuilder()		.addQueryParameter("area_code", "510")		.addQueryParameter("contains", "")		.addQueryParameter("country", "US")		.addQueryParameter("toll_free", "true");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/channels/voice/phone_numbers/search',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },  params: {    'area_code': '510',    'contains': '',    'country': 'US',    'toll_free': 'true',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/channels/voice/phone_numbers/search?area_code=510&contains=&country=US&toll_free=true"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://support.zendesk.com/api/v2/channels/voice/phone_numbers/search")uri.query = URI.encode_www_form("area_code": "510", "contains": "", "country": "US", "toll_free": "true")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "count": 1,  "next_page": null,  "phone_numbers": [    {      "address_requirements": "none",      "capabilities": {        "mms": false,        "sms": true,        "voice": true      },      "country_code": "US",      "display_number": "+1 (240) 3123885",      "location": "MD",      "nickname": null,      "number": "+12403123885",      "price": "$1.00",      "token": "24a407cef67213be6d26b4c02d7d86c0",      "toll_free": false    }  ],  "previous_page": null}

Show Phone Number

  • GET /api/v2/channels/voice/phone_numbers/{phone_number_id}

Retrieves a phone number.

Including additional information

Use the include query parameter to retrieve additional information about a phone number. The parameter accepts the following values:

  • all_greetings
  • all_groups
  • all_schedules
  • ivrs
  • settings

For example, to retrieve a phone number's settings, use ?include=settings. The response includes a settings child object in the phone_number object. For returned settings properties, see Settings JSON Format.

Use commas to separate multiple values. Example:?include=settings,ivrs,all_groups.

Allowed For

  • Agents

Parameters

NameTypeInRequiredDescription
includestringQueryfalseParameter to include additional information. Allowed values are "settings", "ivrs", "all_greetings", "all_groups", or "all_schedules".
phone_number_idintegerPathtrueID of a phone number

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers/{phone_number_id}.json \  -v -u {email_address}/token:{api_token}
# Retrieve a phone number's settingscurl https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers/{phone_number_id}.json \  -G --data-urlencode "include=settings" \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/channels/voice/phone_numbers/900000120986?include="	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/channels/voice/phone_numbers/900000120986")		.newBuilder()		.addQueryParameter("include", "");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/channels/voice/phone_numbers/900000120986',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },  params: {    'include': '',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/channels/voice/phone_numbers/900000120986?include="headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://support.zendesk.com/api/v2/channels/voice/phone_numbers/900000120986")uri.query = URI.encode_www_form("include": "")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "phone_number": {    "brand_id": 1,    "call_recording_consent": "always",    "capabilities": {      "emergency_address": false,      "mms": false,      "sms": true,      "voice": true    },    "categorised_greetings": {      "1": "voicemail_en",      "2": "available_en"    },    "categorised_greetings_with_sub_settings": {      "1": {        "voicemail_off_inside_business_hours": "voicemail_en_voicemail_config",        "voicemail_off_outside_business_hours": "voicemail_en_voicemail_config",        "voicemail_on_inside_business_hours": "voicemail_en"      },      "2": {        "voicemail_off": "available_en_voicemail_config",        "voicemail_on": "available_en,"      }    },    "country_code": "US",    "created_at": "2013-04-13T16:02:33Z",    "default_greeting_ids": [      "voicemail_en",      "available_jp"    ],    "default_group_id": 1,    "display_number": "+353 76 680 1402",    "external": false,    "greeting_ids": [      1,      2    ],    "group_ids": [      1,      2    ],    "id": 6,    "line_type": "phone",    "location": "TX",    "name": "Awesome Support Line",    "nickname": "Awesome Support Line",    "number": "+353766801402",    "recorded": true,    "sms_group_id": 7,    "toll_free": false,    "transcription": false  }}

Create Phone Number

  • POST /api/v2/channels/voice/phone_numbers

Creates a Talk phone number from an available phone number. The available phone number is specified by a token returned by a search for available numbers. See Search for Available Phone Numbers.

Allowed For

  • Agents

Address and business verification requirements

Certain regional numbers require a valid address and/or business verification in that region before the number can be created. For more information, see Zendesk Talk and Zendesk Text number address requirements in Zendesk help.

Number needs valid address You can create a phone number that needs an address by getting the address' provider_reference using the List Addresses endpoint and adding it to the body as address_sid. Example:

{  "phone_number": {    "token": "24a407cef67213be6d26b4c02d7d86c0"  },  "address_sid": "ADXXXXXXXXXXXXXX"}

Number needs business verification The endpoint does not currently support creating a phone number that requires a valid verified business.

Example body

{  "phone_number": {    "token": "24a407cef67213be6d26b4c02d7d86c0"  }}

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers.json \  -H "Content-Type: application/json" -X POST -d '{"phone_number" : {"token": "xxx"}}' \  -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://support.zendesk.com/api/v2/channels/voice/phone_numbers"	method := "POST"	payload := strings.NewReader(`{  "phone_number": {    "token": "24a407cef67213be6d26b4c02d7d86c0"  }}`)	req, err := http.NewRequest(method, url, payload)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/channels/voice/phone_numbers")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"phone_number\": {    \"token\": \"24a407cef67213be6d26b4c02d7d86c0\"  }}""");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var data = JSON.stringify({  "phone_number": {    "token": "24a407cef67213be6d26b4c02d7d86c0"  }});
var config = {  method: 'POST',  url: 'https://support.zendesk.com/api/v2/channels/voice/phone_numbers',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport jsonfrom requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/channels/voice/phone_numbers"
payload = json.loads("""{  "phone_number": {    "token": "24a407cef67213be6d26b4c02d7d86c0"  }}""")headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"POST",	url,	auth=auth,	headers=headers,	json=payload)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://support.zendesk.com/api/v2/channels/voice/phone_numbers")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.body = %q({  "phone_number": {    "token": "24a407cef67213be6d26b4c02d7d86c0"  }})email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "phone_number": {    "brand_id": 1,    "call_recording_consent": "always",    "capabilities": {      "emergency_address": false,      "mms": false,      "sms": true,      "voice": true    },    "categorised_greetings": {      "1": "voicemail_en",      "2": "available_en"    },    "categorised_greetings_with_sub_settings": {      "1": {        "voicemail_off_inside_business_hours": "voicemail_en_voicemail_config",        "voicemail_off_outside_business_hours": "voicemail_en_voicemail_config",        "voicemail_on_inside_business_hours": "voicemail_en"      },      "2": {        "voicemail_off": "available_en_voicemail_config",        "voicemail_on": "available_en,"      }    },    "country_code": "US",    "created_at": "2013-04-13T16:02:33Z",    "default_greeting_ids": [      "voicemail_en",      "available_jp"    ],    "default_group_id": 1,    "display_number": "+353 76 680 1402",    "external": false,    "greeting_ids": [      1,      2    ],    "group_ids": [      1,      2    ],    "id": 6,    "line_type": "phone",    "location": "TX",    "name": "Awesome Support Line",    "nickname": "Awesome Support Line",    "number": "+353766801402",    "recorded": true,    "sms_group_id": 7,    "toll_free": false,    "transcription": false  }}

Update Phone Number

  • PUT /api/v2/channels/voice/phone_numbers/{phone_number_id}

Updates an existing phone number.

Including additional information

Use the include query parameter to update additional information about a phone number. The parameter accepts the following values:

  • all_greetings
  • all_groups
  • all_schedules
  • ivrs
  • settings

For example, to update a phone number's settings, use ?include=settings and include a settings child object in the request body's phone_number object. For supported settings properties, see Settings JSON Format.

Use commas to separate multiple values. Example:?include=settings,ivrs,all_groups.

Settings JSON Format

NameTypeRead-onlyMandatoryDescription
allow_outbound_callsbooleanfalsefalseWhether outbound calls are allowed on this phone number
average_wait_time_message_enabledbooleanfalsefalseWhether average wait time message is enabled on this phone number
call_offering_durationintegerfalsefalseHow long the call is offered to an agent for this phone number (in seconds)
call_recording_delete_afterstringfalsefalseLength of time before call recordings are deleted. Allowed values are 'never', '1.days', '1.weeks', '2.weeks', '1.months', '2.months', '3.months', '6.months', '1.years', and '2.years'
callback_from_queuebooleanfalsefalseWhether callback from queue is enabled on this phone number
callback_localestringfalsefalseISO 639-1 language code for the callback phone number confirmation greeting
create_ticket_for_abandoned_callsbooleanfalsefalseIf true, calls abandoned on this phone number create a ticket
dequeue_retry_if_attemptedbooleanfalsefalseIf true, the call is dequeued after a retry attempt
maximum_queue_sizeintegerfalsefalseMaximum number of phone calls allowed in the queue before being directed to voicemail
maximum_queue_wait_timeintegerfalsefalseMaximum wait time that a phone call can be allocated to the queue (in minutes)
overflow_numberobjectfalsefalseDefines an overflow number used when a call cannot currently be taken by any agents or answered by voicemail. For an example of this object, see Overflow number example
priorityintegerfalsefalsePriority of this phone number
voicemailbooleanfalsefalseIf true, voicemail is enabled for this phone number
voicemail_outside_business_hoursbooleanfalsefalseIf true, callers can leave voicemails outside of business hours
voicemail_recording_delete_afterstringfalsefalseLength of time before voicemail recordings are deleted. Allowed values are 'never', '1.days', '1.weeks', '2.weeks', '1.months', '2.months', '3.months', '6.months', '1.years', '2.years'
wrap_up_enabledbooleanfalsefalseIf true, Talk agents have time after each call to finish adding details to the ticket
wrap_up_time_limitintegerfalsefalseAmount of time agents have to wrap up calls for each number (in seconds)
Overflow number example
"overflow_number": {        "enabled": true,        "number": "+12518717081"}

Allowed For

  • Agents

Parameters

NameTypeInRequiredDescription
includestringQueryfalseParameter to include additional information. Allowed values are "settings", "ivrs", "all_greetings", "all_groups", or "all_schedules".
phone_number_idintegerPathtrueID of a phone number

Example body

{  "phone_number": {    "nickname": "Awesome Support Line"  }}

Code Samples

curl
# Update a phone number's nicknamecurl https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers/{phone_number_id}.json \  -H "Content-Type: application/json" -d '{"phone_number": {"nickname": "Awesome Support Line"}}' \  -v -u {email_address}/token:{api_token} -X PUT
# Update a phone number's transcriptioncurl "https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers/{phone_number_id}.json?include=settings" \  -H "Content-Type: application/json" -d '{"phone_number": {"transcription": true}}' \  -v -u {email_address}/token:{api_token} -X PUT
# Update callback from callback greetingcurl "https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers/{phone_number_id}.json?include=settings" \  -H "Content-Type: application/json" -d '{"phone_number": {"categorised_greetings": {"6": "callback_none"}}}' \  -v -u {email_address}/token:{api_token} -X PUT
# Update a phone number's voicemail settingcurl "https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers/{phone_number_id}.json?include=settings" \  -H "Content-Type: application/json" -d '{"phone_number": {"settings": {"voicemail": true}}}' \  -v -u {email_address}/token:{api_token} -X PUT
# Update callback from `callback_from_queue` settingcurl "https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers/{phone_number_id}.json?include=settings" \  -H "Content-Type: application/json" -d '{"phone_number": {"settings": {"callback_from_queue": false }}}' \  -v -u {email_address}/token:{api_token} -X PUT
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://support.zendesk.com/api/v2/channels/voice/phone_numbers/900000120986?include="	method := "PUT"	payload := strings.NewReader(`{  "phone_number": {    "nickname": "Awesome Support Line"  }}`)	req, err := http.NewRequest(method, url, payload)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/channels/voice/phone_numbers/900000120986")		.newBuilder()		.addQueryParameter("include", "");RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"phone_number\": {    \"nickname\": \"Awesome Support Line\"  }}""");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("PUT", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var data = JSON.stringify({  "phone_number": {    "nickname": "Awesome Support Line"  }});
var config = {  method: 'PUT',  url: 'https://support.zendesk.com/api/v2/channels/voice/phone_numbers/900000120986',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },  params: {    'include': '',  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport jsonfrom requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/channels/voice/phone_numbers/900000120986?include="
payload = json.loads("""{  "phone_number": {    "nickname": "Awesome Support Line"  }}""")headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"PUT",	url,	auth=auth,	headers=headers,	json=payload)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://support.zendesk.com/api/v2/channels/voice/phone_numbers/900000120986")uri.query = URI.encode_www_form("include": "")request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")request.body = %q({  "phone_number": {    "nickname": "Awesome Support Line"  }})email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "phone_number": {    "brand_id": 1,    "call_recording_consent": "always",    "capabilities": {      "emergency_address": false,      "mms": false,      "sms": true,      "voice": true    },    "categorised_greetings": {      "1": "voicemail_en",      "2": "available_en"    },    "categorised_greetings_with_sub_settings": {      "1": {        "voicemail_off_inside_business_hours": "voicemail_en_voicemail_config",        "voicemail_off_outside_business_hours": "voicemail_en_voicemail_config",        "voicemail_on_inside_business_hours": "voicemail_en"      },      "2": {        "voicemail_off": "available_en_voicemail_config",        "voicemail_on": "available_en,"      }    },    "country_code": "US",    "created_at": "2013-04-13T16:02:33Z",    "default_greeting_ids": [      "voicemail_en",      "available_jp"    ],    "default_group_id": 1,    "display_number": "+353 76 680 1402",    "external": false,    "greeting_ids": [      1,      2    ],    "group_ids": [      1,      2    ],    "id": 6,    "line_type": "phone",    "location": "TX",    "name": "Awesome Support Line",    "nickname": "Awesome Support Line",    "number": "+353766801402",    "recorded": true,    "sms_group_id": 7,    "toll_free": false,    "transcription": false  }}

Delete Phone Number

  • DELETE /api/v2/channels/voice/phone_numbers/{phone_number_id}

Allowed For

  • Agents

Parameters

NameTypeInRequiredDescription
phone_number_idintegerPathtrueID of a phone number

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers/{phone_number_id}.json \  -H "Content-Type: application/json" -X DELETE -v -u {email_address}/token:{api_token}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/channels/voice/phone_numbers/900000120986"	method := "DELETE"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "{email_address}/token:{api_token}"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/channels/voice/phone_numbers/900000120986")		.newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("DELETE", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'DELETE',  url: 'https://support.zendesk.com/api/v2/channels/voice/phone_numbers/900000120986',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://support.zendesk.com/api/v2/channels/voice/phone_numbers/900000120986"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"DELETE",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby
require "net/http"require "base64"uri = URI("https://support.zendesk.com/api/v2/channels/voice/phone_numbers/900000120986")request = Net::HTTP::Delete.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
null