API Resource: /extensions

Want to get straight to work? Jump to available methods: POST /extensions | GET /extensions | DELETE /extensions | GET /extensions/UUID | PUT /extensions/UUID | DELETE /extensions/UUID


With Phone.com, you can add as many extensions to each phone number as you need. Extensions are endpoints or destinations associated with a phone number that allow you to send calls or SMS messages to cell phones, home and work phones.

Each extension can have its own Address Book and voicemail box, can be linked to a specific greeting, and offers custom delivery of voice messages to your phone (audio or text message) or email.

What Can I Do with Extensions?

The Phone.com API /extensions service offers access to all of your Phone.com extensions, allowing you to add, retrieve, update and delete them. Once integrated with your web and mobile applications, you can then use extensions to route calls and SMS messages, assign greetings and hold music, and much more!

Extensions Settings in Your Account

Typically, you would create and manage extensions by logging into your Phone.com API Developer account and clicking Configure and Manage Users and Extensions. You can add an extension to a specific phone number, then set up voicemail, greetings and Address Books for that extension.

Working with the /extensions API Resource

In other cases, however, you may need to create and manage extensions more dynamically. Using the /extensions API service, you can give your end users the ability to update their extensions on the fly. You can also let them add or delete extensions as needed.

This topic outlines the methods available for /extensions, and shows you how to build effective requests for this service. From your app, you can add a new extension using a POST to /extensions. Once that extension exists, you can update, list or delete it using the PUT, GET and DELETE methods respectively.

Note that for this release, the Phone.com API supports only virtual extension types, which allow you to route calls to your Phone.com number to a cell phone, home phone or work phone.

POST /extensions

Use POST /extensions to create a new extension on a number in your Phone.com account.

Example

POST https://v1.api.phone.com/extensions

Authentication

This method requires authentication.

Request Body Fields and Example

Parameter Type Description
extension_number Integer Number you want to assign to the extension (0 through 9)
alternate_greeting String Resource ID of a valid greeting object
call_handling String Resource ID of a valid route object
call_notification_status Boolean Setting to turn the call notification feature on or off
call_notify_email Boolean Setting to turn the call notification email feature on or off
call_notify_email_address String Email addresses to receive call notifications, separated by commas
call_notify_mobile Boolean Setting to turn call notifications by SMS on or off
call_sms_did String Formatted phone number where call notifications will be sent by SMS (E.164 format)
caller_id String Caller ID to use for outbound phone calls. Specify either private or the formatted phone number (E.164 format).
extension_name String Name (nickname) for the extension
extension_type String Extension type. Currently the API supports virtual.
extension_unlimited Boolean Setting to turn unlimited calling on that extension on or off
include_in_dial_by_name_dir Boolean Setting to add the extension to the dial-by-name directory or not. Set to Y to include the extension in the directory.
leave_message_prompt Boolean Setting to turn the ability to leave a message after the greeting on or off
local_area_code Integer Three-digit area code for outbound calls from the extension
owner_name String Name of the person using the extension
recorded_name String Recorded name of that person in the form of a greeting object, comprised of a resource ID
standard_greeting String Greeting object, comprised of a resource ID
time_zone String Time zone assigned to the extension. Note: Time zone must be specified exactly as in Supported Time Zones.
voicemail_attach Boolean Setting for turning the attachment of voicemail files to email notifications on or off
voicemail_attachment_type String Attachment type, wav or mp3
voicemail_greeting String Greeting type, standard, alternate or name
voicemail_notify_email Boolean Setting for turning the sending of a voicemail notification by email on or off
voicemail_notify_email_address String Email address to send voicemail notifications
voicemail_password Integers Sets the password for voicemail for the extension, numbers 0-9
voicemail_notify_mobile Boolean Setting for turning the sending of voicemail notifications via SMS on or off
voicemail_sms_did String Formatted phone number to which voicemail notifications are sent by SMS (E.164 format)
voicemail_status Boolean Setting for turning the voicemail feature on or off on the extension
voicemail_transcription Boolean Setting for turning the voicemail transcription service feature on or off on the extension
voicemail_transcription_type String Set voicemail transcription service type, either human or automated

