Phone numbers
JSON Format
Phone numbers are represented as JSON objects with the following properties:
Name |
Type |
Read-only |
Mandatory |
Description |
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 the Talk Help Center |
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 the Talk Help Center |
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 the Talk Help Center |
group_ids |
array |
false |
false |
An array of associated groups. *Writeable on most of plans. |
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 of line associated with the phone number |
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 |
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 calls for the number are transcribed or not |
voice_enabled |
boolean |
false |
false |
Whether or not the phone number has voice 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 |
Example
{
"capabilities": {
"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
}
List Phone Numbers
GET /api/v2/channels/voice/phone_numbers
Allowed For
Minimizing the results
You can reduce the number of properties per phone number in the response with the minimal_mode=true
query string parameter.
/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 |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"count": 1,
"next_page": null,
"phone_numbers": [
{
"capabilities": {
"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
}
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
This endpoint is not available for Trial accounts.
Example Body
{
"phone_number": {
"token": "24a407cef67213be6d26b4c02d7d86c0"
}
}
Using 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}:{password}
Example Response
Status 200 OK
{
"phone_number": {
"capabilities": {
"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
}
}
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
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 |
Using 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}:{password}
Example Response
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}
Allowed For
Parameters
Name |
Type |
In |
Required |
Description |
phone_number_id |
integer |
Path |
true |
ID of a phone number |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers/{phone_number_id}.json \
-v -u {email_address}:{password}
Example Response
Status 200 OK
{
"phone_number": {
"capabilities": {
"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
}
}
Update Phone Number
PUT /api/v2/channels/voice/phone_numbers/{phone_number_id}
Allowed For
Parameters
Name |
Type |
In |
Required |
Description |
phone_number_id |
integer |
Path |
true |
ID of a phone number |
Example Body
{
"phone_number": {
"nickname": "Awesome Support Line"
}
}
Using curl
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}:{password} -X PUT
Example Response
Status 200 OK
{
"phone_number": {
"capabilities": {
"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
}
}
Delete Phone Number
DELETE /api/v2/channels/voice/phone_numbers/{phone_number_id}
Allowed For
Parameters
Name |
Type |
In |
Required |
Description |
phone_number_id |
integer |
Path |
true |
ID of a phone number |
Using 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}:{password}
Example Response
Status 200 OK