Basic Phone.com API Requests and Responses

Whether you’re using a REST request to change a simple setting in your Phone.com account or to control a complex phone call, our API services use the HTTP protocol for all communications. The Phone.com API is a REST API.

This topic covers how to structure Phone.com API requests and responses, and provides examples that you can review when writing your own API requests.

In This Topic:

Forming HTTP Requests

API requests must be written as HTTP requests, and include the following components:

  • HTTP Method: Describes the type of HTTP action (POST, GET, PUT or DELETE)
  • URL: Describes the resource you are creating or accessing, along with any optional arguments
  • HTTP Headers: Specifies attributes of the request, including authentication, encoding and request format
  • Request Body: Describes resources or specifies a call-control script

HTTP Methods

The Phone.com API supports basic POST, GET, PUT and DELETE HTTP methods.

POST

Used to create a new resource, like a menu or queue, or to initiate a phone call. Note that POST can only be used to create new objects.

Example:
POST /menus - to create a new menu

GET

Used to retrieve the definition of a resource—for example, a menu configuration or the state of a phone call. You can also use GET to retrieve a list of objects in a collection or a single object in that collection.

Examples:
GET /menus - retrieves the list of menus
GET /menus/UUID - retrieves a specific menu

PUT

Used to update an existing resource. Note that only full updates are supported—meaning updates that replace the entire object definition, as opposed to updating select fields only.

Example:
PUT /menus/UUID

DELETE

Used to delete a resource—for example, deleting a menu or canceling a scheduled phone call. DELETE can be used on collections and individual objects, but a DELETE on a collection must include the delete_all argument to avoid deleting a collection by accident.

Examples:
DELETE /menus
DELETE /menus/UUID

Limitations on Methods

Note that some kinds of Phone.com resources cannot be created with the POST command. For example, a call recording can be seen as a by-product of an API call that initiates a phone call, but it is not created by the POST command. Similarly, not all objects can be deleted with the DELETE command. For example, call logs cannot be deleted.

Also, some collections and objects are read-only—for example, text-to-speech voice settings. Please refer to the API Command Reference Guide to see the specific methods supported for different resources. The table below shows how methods are typically applied to collections and single objects.

  POST GET PUT DELETE
Collection (/menus) Create Read Invalid Delete
Single Object (/menus/UUID) Invalid Read Update Delete

Note that requests containing unsupported methods will return an HTTP 400 error, with Error Code: 10005.

API URL Format

The Phone.com API URL uses the following format: https://<version>.api.phone.com/<resource>[/<id>][?list of optional arguments]

Example:
https://v1.api.phone.com/sms/?limit=15&format=json

Note that the protocol is always HTTPS, that version matches the version of the API that you are using, and that resource and (optionally) [/id] describe the resource you want to access. Optional arguments can be specified after a question mark using the format argument=value and multiple arguments are separated by &. In the example above, results are limited to 15. The format argument is optional, but if present, must be set to json.

HTTP Request Headers

The Phone.com API recognizes the following HTTP headers in API requests. Note that these headers are not case sensitive.

Host

Specifies the server name and API version: <version>.api.phone.com

Example:
Host: v1.api.phone.com

Note that typically your HTTP client library or software will set the hostname for you—you will not need to set it manually. If the header is missing, the request will fail with an HTTP 400 Invalid Request error code. If the header contains a hostname for an unsupported version, an HTTP 400 Invalid Request will be returned with an Error Code: 10006.

Authentication

All API requests must be authenticated using HTTP Basic authentication. For more information, see Account Security.

Example:
API Key: 5d205ef2-7fc3-11e2-9865-ef010b5ae12e
API Password: *mYsEcReT*
Authentication: Basic NWQyMDVlZjItN2ZjMy0xMWUyLTk4NjUtZWYwMTBiNWFlMTJlOiptWXNFY1JlVCoK

Your HTTP client library will likely offer a simple way to use Basic authentication. If the header is missing, incorrectly formatted, or the credentials are invalid, the request will fail with an HTTP 401 Unauthorized error.

Content-Type

Specifies the format of the request (JSON) and the encoding type.

Request Format:

JSON
  • Supported values: text/json and application/json
  • The body of the request must be a JSON object.
URL Encoded
  • Supported value: application/x-www-form-urlencoded

This second format supports making requests using form content-types. The actual format will default to JSON, and the body of the request must be: json=<json object>

Encoding Type:

Supported encoding formats include UTF-8 and ISO-8859-1 (latin1). If the encoding format is not specified with the charset parameter, the system will default to UTF-8.

The Phone.com API supports UTF-8 encoding so that you can store object names and properties with non-ASCII characters.

Examples:
Content-Type: text/json; charset=utf-8
Content-Type: text/json; charset=iso-8859-1

If the Content-Type header is missing, the API server will try to locate the format in the URL; otherwise it will default to JSON. If the format of the body of the request or its encoding doesn’t match the headers, the API server will return an HTTP 400 Invalid Request error. If your HTTP client doesn’t support customizing HTTP headers, you can also set the format in the URL. See the list of Optional Arguments below.

Accept