Request Body Format Example

The example below shows how you can add (POST) an extension for a phone number in your account.


{
    "extension_type": "virtual",
    "extension_name": "<extension name>",
    "extension_number": 511,
    "owner_name": "<owner name>",
    "recorded_name": "aee74dfc-b458-11e3-b0ae-f7d513157581",
    "time_zone": "Pacific",
    "include_in_dial_by_name_dir": "Y",
    "caller_id": "+15555551234",
    "local_area_code": <area code>,
    "voicemail_status": "Y",
    "voicemail_notify_email": "Y",
    "voicemail_notify_email_address": "<email address>",
    "voicemail_notify_mobile": "N",
    "voicemail_sms_did": "+15555552345",
    "voicemail_greeting": "standard",
    "standard_greeting": "aee74dfc-b458-11e3-b0ae-f7d513157581",
    "alternate_greeting": "aee74dfc-b458-11e3-b0ae-f7d513157575",
    "leave_message_prompt": "Y",
    "voicemail_password": <password>,
    "voicemail_transcription": "Y",
    "voicemail_transcription_type": "automated",
    "call_notification_status": "Y",
    "call_notify_email": "Y",
    "call_notify_email_address": "<email address>",
    "call_notify_mobile": "Y",
    "call_sms_did": "+15555553456",
    "call_handling": "aee75dfc-b428-11e7-b0ae-f9d513157581",
    "extension_unlimited": "Y"
}

 

Success Response

HTTP Code: 200 OK


{
    "response": {
        "data": {
            "resource_id": "1b323609-14ba-11e3-8a95-c8d05d0d06fa"
        }
    }
}


Error Response

  • HTTP Code: 409 Conflict (Name in use)
  • HTTP Code: 404 Not Found (Dependent resource not found)
  • HTTP Code: 500 Internal Server Error

For HTTP Code 404:

{
    "response": {
        "error": {
            "code": 30000,
            "info": "The system could not locate the resource you requested.",
            "url": "https://docs.phone.com/refguides/errorref/serviceerrors.html#error-code-30000"
        }
    }
}


Sample POST /extensions Request (PHP)


  <?php
  $url = "https://v1.api.phone.com/extensions";

  $post_body = <<<MENUDATA
  {
      "extension_type": "virtual",
      "extension_name": "Tom Extension",
      "extension_number": 501,
      "owner_name": "Tom Jones",
      "time_zone": "Pacific",
      "include_in_dial_by_name_dir": "Y",
      "caller_id": "+15555551234",
      "local_area_code": 858,
      "voicemail_status": "Y",
      "voicemail_notify_email": "Y",
      "voicemail_notify_email_address": "tom@phone.com",
      "voicemail_notify_mobile": "N",
      "voicemail_sms_did": "+15555552345",
      "voicemail_greeting": "standard",
      "standard_greeting": "aee74dfc-b458-11e3-b0ae-f7d513157581",
      "leave_message_prompt": "Y",
      "voicemail_password": 123456,
      "voicemail_transcription": "Y",
      "voicemail_transcription_type": "automated",
      "call_notification_status": "Y",
      "call_notify_email": "Y",
      "call_notify_email_address": "tom@outlook.com",
      "call_notify_mobile": "Y",
      "call_sms_did": "+155555553456",
      "call_handling": "aee75dfc-b428-11e7-b0ae-f9d513157581",
      "extension_unlimited": "N"
    }
    MENUDATA;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    // authentication
    curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
    curl_setopt($ch, CURLOPT_USERPWD, "username:password");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_body);
    curl_setopt($ch, CURLOPT_HEADER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER,
             array('Content-Type:application/json',
                 'Content-Length: ' . strlen($post_body))
             );
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

    $result = curl_exec($ch);

    $info = curl_getinfo($ch);
    curl_close($ch);

    if($info['http_code'] == 200 || $info['http_code'] == 201) {
             echo $result;
    } else {
             $error = array('http_code' => $info['http_code'], 'response' => $result);
             echo json_encode($error);
    }
  ?>

Back to Methods Available for /extensions.


GET /extensions

Use GET /extensions to retrieve a list of existing extensions in your Phone.com account. Note that, by default, you can retrieve a maximum of 20 extensions per request. You can increase the number of returned objects to a maximum of up to 50 by setting the limit parameter, and you can set offset to page through all available objects.

Example

GET https://v1.api.phone.com/extensions

Authentication

This method requires authentication.

Parameters

Parameter Type Description
limit (Optional) Integer Limits the result set to the value provided, to a maximum of 50 extensions. If you do not specify a limit, GET requests have a default maximum of 20 objects returned.
offset (Optional) Integer Determines the number of rows to skip before returning rows for the request
order_by (Optional) String The field by which you want to order results
name (Optional) String Allows you to retrieve extensions by name

Success Response

HTTP Code: 200 OK

Response Body Fields and Example

Parameter Type Description
resource_id String Resource ID for the extension
extension_number Integer Extension number
alternate_greeting Object Greeting object, comprised of a resource ID and a URL
Visual spacer resource_id String Resource ID for a valid greeting object
Visual spacer url String URL that points to the resource ID for the alternate greeting
call_handling Object Route object, comprised of a resource ID and a URL
Visual spacer resource_id String Resource ID for a valid route object
Visual spacer url String URL that points to the resource ID for the route
call_notification_status Boolean Setting to turn the call notification feature on or off
call_notify_email Boolean Setting to turn the notification email feature on or off
call_notify_email_address String Email addresses to receive call notifications, separated by commas
call_notify_mobile Boolean Setting to turn the call notification SMS feature on or off
call_sms_did String Formatted phone number where call notification will be sent by SMS (E.164 format)
caller_id String Caller ID to use for outbound phone calls. Specify either private or the formatted phone number (E.164 format).
conference_id String ID number given to participants to join the conference
extension_name String Name (nickname) for the extension
extension_type String Extension type. Currently the API supports virtual.
extension_unlimited Boolean Setting to turn on unlimited calling on that extension
include_in_dial_by_name_dir Boolean Setting to add the extension to the dial-by-name directory or not. Set to Y to include the extension in the directory.
leave_message_prompt Boolean Setting to turn the ability to leave a message after the greeting on or off
local_area_code Integer Three-digit area code for outbound calls from the extension
moderator_pin String Number use by moderator to control conference features
owner_name String Name of the person using the extension
recorded_name Object Recorded name of that person in the form of a greeting object, comprised of a resource ID
Visual spacer resource_id String Resource ID for a valid greeting object
Visual spacer url String URL that points to the resource ID for the greeting
standard_greeting Object Greeting object, comprised of a resource ID
Visual spacer resource_id String Resource ID for a valid greeting object
Visual spacer url String URL that points to the resource ID for the greeting
time_zone String Time zone assigned to the extension. Note: Time zone must be specified exactly as in Supported Time Zones.
voicemail_attach Boolean Setting for turning the attachment of voicemail files to email notifications on or off
voicemail_attachment_type String Attachment type, wav or mp3
voicemail_greeting String Greeting type, standard, alternate or name
voicemail_notify_email Boolean Setting for turning the sending of a voicemail notification by email on or off
voicemail_notify_email_address String Email address to send voicemail notifications
voicemail_password Integer Sets the password for voicemail for the extension
voicemail_notify_mobile Boolean Setting for turning the sending of voicemail notifications via sms on or off
voicemail_sms_did String Formatted phone number to which voicemail notifications are sent by SMS (E.164 format)
voicemail_status Boolean Setting for turning the voicemail feature on or off on the extension
voicemail_transcription Boolean Setting for turning the voicemail transcription service feature on or off on the extension
voicemail_transcription_type String Set voicemail transcription service type, either human or automated

Response Body Format Example


  {
     "response" : {
        "data" : [
           {
              "resource_id" : "46f3d499-5bae-11e3-acef-e9bfb76f4bce",
              "alternate_greeting" : {
                 "resource_id" : "42def790-b458-11e3-a687-b35c69a63ebe",
                 "url" : "http://v1.api.phone.com/media/42def790-b458-11e3-a687-b35c69a63ebe"
              },
              "call_handling" : {
                 "resource_id" : "42def780-b428-11e3-a687-b22c69a63ebe",
                 "url" : "http://v1.api.phone.com/routes/42def780-b428-11e3-a687-b22c69a63eb"
              },
              "call_notification_status" : "Y",
              "call_notify_email" : "Y",
              "call_notify_email_address" : "helen@outlook.com",
              "call_notify_mobile" : "Y",
              "call_sms_did" : "+15555551234",
              "caller_id" : "private",
              "conference_id" : "456321",
              "extension_name" : "Helen",
              "extension_number" : "501",
              "extension_type" : "virtual",
              "extension_unlimited" : "Y",
              "inclde_in_dial_by_name_dir" : "Y",
              "leave_message_prompt" : "N",
              "local_area_code" : 123,
              "moderator_pin" : "123456",
              "owner_name" : "Helen Smith",
              "recorded_name" : {},
              "standard_greeting" : {
                 "resource_id" : "aee74dfc-b458-11e3-b0ae-f7d513157581",
                 "url" : "http://v1.api.phone.com/media/aee74dfc-b458-11e3-b0ae-f7d513157581"
              },
              "time_zone" : "America/Los_Angeles",
              "voicemail_attach" : "Y",
              "voicemail_attachment_type" : "mp3",
              "voicemail_greeting" : "standard",
              "voicemail_notify_email" : "Y",
              "voicemail_notify_email_address" : "helen@yourcompany.com",
              "voicemail_notify_mobile" : "Y",
              "voicemail_password" : "601445",
              "voicemail_sms_did" : "+18583217654",
              "voicemail_status" : "Y",
              "voicemail_transcription" : "N"
           },
           {
              "resource_id" : "623380f5-402a-11e3-a05b-b0a4ae1812b5",
              "alternate_greeting" : {},
              "call_handling" : {},
              "call_notification_status" : "N",
              "caller_id" : "+18581234567",
              "extension_name" : "Tom",
              "extension_number" : "500",
              "extension_type" : "virtual",
              "extension_unlimited" : "Y",
              "inclde_in_dial_by_name_dir" : "Y",
              "leave_message_prompt" : "Y",
              "local_area_code" : 858,
              "owner_name" : "Tom Smith",
              "recorded_name" : {},
              "standard_greeting" : {
                 "resource_id" : "42def790-b458-11e3-a687-b35c69a63ebe",
                 "url" : "http://v1.api.phone.com/media/42def790-b458-11e3-a687-b35c69a63ebe"
              },
              "time_zone" : "America/Los_Angeles",
              "voicemail_attach" : "Y",
              "voicemail_attachment_type" : "mp3",
              "voicemail_greeting" : "standard",
              "voicemail_notify_email" : "Y",
              "voicemail_notify_email_address" : "tom@yourcompany.com",
              "voicemail_notify_mobile" : "Y",
              "voicemail_password" : "301256",
              "voicemail_sms_did" : "+15748889999",
              "voicemail_status" : "Y",
              "voicemail_transcription" : "Y",
              "voicemail_transcription_type" : "automated"
           }
        ]
     }
  }

  

Error Response

  • HTTP Code: 404 Not Found (Dependent resource not found)

Sample GET /extensions Request (PHP)


<?php
$url = "https://v1.api.phone.com/extensions/?limit=5&offset=0";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
// authentication
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");

curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

$info = curl_getinfo($ch);
curl_close($ch);

if($info['http_code'] == 200) {
  echo $result;
} else {
  $error = array('http_code' => $info['http_code'], 'response' => $result);
  echo json_encode($error);
}
?>


Back to Methods Available for /extensions.


DELETE /extensions

Use DELETE /extensions to remove all extensions in your account. Note that you must include delete_all to prevent you from deleting all of your extensions by accident! Also, extensions being used by another object cannot be deleted.

Example

DELETE https://v1.api.phone.com/extensions?delete_all=1

Authentication

This method requires authentication.

Parameters

Parameter Type Description
delete_all Boolean Set to 1 to delete all extensions

Success Response

HTTP Code: 200 OK


{
    "response": {
        "data": "1"
    }
}


Error Response

  • HTTP Code: 400 Invalid Request
  • HTTP Code: 404 Not Found (Dependent resource not found)
  • HTTP Code: 409 Conflict (Name in Use)

For HTTP Code 400

{
    "response": {
        "error": {
            "code": 30007,
            "info": "You cannot delete all without the delete_all argument.",
            "url": "https://docs.phone.com/refguides/errorref/serviceerrors.html#error-code-30007"
        }
    }
}


Sample DELETE /extensions Request (PHP)

Note that you must supply the delete_all argument to prevent you from deleting all of your extensions by accident. Also, extensions being used by another object cannot be deleted.


<?php
$url = "https://v1.api.phone.com/extensions?delete_all=1";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
// authentication
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

$info = curl_getinfo($ch);
curl_close($ch);

if($info['http_code'] == 200) {
        echo $result;
} else {
        $error = array('http_code' => $info['http_code'], 'response' => $result);
        echo json_encode($error);
}
?>


Back to Methods Available for /extensions.


GET /extensions/UUID

Use GET /extensions/UUID to retrieve information about a single extension.

Example

GET https://v1.api.phone.com/extensions/UUID

Authentication

This method requires authentication.

Success Response

HTTP Code: 200 OK

Response Body Fields and Example

Parameter Type Description
resource_id String Resource ID for the extension
extension_number Integer Extension number
alternate_greeting Object Greeting object, comprised of a resource ID and a URL
Visual spacer resource_id String Resource ID for a valid greeting object
Visual spacer url String URL that points to the resource ID for the alternate greeting
call_handling Object Route object, comprised of a resource ID and a URL
Visual spacer resource_id String Resource ID for a valid route object
Visual spacer url String URL that points to the resource ID for the route
call_notification_status Boolean Setting to turn the call notification feature on or off
call_notify_email Boolean Setting to turn the notification email feature on or off
call_notify_email_address String Email addresses to receive call notifications, separated by commas
call_notify_mobile Boolean Setting to turn the call notification SMS feature on or off
call_sms_did String Formatted phone number where call notifications will be sent by SMS (E.164 format)
caller_id String Caller ID to use for outbound phone calls. Specify either private or the formatted phone number (E.164 format).
conference_id String ID number given to participants to join the conference
extension_name String Name (nickname) for the extension
extension_type String Extension type. Currently the API supports virtual.
extension_unlimited Boolean Feature to turn on unlimited calling on that extension
include_in_dial_by_name_dir Boolean Setting to add the extension to the dial-by-name directory or not. Set to Y to include the extension in the directory.
leave_message_prompt Boolean Setting to turn the ability to leave a message after the greeting on or off
local_area_code Integer Three-digit area code for outbound calls from the extension
moderator_pin String Number use by moderator to control conference features
owner_name String Name of the person using the extension
recorded_name Object Recorded name of that person in the form of a greeting object, comprised of a resource ID
Visual spacer resource_id String Resource ID for a valid greeting object
Visual spacer url String URL that points to the resource ID for the greeting
standard_greeting Object Greeting object, comprised of a resource ID
Visual spacer resource_id String Resource ID for a valid greeting object
Visual spacer url String URL that points to the resource ID for the greeting
time_zone String Time zone assigned to the extension. Note: Time zone must be specified exactly as in Supported Time Zones.
voicemail_attach Boolean Setting for turning the attachment of voicemail files to email notifications on or off
voicemail_attachment_type String Attachment type, wav or mp3
voicemail_greeting String Greeting type, standard, alternate or name
voicemail_notify_email Boolean Setting for turning the sending of a voicemail notification by email on or off
voicemail_notify_email String Email address to send voicemail notifications
voicemail_password Integer Sets the password for voicemail for the extension
voicemail_notify_mobile Boolean Setting for turning the sending of voicemail notifications via sms on or off
voicemail_sms_did String Formatted phone number to which voicemail notifications are sent by SMS (E.164 format)
voicemail_status Boolean Setting for turning the voicemail feature on or off on the extension
voicemail_transcription Boolean Setting for turning the voicemail transcription service feature on or off on the extension
voicemail_transcription_type String Set voicemail transcription service type, either human or automated

