Phone numbers

JSON Format of Talk Phone Numbers

Talk 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 the phone number was created
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 the phone number. See Create Greetings in the Talk API docs and Managing outgoing greetings in the Talk Help Center
default_greeting_ids array yes no The names of default system greetings associated with the phone number. See Managing outgoing greetings in the Talk Help Center
categorised_greetings object yes no Greeting category ids and names. See Greeting Category JSON Format
categorised_greetings_with_sub_settings object yes no The id and any settings associated with each greeting category. If the category has no settings, defaults to the category name. See Managing outgoing greetings in the Talk Help Center
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"],
    "categorised_greetings": {
      "1":                  "voicemail_en",
      "2":                  "available_en",
      ...
    },
    "categorised_greetings_with_sub_settings": {
      "1": {
        "voicemail_on_outside_business_hours": "voicemail_en",
        "voicemail_off_inside_business_hours": "voicemail_en_voicemail_config",
        ...
      },
      "2": { ... },
      ...
    },
    "sms_group_id":         7,
    "capabilities": {
      "sms":                true,
      "mms":                false,
      "voice":              true,
    }
  }
}

JSON Format of Available Phone Numbers

Searching for available phone numbers returns numbers with the following properties:

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

Returns available phone numbers. See JSON Format of Available Phone Numbers.

This endpoint is not available for Trial accounts.

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

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

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.

Example request body:

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

This endpoint is not available for Trial accounts.

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 Number

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