Accept headers let you request the format of the response. The Phone.com API will process Accept headers that include quality factors but will only recognize and use the following types: text/json, application/json, and text/*.

Examples:
Accept: text/json

If the header is missing, the API will try to locate the format in the URL and then default to JSON format.

Request Body Format

Requests that create (POST) or update (PUT) a resource must contain a description of the resource. GET and DELETE requests, on the other hand, should not include a body component in the HTTP request.

Unless the request is URL encoded, the body should only contain the JSON object. If you choose to encode your requests with standard form URL encoding, you still need to create JSON for your request, but you must encode a key named ‘json’ with Content-Type application/x-www-form-urlencoded data.

A full PHP example for a URL-encoded POST to our /sms service is shown below.

Sample POST /sms Request (PHP)


  <?php

  $url     = 'https://v1.api.phone.com/sms/';
  $app_key = '<my app key>';
  $app_pwd = '<my app password>';

  $payload = <<<JSON
  {
     "from": "<caller ID>",
     "to": "<caller ID>",
     "message": "My First SMS."
  }
  JSON;

  $data = array('json' => $payload);

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);

  // authentication
  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
  curl_setopt($ch, CURLOPT_USERPWD, "$app_key:$app_pwd");

  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/x-www-form-urlencoded'));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

  $result = curl_exec($ch);
  $info = curl_getinfo($ch, CURLINFO_HTTP_CODE);

  curl_close($ch);

  if($info == 200 || $info == 201) {
     $response = json_decode($result, true);
     $sms_id = $response['results']['data'][0]['resource_id'];
     echo "ID: $sms_id\n";
  } else {
     $error = array('http_code' => $info['http_code'], 'response' => $result);
     echo "Error: $info['http_code']\n";
     echo "Response body: $result\n";
  }

  ?>

Forming HTTP Responses

API responses are written as HTTP responses, and include:

  • HTTP Code: Describes the result of the request (success or failure)
  • HTTP Headers: Specify attributes of the response, including response format, encoding and length
  • Response Body: Describes resources or errors

Response HTTP Codes

The Phone.com API server will reply to requests with the following HTTP codes:

  • 200 - Valid request, executed successfully
  • 400 - Invalid request
  • 401 - Authentication missing or invalid
  • 403 - Permission to access this resource is denied
  • 404 - Unknown version or resource
  • 409 - Problem executing request
  • 500 - Server error while processing the request

When the request results in an error, the response contains an extended error reference. These codes provide a more detailed reason for failure than standard HTTP codes do, and help you troubleshoot issues that may have led to the error.

API Response Headers

The Phone.com API sets the following headers in responses:

Content-Type

Indicates the format and encoding of the body of the response as follows:

Format: text/json or application/json
Encoding: utf-8 or iso-8859-1

Note that the format is set based on the Accept header or the URL argument, and it will default to JSON. Response encoding is always set to the same encoding type used in the request. If the API is unable to determine a requested format type, it will use JSON to deliver an Error Code: 10008.

Example:
Content-Type: text/json; charset=utf-8

Content-Length

Indicates the length of the response (HTTP body).

Example:
Content-Length: 250

WWW-Authenticate

When responding to a request that doesn’t include a correctly formed Authentication header, the API server will include the WWW-Authenticate header in its response. The realm is Phone.com API.

Example:
WWW-Authenticate: Basic realm="Phone.com API"

Resource Format

Resources can be a collection of objects (for example: /menus) or a single object identified by its UUID (for example: /menus/<UUID>). See the API Reference Guide for a full list of API resources.

Optional Arguments

The Phone.com API supports optional arguments passed in the URL. Note that parameters for these arguments are not case sensitive. The following arguments are available for any request, and additional parameters are supported by specific services.

Method

If your HTTP client does not allow you to set the HTTP method, you can set it on the command line.

Parameter Name: method
Values: POST, GET, PUT and DELETE

This parameter overrides the settings in the HTTP Header.

Example:
GET /menus/?method=DELETE

Format

If your HTTP client does not allow you to manipulate HTTP headers, you can set the format on the command line. The format argument is optional, but if present, must be set to json.

Parameter Name: format
Values:json - The body of the request and the reply is in JSON format

This parameter overrides the settings in the HTTP Header.

Example:
GET /menus?format=json

Delete All Resources

By default, the Phone.com API will not execute a REST command to delete all items in a collection. This is so that all items will not be deleted if an API call like DELETE /menus/ is issued, when the application should have sent DELETE /menus/<uuid>. If you really want to delete all objects in a collection, you need the specify the following argument.

Parameter Name: delete_all
Value: Must be set to 1

Note: You cannot delete a resource used by another object. The delete_all parameter does not change this behavior.

Example:
DELETE /menus?delete_all=1

Response Body Format

All responses from the Phone.com API server contain an HTTP body that includes one of the following:

  • A description of the resource (the resource)
  • A unique ID (resource creation)
  • An extended error code (when failing)

The body of a response for a valid request (HTTP 200 OK) follows the following format:


{
  "response" : {
    <resource description>
  }
}

If the request failed (HTTP 400 Invalid Request), the response body would follow this format:



{
  "response" : {
    "error" : {
       <extended error code>
    }
  }
}

Learn More: