Formatting Guidelines

The Phone.com API gives you access to the entire suite of Phone.com services from any programming tool that can send an HTTP request.

This topic defines common formats, field types, response objects and allowed inputs. It is a good resource when you need to check that your code conforms to supported formats.

In This Topic:


Request Format

All successful requests to the Phone.com API begin with a properly formatted URI. For the current release, we accept requests only to: https://v1.api.phone.com/

Requests must also specify the service as part of the fully formatted URI. For example: https://v1.api.phone.com/sms

A list of all Phone.com API services follows:

Feature API Resource Learn More Here ...
Making and receiving phone calls /calls API Resource: /calls
Sending and receiving SMS messages /sms API Resource: /sms
Menus /menus API Resource: /menus
Queues /queues API Resource: /queues
Routes (Call Handling Rules) /routes API Resource: /routes
Greetings and hold music /media API Resource: /media
Batch calls and SMS messages /batch API Resource: /batch
Contacts in your address Book /contacts API Resource: /contacts
Contact groups /contact_groups API Resource: /contact_groups
Schedules for routing calls /schedules API Resource: /schedules
Phone extensions /extensions API Resource: /extensions

For POST and PUT requests, the request body must contain a valid JSON object, with the Content-Type header set to application/json or text/json.

Authentication Format

Authentication is handled using HTTP Basic authentication. HTTP headers may be used for convenience. The username and password are the Phone.com API key and the password you defined for your application in your Phone.com API Developer account settings.

For example:
Authorization: Basic UGhvbmUuY29tOldlbGNvbWUh

Response Format

The response format for all requests is a JSON object.

Whether or not a request succeeded is indicated by the HTTP status code. A 200 (2xx) status code indicates success, whereas a 4xx status code indicates failure. When a request fails, the response body is still JSON, and will always contain the code, info, and url fields, which you can use for debugging.

For example, posting an object to our API without the proper authentication will result in this JSON response:


  {
    "response" : {
       "error" : {
          "info" : "Invalid basic authentication format specified.",
          "url" : "https://docs.phone.com/refguides/errorref/generalerrors.html#error-code-10003",
          "code" : 10003
       }
    }
  }

All error codes map to a detailed message in our API Error Reference Guide. We provide the URL in the error response JSON itself.

Examining an Example POST Request

In the example below, we’ll create a menu using the /menus service to understand our commonly used and acceptable data types and object formats. Menus present your callers with a list of options for routing their calls.

Request Body Format for POST to /menus


{
  "name": "first_menu",
  "allow_extension_dial": "N",
  "outgoing_recording": "40dc31d0-76ef-11e2-bcfd-0800200c9a66",
  "invalid_entry_recording": "f7c0ec0c-9016-11e2-97f5-525400838e08",
  "digits": [
       {
           "digit": "pound",
           "route": "6df07874-a797-11e2-bb5a-dc180921aee7"
      },
       {
           "digit": 0,
           "route": "ae761ef5-a6bd-11e2-b484-9048ce5be0cc"
      },
       {
           "digit": 1,
           "route": "8f0f5201-ac3b-11e2-8b76-de60857c4383"
      },
       {
           "digit": 2,
           "route": "d6e560bb-a6be-11e2-9080-f93165e3d18b"
      },
       {
           "digit": 3,
           "route": "d6e560bb-a6be-11e2-9080-f93165e3d18b"
      }
  ]
}

This request introduces us to several common concepts in the Phone.com API environment. Without going too far into the specifics of what this request is meant to do, let’s examine the fields and the expected data types.

  • “name”: “first_menu” — “JSON keys are always double-quoted strings in the Phone.com API, per the JSON specification. The value must always be a String type.
  • “allow_extension_dial”: “N” — This is an example of a boolean value in the Phone.com API. Quoted characters “Y” and “N” are used in place of the JSON true or false.
  • “outgoing_recording”: “40dc31d0-76ef-11e2-bcfd-0800200c9a66” — The value here introduces us to our UUID type. While always a general string type, the overall value follows a particular convention and is easily recognizable by the five hexadecimal values, separated by dashes, with no whitespace. A regular expression to match on these UUID types is provided later in the document.
  • “invalid_entry_recording”: “f7c0ec0c-9016-11e2-97f5-525400838e08” — The same as in the previous example; this is also a UUID string type.
  • “digits”: [ {“digit”: 1}, {“digit”: 2}, {“digit”: 3} ] — The Phone.com API commonly uses JSON array syntax as a container for an indeterminate number of elements. In this case the digits key has a value equal to an array of individual digit elements.
  • “digit”: 1 — Here we are using the basic number type. The Phone.com API will allow requests to specify true numbers in the requests as well as quoted numbers. It is just as valid to define “digit”: “1” as it is to define “digit”: 1. However, note that the /menus service will always respond to you in string syntax, even if you used a numeric value in your request.

Considered together, we call the rules shown above a schema. Within the API, we implement the use of JSON Schema, and the literal schema for the POST request to /menus is as follows:


{
   "$schema": "http://json-schema.org/draft-03/schema#",
   "id":"menu",
   "description": "POST menu schema",
   "type": "object",
   "properties": {
       "name": {
           "type": "string",
           "required": false,
           "description": "name of the menu.",
           "example": "test_menu"
       },
       "outgoing_recording": {
           "type": "string",
           "format": "uuid",
           "required": false,
           "description": "outgoing recording"
       },
       "invalid_entry_recording": {
           "type": "string",
           "format": "uuid",
           "required": false,
           "description": "invalid entry message"
       },
       "allow_extension_dial": {
           "type": "string",
           "required": false,
           "enum": [
               "Y",
               "N"
           ]
       },
       "level": {
           "type": "integer",
           "required": false
       },
       "wait_time": {
           "type": "integer",
           "required": false,
           "pattern": "^[0-9]+$"
       },
       "digits": {
           "type": "array",
           "required": true,
           "minItems": 1,
           "items": {
               "type": "object",
               "additionalProperties" : false,
               "properties": {
                   "digit": {
                       "type": "string",
                       "pattern" : "^[0-9]{1}|(pound)$",
                       "required": true
                   },
                   "route": {
                       "type": "string",
                       "format": "uuid",
                       "required": true
                   }
               }
           }
       }
   },
   "required": true,
   "additionalProperties" : false
}

