JSON Formatting

You must use JavaScript Object Notation (JSON) syntax to define any object you are requesting from the Phone.com API. JSON is a descriptive, text-based syntax, used to define data objects when passing them between endpoints. It is both language and platform independent.

Objects that you might need to define in your API requests include menus, queues, greetings and a host of other Phone.com resources. Our API also uses JSON to describe objects when delivering responses to your requests. Responses include descriptions of individual resources in your account, lists of resources that you have requested, and error details if your request fails.

The sections below describe the JSON syntax supported in the Phone.com API for both requests and responses.

In This Topic:

API Request Format

The JSON object used when creating (POST) or updating (PUT) a resource should simply contain a description of the object itself.


 {
     "resource_id" : "uuid1",
     "outgoing_recording" : "uuid2",
      <rest of object>
 }

For more information on using JSON syntax in your requests, see Basic Phone.com API Requests and Responses.

API Response Format

Responses to a valid request (200 HTTP code) will include a JSON document that follows this format:


 {
     "results": {
         "data": [
             <object or list of objects>
         ]
     }
 }

Resources

When making a request for a specific resource (for example, GET /menus/uuid), the data array in the response will contain a single object, as follows.


 {
    "results" : {
         "data" : [
             {
                 "resource_id" : "uuid1",
                 "outgoing_recording" : "uuid2",
                  <rest of object>
             }
         ]
     }
 }

Lists

When making a request for a list of resources (for example, GET /menus), the data array in the response will contain a list of objects.

The API will return up to ten objects per response. If the list contains more than ten, the response will also include a links object, which contains prev and next fields that include links to allow you to move through additional list pages easily.


 {
    "results" : {
         "data" : [
             {
                 "resource_id" : "uuid1",
                 "outgoing_recording" : "uuid2",
                 <rest of object 1>
             },
             {
                 "resource_id" : "uuid3",
                 "outgoing_recording" : "uuid4",
                 <rest of object 2>
             }
         ]
     },
     "links" : [
         {
             "prev" : "https://v1.api.phone.com/menus?limit=x&offset=z"
         },
         {
             "next" : "https://v1.api.phone.com/menus?limit=y&offset=z"
         }
     ]
 }

For more information on understanding JSON syntax in responses, see Basic Phone.com API Requests and Responses.

API Error Format

Invalid requests that result in an error response will include an extended error code formatted as follows:


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

For more information on working with error codes, see Troubleshooting Error Codes.


Learn More: