Phone numbers

This API lets you manage the phone numbers in your Zendesk voice account. See Managing Zendesk Talk lines in Zendesk help. You can also use it to search for available phone numbers.

JSON Format

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

Name	Type	Read-only	Mandatory	Description
brand_id	integer	false	false	ID of brand associated with the phone number
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 Zendesk help
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 Zendesk help
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 Zendesk help
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 line, either phone or digital
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
emergency_address	boolean	true	false	Whether the phone number can be associated with an emergency address

Example

{
  "brand_id": 1,
  "capabilities": {
    "emergency_address": false,
    "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": "[phone]",
  "external": false,
  "greeting_ids": [
    1,
    2
  ],
  "group_ids": [
    1,
    2
  ],
  "id": 6,
  "location": "TX",
  "name": "Awesome Support Line",
  "nickname": "Awesome Support Line",
  "number": "[phone]",
  "recorded": true,
  "sms_group_id": 7,
  "toll_free": false,
  "transcription": false
}

List Phone Numbers

• GET /api/v2/channels/voice/phone_numbers

This endpoint is not available for Trial accounts.

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

/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": {
        "emergency_address": true,
        "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": "[phone]",
      "external": false,
      "greeting_ids": [
        1,
        2
      ],
      "group_ids": [
        1,
        2
      ],
      "id": 6,
      "location": "TX",
      "name": "Awesome Support Line",
      "nickname": "Awesome Support Line",
      "number": "[phone]",
      "recorded": true,
      "sms_group_id": 7,
      "toll_free": false,
      "transcription": false
    }
  ],
  "previous_page": null
}

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":         "[phone]",
    "display_number": "[phone]",
    "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": "[phone]",
      "location": "MD",
      "nickname": null,
      "number": "[phone]",
      "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": {
    "brand_id": 1,
    "call_recording_consent": "always",
    "capabilities": {
      "emergency_address": false,
      "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": "[phone]",
    "external": false,
    "greeting_ids": [
      1,
      2
    ],
    "group_ids": [
      1,
      2
    ],
    "id": 6,
    "location": "TX",
    "name": "Awesome Support Line",
    "nickname": "Awesome Support Line",
    "number": "[phone]",
    "recorded": true,
    "sms_group_id": 7,
    "toll_free": false,
    "transcription": false
  }
}

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

Address and business verification requirements

Certain regional numbers require a valid address and/or business verification in that region before the number can be created. For more information, see Zendesk Talk and Zendesk Text number address requirements in Zendesk help.

Number needs valid address You can create a phone number that needs an address by getting the address' provider_reference using the List Addresses endpoint and adding it to the body as address_sid. Example:

{
  "phone_number": {
    "token": "24a407cef67213be6d26b4c02d7d86c0"
  },
  "address_sid": "ADXXXXXXXXXXXXXX"
}

Number needs business verification The endpoint does not currently support creating a phone number that requires a valid verified business.

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": {
    "brand_id": 1,
    "call_recording_consent": "always",
    "capabilities": {
      "emergency_address": false,
      "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": "[phone]",
    "external": false,
    "greeting_ids": [
      1,
      2
    ],
    "group_ids": [
      1,
      2
    ],
    "id": 6,
    "location": "TX",
    "name": "Awesome Support Line",
    "nickname": "Awesome Support Line",
    "number": "[phone]",
    "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": {
    "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": {
    "brand_id": 1,
    "call_recording_consent": "always",
    "capabilities": {
      "emergency_address": false,
      "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": "[phone]",
    "external": false,
    "greeting_ids": [
      1,
      2
    ],
    "group_ids": [
      1,
      2
    ],
    "id": 6,
    "location": "TX",
    "name": "Awesome Support Line",
    "nickname": "Awesome Support Line",
    "number": "[phone]",
    "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