API Resource: /routes

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


Important Note: For this release, Routes are Call Handling Rules. Puzzled? Read on!

Our /routes API service allows you to set and manage the settings known as Call Handling Rules in your Phone.com API Developer account settings. Routes are call handling rules by another name. The Call Handling Rules settings you see when you log into your account will be renamed as Routes in a coming release.

Phone.com routes give you flexible options for managing incoming calls. Our /routes service lets you direct calls to one or more destinations, based on menu options that you choose, or on the day and time the call is received.

For example, a call received during business hours could be routed to your Sales queue, but a call received after 5:00 P.M. might be sent directly to voicemail. Routes can be set on any of your Phone.com numbers or extensions.


Diagram showing routing based on time of day

You can use menus to present routing options to your callers. For example, you could let callers choose whether to be routed to voicemail, your Support queue or an automated application. How is a route different from a menu? A menu defines the keypad digits that callers must press to select routing options. Routes are the behind-the-scenes logic that turn menu selections into call actions.


Diagram showing how routes are used with menus

How are routes structured? A set of routes can include multiple inline routes, as well as settings and actions nested within those routes, allowing you to create simple or more complex routing structures. The image below shows a simple route being set to direct incoming calls to an organization’s Sales queue.


Dialog showing routes settings

Routes let you direct calls to any of the following endpoints:

  • Forward: Forwards calls to the designated phone number or extension
  • Voicemail: Routes the caller to voicemail
  • Play: Plays the designated greeting
  • Directory: Routes callers to your dial-by-name directory, if one is configured on your phone number
  • Mandatory hold: Places the call on hold for a set amount of time, and plays hold music if configured
  • Disconnect: Ends the call
  • Application: Routes the call to your application webserver for processing by your app
  • Queue: Routes the caller to the first person in the designated queue
  • Menu: Routes the caller to the designated menu
  • Fax: Routes the caller to your Phone.com fax service
Important: Before implementing routes, you must add any phone numbers, extensions, queues, menus, greetings, dial-by-name directories, or schedules to your account that you want to use in your routing set. For more information, see Using Telephony Toolkit Settings to Set Up Greetings, Menus, Routes and Queues and Managing Greetings and Hold Music.

What Can I Do with Routes?

You can set up routes on your phone numbers or extensions to achieve the simplest of actions—for example, to send all incoming calls to voicemail after business hours.

You can also set more complex routes. For example, you could set the desk phone numbers of your executive staff to forward calls to their mobile phones if they do not answer their desk phones. If they do not answer their mobile phones, calls could then be routed to their personal assistants. And if their assistants are away from their desks, calls can then go to voicemail.

Routes can also direct callers to your automated company directory, to a secondary menu, a fax line, or to a custom API-driven application. For example, in the second illustration above, callers have the option to leave a message, talk to a support representative, or use an automated application to troubleshoot their issues.

Route Settings in the Telephony Toolkit

In some cases, you may find it easier to initially configure the routes you need using the Call Handling Rules settings in the Telephony Toolkit. Before setting call handling rules (routes), plan out the destinations and resources you will need. For example, if you want to offer the option to leave a message, talk to a support representative or use your troubleshooting app, you will need to set up phone numbers, voicemail, a queue for your Support department, and also configure your application in your Phone.com API Developer account.

After logging into your account, select the phone number (Configure > Manage Numbers), extension (Configure > Manage Users & Extensions) or Menu (Configure > Manage Menus) for which you want to configure call handling rules. Use the rules to route calls as needed. For more information, see Using Telephony Toolkit Settings to Set Up Greetings, Menus, Routes and Queues.

Working with the /routes API Resource

In other cases, however, you will need to create and manage routes more dynamically. Using the /routes API service, you can offer end users the ability to update routes on the fly. You can also enable them to add or delete routes as needed.

This topic outlines the methods available for /routes, and shows you how to build effective requests for this service. Your app can create a route using a POST to /routes. Once that route exists, you can update, list or delete it using the PUT, GET and DELETE methods respectively.

Note: The maximum size for media files or JSON objects included with a POST or PUT request to the Phone.com API is 20 MB.

POST /routes

Use POST /routes to create a new route.

Example

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

Authentication

This method requires authentication.

Request Body Fields and Example

Field Type Values Description
name String Letters, numbers, spaces, dash, underscore. Up to 60 char. in length Name for the route. This is a friendly name that you can use to identify the route.
routes Array   Array of routes
call_filtering object   An object to use as a filter for this route. Can be a schedule, a contact, or a contact group;
Visual spacer Visual spacer schedule String UUID Schedule object resource_id. UUID must be a valid resource_id of an existing object. Matches, qr/^[0-9a-f]{8}(?0-9a-f]{4}){3}-[0-9a-f]{12}$/is;
Visual spacer Visual spacer contact String UUID Contact object resource_id. UUID must be a valid resource_id of an existing object. Matches, qr/^[0-9a-f]{8}(?0-9a-f]{4}){3}-[0-9a-f]{12}$/is;
Visual spacer Visual spacer group String UUID Contact group object resource_id. UUID must be a valid resource_id of an existing object. Matches, qr/^[0-9a-f]{8}(?0-9a-f]{4}){3}-[0-9a-f]{12}$/is;
actions Array   Array of nested route objects
Visual spacer action String forward, voicemail, play, directory, mandatory_hold, disconnect, application, queue, menu, fax Action of the route
Visual spacer item_number Integer Default 1 Applies to nested route objects
Visual spacer route_number Integer Default 1 Order for route handling
Visual spacer duration Integer Integer representing minutes Required by mandatory hold action. The duration of the hold.
Visual spacer timeout Integer Integer representing minutes Required by mandatory hold action. The duration of the hold.
Visual spacer recording String UUID Media object resource_id. Required for play action.
Visual spacer menu String UUID Menu object resource_id. Required for menu action.
Visual spacer extension String UUID Extension object resource_id. Required for voicemail and fax actions.
Visual spacer hold_music String UUID Media object resource_id. Required for mandatory_hold and forward actions.
Visual spacer application String UUID Application object resource_id. Required for application action.
Visual spacer queue String UUID Queue object resource_id. Required for queue action.
forwards Array   Array of forwarding objects. Required for forward action.
Visual spacer Visual spacer forward_to String number, extension (Optional) Forward to a number or extension. Default value is number.
Visual spacer Visual spacer Visual spacer extension String UUID Extension object resource_id. Required if forward_to is set to extension.
Visual spacer Visual spacer Visual spacer number String E.164 valid phone number Phone number to which calls are forwarded
Visual spacer Visual spacer caller_id String calling_number, called_number Caller ID displayed after routing the call
Visual spacer Visual spacer voice_tag String 40 char. max. alphanumeric Allows you to tag incoming calls with a unique word or phrase to help identify them
Visual spacer Visual spacer screening Boolean Y/N, y/n, t/f, true/false, 1/0 Allows you to preview who is calling before accepting the call

Request Body Format Example

The example below shows how you can use the actions array to nest route objects under one route_number and apply that to a schedule. Calls that fall outside the schedule parameters would be handled by route_number 2, the forward action.


{
    "name" : "mytestname",
    "rules": [
        {
            "action": "forward",
            "call_filtering": {
                "schedule": "a884c606-8756-11e2-b211-525400abd8d8"
            },
            "timeout": "20",
            "hold_music": "de816950-6105-11e2-bcfd-0800200c9a66",
            "forwards": [
                {
                    "forward_to": "extension",
                    "extension": "5f5de5e7-ca42-11e3-bf87-ded228c54404",
                    "caller_id": "calling_number",
                    "screening": "true",
                    "voice_tag": "Support"
                },
                {
                    "number": "+17777777777",
                    "caller_id": "called_number",
                    "screening": "true",
                    "voice_tag": "Sales"
                }
            ]
        }
    ]
}

Success Response

HTTP Code: 200 OK


{
    "response": {
        "data": {
            "resource_id": "2a95ecce-158a-11e3-93c4-9d92284f668b"
        }
    }
}

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": 30005,
            "detail": [
                "the name: mytestname, is in use in another route."
            ],
            "info": "Invalid request. The resource is in use.",
            "url": "https://docs.phone.com/refguides/errorref/serviceerrors.html#error-code-30005"
        }
    }
}

Sample POST /routes Request (PHP)

Note that if you attempt to create a route using objects that the system cannot find, the API server will return an HTTP 404 error.


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

  $post_body = <<<CHRDATA
  {
      "name": "mytestname",
      "rules": [
          {
              "action": "forward",
              "call_filtering": {
                  "schedule": "a884c606-8756-11e2-b211-525400abd8d8"
              },
              "timeout": "20",
              "hold_music": "de816950-6105-11e2-bcfd-0800200c9a66",
              "forwards": [
                  {
                      "forward_to": "extension",
                      "extension": "5f5de5e7-ca42-11e3-bf87-ded228c54404",
                      "caller_id": "calling_number",
                      "screening": "true",
                      "voice_tag": "Support"
                  },
                  {
                      "number": "+17777777777",
                      "caller_id": "called_number",
                      "screening": "true",
                      "voice_tag": "Sales"
                  }
              ]
          }
      ]
  }
  CHRDATA;

  $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 /routes.


GET /routes

Use GET /routes to retrieve a list of existing route objects in your account. Note that, by default, you can retrieve a maximum of 20 routes 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/routes

Authentication

This method requires authentication.

Parameters

Parameter Type Values Description
limit (Optional) Integer   Limits the result set to the value provided, to a maximum of 50 route objects. 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   Field by which you want to order results
name (Optional) String   Allows you to retrieve objects by name.

Success Response

HTTP Code: 200 OK

Response Body Fields and Example

Field Type Values Description
resource_id String UUID The resource id of the object.
name String   Name for the route. This is a friendly name that you can use to identify the route.
routes Array   Array of routes
actions Array   Array of nested route objects
Visual spacer action String   Action of the route
Visual spacer schedule String   Schedule object resource_id.
Visual spacer item_number Integer   Applies to nested route objects
Visual spacer route_number Integer   Order for route handling
Visual spacer duration Integer   Required by mandatory hold action. The duration of the hold.
Visual spacer timeout Integer   Required by forward action. The timeout if no forwarding number answers the call.
Visual spacer recording String   Media object resource_id. Required for play action.
Visual spacer menu String   Menu object resource_id. Required for menu action.
Visual spacer extension String   Extension object resource_id. Required for voicemail and fax actions.
Visual spacer hold_music String   Media object resource_id. Required for mandatory_hold and forward actions.
Visual spacer application String   Application object resource_id. Required for application action.
Visual spacer queue String   Queue object resource_id. Required for queue action.
Visual spacer caller_id String   Caller ID displayed after routing the call
forwards Array   Array of forwarding objects. Required for forward action.
Visual spacer forward_to String number, extension (Optional) Forward to a number or extension. Default value is number.
Visual spacer Visual spacer extension String UUID Extension object resource_id. Required if forward_to is set to extension.
Visual spacer Visual spacer number String   Phone number to which calls are forwarded
Visual spacer caller_id String   Caller ID displayed after routing the call
Visual spacer voice_tag String   Allows you to tag incoming calls with a unique word or phrase to help identify them
Visual spacer screening Boolean   Allows you to preview who is calling before accepting the call

Response Body Format Example