For additional information about JSON schemas, see json-schema.org.

Formatting for Specific Field Types

Guidelines for formatting specific field types are shown below.

Resource IDs

The Phone.com API always returns references to objects in a field called resource_id. The resource ID is always a UUID string type, and is the primary way of retrieving your data through the API, regardless of which service you are using. The resource_id field will always be returned in responses where you are creating a new object, allowing you to query the API later using the returned ID.

Example response on object creation (Usually follows any POST or PUT, assuming no errors):


For HTTP Code 404:

{
   "response": {
       "data": {
           "resource_id": "06283513-14f5-11e3-a398-91e4dd3a21e9"
       }
   }
}

Phone Numbers

Our API encourages the use of the E.164 standard for defining all phone numbers, whether they are incoming or outgoing. When referencing phone numbers, responses from the Phone.com API will always be a string, conforming to this standard.

Example:
Basic E.164 Syntax: +15555551234

E.164 numbers are comprised of three parts:

  • The + prefix, while required by E.164, isn’t required on our API requests. If it is left off, our service will add it for you.
  • Following the + prefix, is the country code, in this case 1, which is used for countries in the North American Numbering Plan (NANP), including the United States.
  • The subscriber phone number, in this case, 5555551234. The phone number consists of the familiar area code, prefix and suffix.

Dates

The Phone.com API attaches two common fields to the majority of objects available. Both are representations of the created time, and are provided to you as a convenience. These fields are: created_date and created_epoch, as seen in the example of an SMS object below.


{
   "to": "+15555551235",
   "from": "+5551231234",
   "message": "Welcome to Phone.com",
   "status": "sent",
   "type": "incoming",
   "application_id": "fe02e19d-cd54-11e2-bf99-91e4d3e209c1",
   "created_date": "2014-01-01T23:00:37Z",
   "created_epoch": 1388617237,
   "resource_id": "18a349a6-3d00-11e3-8779-91e7f37d368b",
   "url": "http://yourapplication.com/sms",
   "backup_url": "http://yourapplication2.com/sms",
   "voip_id": 0
}

The two date fields, created_date and created_epoch, represent the same date: January 1, 2014 at 23:00:37 UTC, but one is a string representing the ISO 8601 standard, and the other is an integer representing the number of seconds since the epoch.

When making a POST or PUT request to the Phone.com API, you can define your dates using either ISO 8601, or seconds since the epoch. Regardless of which format you use, our service will always generate both created_date and created_epoch elements, and attach them to your objects at the time your request is processed.

Timestamps and Durations

As with the dates above, timestamps make use of either the ISO 8601 format or an integer representing the number of seconds since the epoch (January 1, 1970), also known as Unix time. Durations are integers representing seconds unless specifically noted in the reference topic for the service in question. Durations may be returned in integer or string form, depending on the service.

Booleans

The Phone.com API supports the options Y (for yes or true) or N (for no or false) to define truth. The JSON barewords true and false are not supported.

The example below illustrates the use of booleans in building the object for a greeting upload. The fields is_hold_music and is_temporary are boolean fields, which accept either the character Y or N.


{
   "resource_id": "9d1ee64b-f316-11e2-b57c-ac4ed37d8038",
   "create_date": 1374528920,
   "duration": "0",
   "filename": "",
   "is_hold_music": "N",
   "is_temporary": "N",
   "name": "voicemail_greeting1",
   "notes": "",
   "origin": "tts",
   "tts_text": "I'm not in, please leave a message.",
   "tts_voice": "amy"
}

Monetary Units

Unless otherwise noted in the reference topic for a specific service, currency is represented by Phone.com in U.S. dollars.

The notation used to represent charges and account balances follows this convention: $12,345.67, where the leading $ represents the USD (U.S. dollar), the comma (,) represents the grouping separator, and the dot (.) represents the decimal indicator. The example USD value above is twelve thousand, three hundred, forty five dollars, and sixty seven cents.

Audio Formats

The Phone.com /media service allows audio files to be added to your account using a POST request to the API. We support several audio file encoding formats, and attempt to maintain the original quality of the uploaded file stream.

Note that files sent to the /media service must have an extension that matches the MIME type of file. The table below lists supported types.

Supported Audio Formats

Type Extension MIME Type
MP3 .mp3 audio/mpeg
ULAW .ulaw audio/x-ulaw
WAV .wav audio/wav
WAV .wav audio/x-wav

We currently have no restrictions on bitrates for each codec. The maximum size for media files or JSON objects included with a POST or PUT request to the Phone.com API is 20 MB.

Useful Regular Expressions

As a developer, you may find the following regular expressions useful when using the Phone.com API. They will help when validating your inputs to the API, and recognizing response values issued back from the API.

All regular expressions conform to Perl-compatible regular expressions (PCRE).

Matching an E.164 string: /^\+?\d{11,14}$/

Matching a resource_id: /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/

Matching an ISO8601 date or timestamp: /(-?(?:[1-9][0-9]*)?[0-9]{4})-(1[0-2]|0[1-9])-(3[0-1]|0[1-9]|[1-2][0-9])?(Z|[+-]
(?:2[0-3]|[0-1][0-9]):[0-5][0-9])?/

Learn More: