Phone numbers
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:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
brand_id | integer | false | false | id of brand associated with the phone number |
call_recording_consent | string | false | false | What call recording consent is set to |
capabilities | object | false | false | Whether a phone number has mms, sms, or voice capability. See the Capabilities section below. |
categorised_greetings | object | true | false | Greeting category ids and names. See Greeting Category JSON Format |
categorised_greetings_with_sub_settings | object | true | false | The 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_code | string | true | false | The ISO code of the country for this number |
created_at | string | true | false | The date and time the phone number was created |
default_greeting_ids | array | true | false | The names of default system greetings associated with the phone number. See Managing outgoing greetings in Zendesk help |
default_group_id | integer | false | false | Default group id. *Writeable on most of the plans. |
display_number | string | true | false | The formatted phone number |
external | boolean | true | false | The external caller id number |
failover_number | string | false | false | Failover number associated with the phone number |
greeting_ids | array | false | false | Custom greetings associated with the phone number. See Create Greetings in the Talk API docs and Managing outgoing greetings in Zendesk help |
group_ids | array | false | false | An array of associated groups. *Writeable on most plans. If omnichannel routing is enabled, only the first group_id provided is accepted for routing purposes |
id | integer | true | false | Automatically assigned upon creation |
ivr_id | integer | false | false | id of IVR associated with the phone number |
line_type | string | false | false | The type line, either phone or digital |
location | string | true | false | The number's geographical location. For example, "CA" or "Leeds" |
name | string | true | false | The nickname if one is set. Otherwise the display_number |
nickname | string | false | false | The nickname of the number if one is set |
number | string | true | false | The phone number digits |
outbound_enabled | boolean | false | false | Whether or not the phone number has outbound enabled |
post_call_voice_ai_enabled | boolean | false | false | If true, the phone number has voice AI enabled |
priority | integer | false | false | Level of priority associated with the phone number |
recorded | boolean | false | false | Whether calls for the number are recorded or not |
schedule_id | integer | false | false | id of schedule associated with the phone number |
sms_enabled | boolean | false | false | Whether or not the phone number has sms enabled |
sms_group_id | integer | false | false | The group associated with this phone number |
token | string | false | false | A generated token, unique for each phone number and used when provisioning the number. *Writeable on create only. |
toll_free | boolean | true | false | Whether the number is toll-free or local |
transcription | boolean | false | false | Whether voicemail calls for the number are transcribed or not |
voice_enabled | boolean | false | false | Whether or not the phone number has voice enabled |
voice_qa_enabled | boolean | false | false | If true, the phone number has voice QA enabled |
Capabilities
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
sms | boolean | true | false | Whether phone number has sms capability |
mms | boolean | true | false | Whether phone number has mms capability |
voice | boolean | true | false | Whether phone number has voice capability |
emergency_address | boolean | true | false | Whether 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
Name | Type | In | Required | Description |
---|---|---|---|---|
minimal_mode | boolean | Query | false | Enable 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 requests
from 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 authentication
auth = 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
Name | Type | Comments |
---|---|---|
number | string | The phone number digits |
display_number | string | The formatted phone number |
toll_free | boolean | Whether the number is toll-free or local |
location | string | The number's geographical location. For example, "CA" or "Leeds" |
country_code | string | The ISO code of the country for the phone number |
token | string | A generated token unique for each phone number and used when provisioning the number |
price | string | The monthly cost of the phone number |
address_requirements | string | The 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 query | Returns |
---|---|
"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
Name | Type | In | Required | Description |
---|---|---|---|---|
area_code | string | Query | false | Find phone numbers in the specified area code. (US and Canada only) |
contains | string | Query | false | The regular expression used to search for phone numbers. Valid characters are '' and [0-9a-zA-Z]. The '' character will match any single digit |
country | string | Query | true | The ISO country code |
toll_free | boolean | Query | false | Whether 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 requests
from 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 authentication
auth = 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
Name | Type | In | Required | Description |
---|---|---|---|---|
include | string | Query | false | Parameter to include additional information. Allowed values are "settings", "ivrs", "all_greetings", "all_groups", or "all_schedules". |
phone_number_id | integer | Path | true | ID 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 settings
curl 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 requests
from 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 authentication
auth = 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 requests
import json
from 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 authentication
auth = 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
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
allow_outbound_calls | boolean | false | false | Whether outbound calls are allowed on this phone number |
average_wait_time_message_enabled | boolean | false | false | Whether average wait time message is enabled on this phone number |
call_offering_duration | integer | false | false | How long the call is offered to an agent for this phone number (in seconds) |
call_recording_delete_after | string | false | false | Length 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_queue | boolean | false | false | Whether callback from queue is enabled on this phone number |
callback_locale | string | false | false | ISO 639-1 language code for the callback phone number confirmation greeting |
create_ticket_for_abandoned_calls | boolean | false | false | If true, calls abandoned on this phone number create a ticket |
dequeue_retry_if_attempted | boolean | false | false | If true, the call is dequeued after a retry attempt |
maximum_queue_size | integer | false | false | Maximum number of phone calls allowed in the queue before being directed to voicemail |
maximum_queue_wait_time | integer | false | false | Maximum wait time that a phone call can be allocated to the queue (in minutes) |
overflow_number | object | false | false | Defines 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 |
priority | integer | false | false | Priority of this phone number |
voicemail | boolean | false | false | If true, voicemail is enabled for this phone number |
voicemail_outside_business_hours | boolean | false | false | If true, callers can leave voicemails outside of business hours |
voicemail_recording_delete_after | string | false | false | Length 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_enabled | boolean | false | false | If true, Talk agents have time after each call to finish adding details to the ticket |
wrap_up_time_limit | integer | false | false | Amount 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
Name | Type | In | Required | Description |
---|---|---|---|---|
include | string | Query | false | Parameter to include additional information. Allowed values are "settings", "ivrs", "all_greetings", "all_groups", or "all_schedules". |
phone_number_id | integer | Path | true | ID of a phone number |
Example body
{
"phone_number": {
"nickname": "Awesome Support Line"
}
}
Code Samples
curl
# Update a phone number's nickname
curl 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 transcription
curl "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 greeting
curl "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 setting
curl "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` setting
curl "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 requests
import json
from 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 authentication
auth = 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
Name | Type | In | Required | Description |
---|---|---|---|---|
phone_number_id | integer | Path | true | ID 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 requests
from 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 authentication
auth = 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