Phone numbers

Phone Number JSON Format

Phone numbers have the following keys:

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

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
address_requirements	string	Type of address that must be supplied when purchasing the phone number (based on specific country regulations). Possible values: "none", "local", "any", foreign"

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	Mandatory	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