{
    "response": {
        "data": [
            {
                "resource_id": "50bf82ca-b2a5-11e2-aef5-e8568861c147",
                "name": "testname",
                "rules": [
                    [
                        {
                            "action": "disconnect",
                            "rule_number": "1"
                        }
                    ]
                ]
            },
            {
                "resource_id": "309ecef3-1589-11e3-93c4-f68ed710a677",
                "name": "test",
                "rules": [
                    [
                        {
                            "action": "forward",
                            "forwards": [
                              {
                                  "caller_id": "calling_number",
                                  "extension": {
                                      "resource_id": "5f5de5e7-ca42-11e3-bf87-ded228c54404",
                                      "url": "https://v1.api.phone.com/extensions/5f5de5e7-ca42-11e3-bf87-ded228c54404"
                                  },
                                  "screening": "false",
                                  "voice_tag": "Support"
                              },
                              {
                                  "caller_id": "called_number",
                                  "number": "17777777777",
                                  "screening": "false",
                                  "voice_tag": "Sales"
                              }
                            ],
                            "rule_number": "1"
                        }
                    ]
                ]
            },
            {
                "resource_id": "11e69f9f-1589-11e3-93c4-89b643a8f167",
                "name": "route_c89249b3c73",
                "rules": [
                    [
                        {
                            "action": "disconnect",
                            "rule_number": "1"
                        }
                    ]
                ]
            },
            {
                "resource_id": "ba347214-0c19-11e3-8584-8f02e7a8dc50",
                "name": "route_c86ba475743",
                "rules": [
                    [
                        {
                            "action": "disconnect",
                            "rule_number": "1"
                        }
                    ]
                ]
            },
            {
                "resource_id": "a127d581-0112-11e3-9031-dd95dd3aad93",
                "name": "route_c83e78f6d13",
                "rules": [
                    [
                        {
                            "action": "menu",
                            "menu": {
                                "resource_id": "6fa47c76-eda9-11e2-93ee-92d4ad85c38d",
                                "url": "https://v1.api.phone.com/menus/6fa47c76-eda9-11e2-93ee-92d4ad85c38d"
                            },
                            "rule_number": "1"
                        }
                    ]
                ]
            }
        ],
        "links": [
            {
                "next": "https://v1.api.phone.com/routes?limit=5&offset=15&order_by=name&sort=desc"
            },
            {
                "prev": "https://v1.api.phone.com/routes?limit=5&offset=5&order_by=name&sort=desc"
            }
        ]
    }
}

Error Response

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

Sample GET /routes Request (PHP)


<?php
$url = "https://v1.api.phone.com/routes/?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);
}
?@gt;

Back to Methods Available for /routes.


DELETE /routes

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

Example

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

Authentication

This method requires authentication.

Parameters

Parameter Type Values Description
delete_all Boolean 0, 1 Set to 1 to complete the operation

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 /routes Request (PHP)


<?php
$url = "https://v1.api.phone.com/routes?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 /routes.


GET /routes/UUID

Use GET /routes/UUID to retrieve a single Queue object.

Example

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

Authentication

This method requires authentication.

Success Response

HTTP Code: 200 OK

Response Body Fields and Example

Field Type Values Description
resource_id String UUID The resource id of the object.
name String   Name for the route. This is a friendly name that you can use to identify the route.
routes Array   Array of routes
actions Array   Array of nested route objects
Visual spacer action String   Action of the route
Visual spacer schedule String   Schedule object resource_id.
Visual spacer contact String   Contact object resource_id.
Visual spacer contact_group String   Contact group object resource_id.
Visual spacer item_number Integer   Applies to nested route objects
Visual spacer route_number Integer   Order for route handling
Visual spacer duration Integer   Required by mandatory hold action. The duration of the hold.
Visual spacer timeout Integer   Required by forward action. The timeout if no forwarding number answers the call.
Visual spacer recording String   Media object resource_id. Required for play action.
Visual spacer menu String   Menu object resource_id. Required for menu action.
Visual spacer extension String   Extension object resource_id. Required for voicemail and fax actions.
Visual spacer hold_music String   Media object resource_id. Required for mandatory_hold and forward actions.
Visual spacer application String   Application object resource_id. Required for application action.
Visual spacer queue String   Queue object resource_id. Required for queue action.
Visual spacer caller_id String   Caller ID displayed after routing the call
forwards Array   Array of forwarding objects. Required for forward action.
Visual spacer Visual spacer forward_to String number, extension Optional, default value is number
Visual spacer Visual spacer extension String UUID Extension object resource_id. Required if ‘forward_to’ is set to extension.
Visual spacer number String   Phone number to which calls are forwarded
Visual spacer caller_id String   Caller ID displayed after routing the call
Visual spacer voice_tag String   Allows you to tag incoming calls with a unique word or phrase to help identify them
Visual spacer screening Boolean   Allows you to preview who is calling before accepting the call

Response Body Format Example


{
    "response": {
        "data": {
            "resource_id": "7f6a1919-0e77-11e3-ae4b-e1fed5ba438a",
            "name": "route_7d49557f7c35",
            "rules": [
                {
                    "actions": [
                        {
                            "action": "play",
                            "item_number": "1",
                            "recording": {
                                "resource_id": "23916114-febe-11e2-9e09-b36883d6694b",
                                "url": "https://v1.api.phone.com/media/23916114-febe-11e2-9e09-b36883d6694b"
                            }
                        },
                        {
                            "action": "mandatory_hold",
                            "item_number": "2",
                            "recording": {
                                "resource_id": "5aa18a74-c3c8-11e2-8404-525400838e08",
                                "url": "https://v1.api.phone.com/media/5aa18a74-c3c8-11e2-8404-525400838e08"
                            }
                        },
                        {
                            "action": "application",
                            "application": {
                                "resource_id": "7024b8b7-5c3e-11e2-b25b-aecdb1fca3f8",
                                "url": "https://v1.api.phone.com/applications/7024b8b7-5c3e-11e2-b25b-aecdb1fca3f8"
                            },
                            "item_number": "3"
                        }
                    ],
                    "rule_number": "1"
                },
                [
                    {
                        "action": "application",
                        "application": {
                            "resource_id": "7024b8b7-5c3e-11e2-b25b-aecdb1fca3f8",
                            "url": "https://v1.api.phone.com/applications/7024b8b7-5c3e-11e2-b25b-aecdb1fca3f8"
                        },
                        "rule_number": "2"
                    }
                ],
                [
                    {
                        "action": "forward",
                        "forwards": [
                            {
                                "caller_id": "calling_number",
                                "number": "9999999999",
                                "screening": "true",
                                "voice_tag": "My NEW THING"
                            },
                            {
                                "caller_id": "called_number",
                                "number": "7777777777",
                                "screening": "true",
                                "voice_tag": "thing"
                            },
                            {
                                "caller_id": "called_number",
                                "number": "5555555555",
                                "screening": "true",
                                "voice_tag": "thing 5"
                            }
                        ],
                        "rule_number": "3"
                    }
                ]
            ]
        }
    }
}

Error Response

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

Sample GET /routes/UUID Response (PHP)


<?php
$url = "https://v1.api.phone.com/routes/e1186304-a5ec-11e2-8507-e90d08636c59";

$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 /routes.


PUT /routes/UUID

Use PUT /routes/UUID to update specific routes objects.

Important:

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 a route using PUT to /routes, but you cannot change the name to a name used by another route.

Example

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

Authentication

This method requires authentication.

Request Body Fields and Example

Field Type Values Description
name String Letters, numbers, spaces, dash, underscore. Up to 60 char. in length Name for the route. This is a friendly name that you can use to identify the route.
routes Array   Array of routes
actions Array   Array of nested route objects
Visual spacer action String forward, voicemail, play, directory, mandatory_hold, disconnect, application, queue, menu, fax Action of the route
Visual spacer call_filtering object   An object to use as a filter for this route. Can be a schedule, a contact, or a contact group;
Visual spacer Visual spacer schedule String UUID Schedule object resource_id. UUID must be a valid resource_id of an existing object. Matches, qr/^[0-9a-f]{8}(?0-9a-f]{4}){3}-[0-9a-f]{12}$/is;
Visual spacer Visual spacer contact String UUID Contact object resource_id. UUID must be a valid resource_id of an existing object. Matches, qr/^[0-9a-f]{8}(?0-9a-f]{4}){3}-[0-9a-f]{12}$/is;
Visual spacer Visual spacer group String UUID Contact group object resource_id. UUID must be a valid resource_id of an existing object. Matches, qr/^[0-9a-f]{8}(?0-9a-f]{4}){3}-[0-9a-f]{12}$/is;
Visual spacer item_number Integer Default 1 Applies to nested route objects
Visual spacer route_number Integer Default 1 Order for route handling
Visual spacer duration Integer Integer representing minutes Required by mandatory hold action. The duration of the hold.
Visual spacer timeout Integer Integer representing minutes Required by forward action. The timeout if no forwarding number answers the call.
Visual spacer recording String UUID Media object resource_id. Required for play action.
Visual spacer menu String UUID Menu object resource_id. Required for menu action.
Visual spacer extension String UUID Extension object resource_id. Required for voicemail and fax actions.
Visual spacer hold_music String UUID Media object resource_id. Required for mandatory_hold and forward actions.
Visual spacer application String UUID Application object resource_id. Required for application action.
Visual spacer queue String UUID Queue object resource_id. Required for queue action.
Visual spacer caller_id String calling_number, called_number Caller ID displayed after routing the call
forwards Array   Array of forwarding objects. Required for forward action.
Visual spacer Visual spacer forward_to String number, extension Optional, default value is number
Visual spacer Visual spacer extension String UUID Extension object resource_id. Required if ‘forward_to’ is set to extension.
Visual spacer number String E.164 valid phone number Phone number to which calls are forwarded
Visual spacer caller_id String calling_number, called_number Caller ID displayed after routing the call
Visual spacer voice_tag String 40 char. max. alphanumeric Allows you to tag incoming calls with a unique word or phrase to help identify them
Visual spacer screening Boolean Y/N, y/n, t/f, true/false, 1/0 Allows you to preview who is calling before accepting the call

Request Body Format Example


{
    "name": "test",
    "rules": [
        {
            "action": "menu",
            "menu": "f4a190a2-a5ea-11e2-9681-c3e0b7710d4f",
            "call_filtering": {
              "schedule": "a884c606-8756-11e2-b211-525400abd8d8"
            }
        }
    ]
}

Success Response

HTTP Code: 200 OK


{
    "response": {
        "data": {
            "resource_id": "6144f68c-158c-11e3-93c4-ab9b35b17381"
        }
    }
}

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 /routes Request (PHP)


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

$post_body = <<<CHRDATA
{
   "name": "test",
   "rules": [
      {
         "action": "forward",
         "call_filtering": {
            "group": "661af110-f320-11e2-8404-525400838e08"
         },
         "timeout": "20",
         "caller_id": "calling_number",
         "hold_music": "de816950-6105-11e2-bcfd-0800200c9a66",
         "forwards": [
            {
               "number": "9999999999",
               "caller_id": "calling_number",
               "screening": "true",
               "voice_tag": "Sales"
            },
            {
               "number": "7777777777",
               "caller_id": "called_number",
               "screening": "true",
               "voice_tag": "Support"
            }
         ]
      }
   ]
}
CHRDATA;

$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 /routes.


DELETE /routes/UUID

Use DELETE /routes/UUID to delete a specific route object.

Example

DELETE https://v1.api.phone.com/routes/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,
            "info": "Invalid request. The resource is in use.",
            "url": "https://docs.phone.com/refguides/errorref/serviceerrors.html#error-code-30005"
        }
    }
}

Sample DELETE /routes/UUID Request (PHP)

A route that is currently in use by another object cannot be deleted until that reference is removed.


<?php
$url = "https://v1.api.phone.com/routes/80417048-ac3b-11e2-8b76-eea2f9d0a5a3";

$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 /routes.


Learn More: