Phone numbers

Phone Number JSON Format

Phone numbers have the following keys:

Name	Type	Comment
id	integer	Automatically assigned upon creation
number	string	The phone number digits
display_number	string	The formatted phone number
external	boolean	If external caller id number
name	string	The nickname if one is set, otherwise the display_number
nickname	string	The nickname of the number if one is set
toll_free	boolean	Whether the number is toll-free or local
location	string	Geographical location of the number (e.g. CA or Leeds)
country_code	string	The ISO code of the country for this number
created_at	date	The date and time of the phone number creation
transcription	boolean	Whether calls for the number are transcribed or not
recorded	boolean	Whether calls for the number are recorded or not
group_ids	array	Array of associated groups
default_group_id	integer	Default group id
greeting_ids	array	Custom greetings associated with this phone number
default_greeting_ids	array	Default greetings associated with this phone number
sms_group_id	integer	Group associated with this phone number
capabilities.sms	boolean	Whether phone number has sms capability
capabilities.mms	boolean	Whether phone number has mms capability
capabilities.voice	boolean	Whether phone number has voice capability

Example

{
  "phone_number":{
    "id":                   6,
    "number":               "+353766801402",
    "display_number":       "+353 76 680 1402",
    "name":                 "Awesome Support Line",
    "nickname":             "Awesome Support Line",
    "toll_free":            false,
    "location":             "TX",
    "country_code":         "US",
    "created_at":           "2013-04-13T16:02:33Z",
    "transcription":        false,
    "recorded":             true,
    "group_ids":            [1, 2],
    "default_group_id":     1,
    "greeting_ids":         [1, 2],
    "default_greeting_ids": ["voicemail_en", "available_jp"],
    "sms_group_id":         7,
    "capabilities": {
      "sms":               true,
      "mms":               false,
      "voice":             true,
    }
  }
}

Phone Number JSON Format (search)

When searching, phone numbers with the following keys are returned:

Name	Type	Comment
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	Geographical location of the number (e.g. 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	Monthly cost of this phone number

Example

{
  "phone_number":{
    "number":         "+353766801402",
    "display_number": "+353 76 680 1402",
    "toll_free":      false,
    "location":       "TX",
    "country_id":     72,
    "token":          "24a407cef67213be6d26b4c02d7d86c0",
    "price":          "$1.0"
  }
}

Search for Available Phone Numbers

GET /api/v2/channels/voice/phone_numbers/search.json

Available parameters

Name	Type	Required	Comments
country	string	yes	The ISO country code
toll_free	boolean	no	Whether the number should be toll-free or local
area_code	string	no	Find phone numbers in the specified area code. (US and Canada only)
contains	string	no	The regular expression used to search for phone numbers. Valid characters are '' and [0-9a-zA-Z]. The '' character will match any single digit

A few 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

Allowed For

Agents

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

{
  "phone_numbers": [
    {
      "number": "+12403123885",
      "token":  "24a407cef67213be6d26b4c02d7d86c0",
      ...
    },
    {
      "number": "+12403983855",
      "token":  "bfe1efbcf800249c3d8f620be42daaae",
      ...
    }
  ]
}

List Phone Numbers

GET /api/v2/channels/voice/phone_numbers.json

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.

/api/v2/channels/voice/phone_numbers.json?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

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers.json \
  -v -u {email_address}:{password}

Example Response

Status: 200 OK

{
  "phone_numbers": [
    {
      "id":   1,
      "number":"+13525475960"
      ...
    },
    {
      "id":   2,
      "number":"+353766801905"
      ...
    },
  ]
}

Create Phone Numbers

POST /api/v2/channels/voice/phone_numbers.json

Allowed For

Agents

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: 201 Created

{
  "phone_number":{
    "id":     1,
    "number": "+16674015276",
    ...
  }
}

Update Phone Numbers

PUT /api/v2/channels/voice/phone_numbers/{id}.json

Allowed For

Agents

Example Request

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

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers/{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":{
    "id":     1,
    "number": "+353766801402",
    "name":   "Awesome Support Line",
    ...
  }
}

Show Phone Number

GET /api/v2/channels/voice/phone_numbers/{id}.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers/{id}.json \
  -v -u {email_address}:{password}

Example Response

Status: 200 OK

{
  "phone_number":{
    "id":     7,
    "number": "+13525475960",
    ...
  }
}

Delete Phone Number

DELETE /api/v2/channels/voice/phone_numbers.json

Allowed For

Agents

Using curl

curl https://{subdomain}.zendesk.com/api/v2/channels/voice/phone_numbers/{id}.json \
  -H "Content-Type: application/json" -X DELETE -v -u {email_address}:{password}

Example Response

Status: 200 OK