Response Body Format Example



 {
    "response" : {
       "data" : [
          {
             "resource_id" : "46f3d499-5bae-11e3-acef-e9bfb76f4bce",
             "alternate_greeting" : {
                "resource_id" : "42def790-b458-11e3-a687-b35c69a63ebe",
                "url" : "http://v1.api.phone.com/media/42def790-b458-11e3-a687-b35c69a63ebe"
             },
              "call_handling" : {
                 "resource_id" : "42def780-b428-11e3-a687-b22c69a63ebe",
                 "url" : "http://v1.api.phone.com/routes/42def780-b428-11e3-a687-b22c69a63eb"
              },
             "call_notification_status" : "N",
             "caller_id" : "private",
             "conference_id" : "456321",
             "extension_name" : "Helen",
             "extension_number" : "501",
             "extension_type" : "virtual",
             "extension_unlimited" : "Y",
             "inclde_in_dial_by_name_dir" : "Y",
             "leave_message_prompt" : "N",
             "local_area_code" : 123,
             "moderator_pin" : "123456",
             "owner_name" : "Helen Smith",
             "recorded_name" : {},
             "standard_greeting" : {
                "resource_id" : "aee74dfc-b458-11e3-b0ae-f7d513157581",
                "url" : "http://v1.api.phone.com/media/aee74dfc-b458-11e3-b0ae-f7d513157581"
             },
             "time_zone" : "America/Los_Angeles",
             "voicemail_attach" : "Y",
             "voicemail_attachment_type" : "mp3",
             "voicemail_greeting" : "standard",
             "voicemail_notify_email" : "Y",
             "voicemail_notify_email_address" : "helen@yourcompany.com",
             "voicemail_notify_mobile" : "Y",
             "voicemail_password" : "601445",
             "voicemail_sms_did" : "+18583217654",
             "voicemail_status" : "Y",
             "voicemail_transcription" : "N"
          }
 }


Error Response

  • HTTP Code: 404 Not Found (Dependent resource not found)

Sample GET /extensions/UUID Request (PHP)


<?php
$url = "https://v1.api.phone.com/extensions/46f3d499-5bae-11e3-acef-e9bfb76f4bce";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
// authentication
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");

curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

$info = curl_getinfo($ch);
curl_close($ch);

if($info['http_code'] == 200) {
  echo $result;
} else {
  $error = array('http_code' => $info['http_code'], 'response' => $result);
  echo json_encode($error);
}
?>


Back to Methods Available for /extensions.


PUT /extensions/UUID

Use PUT /extensions/UUID to update specific extensions.

Note that a PUT is not a PATCH. You need to send the complete object in the HTTP request body in order to update it. Also, you can change the name of an extensions using PUT to /extensions/UUID. However, you cannot change the name to a name already used by another extension.

Example

PUT https://v1.api.phone.com/extensions/UUID

Authentication

This method requires authentication.

Request Body Fields and Example

Parameter Type Description
extension_number Integer Number you want to assign to the extension (0 through 9)
alternate_greeting String Resource ID of a valid greeting object
call_handling String Resource ID of a valid route object
call_notification_status Boolean Setting to turn the call notification feature on or off
call_notify_email Boolean Setting to turn the call notification email feature on or off
call_notify_email_address String Email addresses to receive call notification, separated by commas
call_notify_mobile Boolean Setting to turn call notifications by SMS on or off
call_sms_did String Formatted phone number where call notification will be sent by SMS (E.164 format)
caller_id String Caller ID to use for outbound phone calls. Specify either private or the formatted phone number (E.164 format).
extension_name String Name of the extension
extension_type String Extension type. Currently the API supports virtual.
extension_unlimited Boolean Setting to turn unlimited calling on that extension on or off
include_in_dial_by_name_dir Boolean Setting to add the extension to the dial-by-name directory or not. Set to Y to include the extension in the directory.
leave_message_prompt Boolean Setting to turn the ability to leave a message after the greeting on or off
local_area_code Integer Three-digit area code for outbound calls from the extension
owner_name String Name of the person using the extension
recorded_name String Recorded name of that person in the form of a greeting object, comprised of a resource ID
standard_greeting String Greeting object, comprised of a resource ID
time_zone String Time zone assigned to the extension. Note: Time zone must be specified exactly as in Supported Time Zones.
voicemail_attach Boolean Setting for turning the attachment of voicemail files to email notifications on or off
voicemail_attachment_type String Attachment type, wav or mp3
voicemail_greeting String Greeting type, standard, alternate or name
voicemail_notify_email Boolean Setting for turning the sending of a voicemail notification by email on or off
voicemail_notify_email_address String Email address to send voicemail notifications
voicemail_password Integers Sets the password for voicemail for the extension, numbers 0-9
voicemail_notify_mobile Boolean Setting for turning the sending of voicemail notifications via SMS on or off
voicemail_sms_did String Formatted phone number to which voicemail notifications are sent by SMS (E.164 format)
voicemail_status Boolean Setting for turning the voicemail feature on or off on the extension
voicemail_transcription Boolean Setting for turning the voicemail transcription service feature on or off
voicemail_transcription_type String Set voicemail transcription service type, either human or automated

Request Body Format Example


{
    "extension_type": "virtual",
    "extension_name": "<extension name>",
    "extension_number": 511,
    "owner_name": "<owner name>",
    "recorded_name": "aee74dfc-b458-11e3-b0ae-f7d513157581",
    "time_zone": "Pacific",
    "include_in_dial_by_name_dir": "Y",
    "caller_id": "+15555551234",
    "local_area_code": <area code>,
    "voicemail_status": "Y",
    "voicemail_notify_email": "Y",
    "voicemail_notify_email_address": "<email address>",
    "voicemail_notify_mobile": "N",
    "voicemail_sms_did": "+15555552345",
    "voicemail_greeting": "standard",
    "standard_greeting": "aee74dfc-b458-11e3-b0ae-f7d513157581",
    "alternate_greeting": "aee74dfc-b458-11e3-b0ae-f7d513157581",
    "leave_message_prompt": "Y",
    "voicemail_password": <password>,
    "voicemail_transcription": "Y",
    "voicemail_transcription_type": "automated",
    "call_notification_status": "Y",
    "call_notify_email": "Y",
    "call_notify_email_address": "<email address>",
    "call_notify_mobile": "Y",
    "call_sms_did": "+15555553456",
    "extension_unlimited": "Y"
}


Success Response

HTTP Code: 200 OK


{
    "response": {
        "data": {
            "resource_id": "1b323609-14ba-11e3-8a95-c8d05d0d06fa"
        }
    }
}


Error Response

  • HTTP Code: 404 Not Found (Dependent resource not found)
  • HTTP Code: 409 Conflict (Name in Use)
  • HTTP Code: 500 Internal Server Error


For HTTP Code 404

{
    "response": {
        "error": {
            "code": 30000,
            "info": "The system could not locate the resource you requested.",
            "url": "https://docs.phone.com/refguides/errorref/serviceerrors.html#error-code-30000"
        }
    }
}


Sample PUT /extensions Request (PHP)


<?php
$url = "https://v1.api.phone.com/extensions/5c16ed38-ad21-11e2-b67b-a1bd4e9063de";

$put_body = <<<MENUDATA
{
    "extension_type": "virtual",
    "extension_name": "Tom Extension",
    "extension_number": 501,
    "owner_name": "Tom Jones",
    "time_zone": "Pacific",
    "include_in_dial_by_name_dir": "Y",
    "caller_id": "+15555551234",
    "local_area_code": 555,
    "voicemail_status": "Y",
    "voicemail_notify_email": "Y",
    "voicemail_notify_email_address": "tom@yourcompany.com",
    "voicemail_notify_mobile": "N",
    "voicemail_sms_did": "+15555552345",
    "voicemail_greeting": "standard",
    "standard_greeting": "aee74dfc-b458-11e3-b0ae-f7d513157581",
    "leave_message_prompt": "Y",
    "voicemail_password": 123456,
    "voicemail_transcription": "Y",
    "voicemail_transcription_type": "automated",
    "call_notification_status": "Y",
    "call_notify_email": "Y",
    "call_notify_email_address": "tom@outlook.com",
    "call_notify_mobile": "Y",
    "call_sms_did": "+15555553456",
    "extension_unlimited": "N"
}
MENUDATA;

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
// authentication
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, $put_body);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER,
       array('Content-Type:application/json',
          'Content-Length: ' . strlen($put_body))
       );
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

$info = curl_getinfo($ch);
curl_close($ch);

if($info['http_code'] == 200 || $info['http_code'] == 201) {
        echo $result;
} else {
        $error = array('http_code' => $info['http_code'], 'response' => $result);
        echo json_encode($error);
}

?>


Back to Methods Available for /extensions.


DELETE /extensions/UUID

Use DELETE /extensions/UUID to delete a specific extensions.

Example

DELETE https://v1.api.phone.com/extension/UUID

Authentication

This method requires authentication.

Success Response

HTTP Code: 200 OK


{
    "response": {
        "data": "1"
    }
}


Error Response

  • HTTP Code: 400 Invalid Request
  • HTTP Code: 404 Not Found (Dependent Resource Not Found)
  • HTTP Code: 409 Conflict (Name in Use)

For HTTP Code 409

{
    "response": {
        "error": {
            "code": 30005,
            "detail_0": "resource: 7c90a683-14c6-11e3-ac5d-a21bb51951d7, is in use and cannot be deleted.",
            "info": "Invalid request. The resource is in use.",
            "url": "https://docs.phone.com/refguides/errorref/serviceerrors.html#error-code-30005"
        }
    }
}


Sample DELETE /extensions/UUID Request (PHP)

An extension that is currently in use by another object cannot be deleted until that reference is removed.


<?php
$url = "https://v1.api.phone.com/extensions/5c16ed38-ad21-11e2-b67b-a1bd4e9063de";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
// authentication
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, "username:password");

curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$result = curl_exec($ch);

$info = curl_getinfo($ch);
curl_close($ch);

if($info['http_code'] == 200) {
  echo $result;
} else {
  $error = array('http_code' => $info['http_code'], 'response' => $result);
  echo json_encode($error);
}
?>


Back to Methods Available for /extensions.


Learn More: