Talk API

Phone numbers

JSON Format

Phone numbers are represented as JSON objects with the following properties:

Name Type Read-only Mandatory Description
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
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
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
recorded boolean false false Whether calls for the number are recorded or not
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
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
  • 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?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
  • Agents

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

{
  "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
  • 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
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
  • Agents
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
  • Agents
Parameters
Name Type In Required Description
phone_number_id integer Path true ID of a phone number
Example Body
 
{
  "phone_number": {
    "name": "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
  • Agents
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