Schema

All API requests and response bodies adhere to a common JSON format representing individual items, collections of items, links to related items and additional meta data.

Single Resources

Individual resources are represented by top level member named after the resource in the singular form. Below is a representation of a single contact. This could be used in the body of a PUT request and it’s what would be returned in the body of a GET request.

{
	"contact": {
		"email": "[email protected]",
		"firstName": "John",
		"lastName": "Smith"
	}
}

Collections

Collections of resources are represented by a top level member named after the resource in the plural form. Below is a representation of a collection of contacts.

{
	"contacts": [
        {
            "email": "[email protected]",
            "firstName": "John",
            "lastName": "Smith"
        },
        {
            "email": "[email protected]",
            "firstName": "Alice",
            "lastName": "Jones"
        }
    ],
    "meta": {
        "total": "2"
    }
}

Relationships

A resource may define relationships to other resources. The name of a relationship generally reflects the type of the related resource. The name will be singular if there is only one related resource or plural if there are many related resources.

Links

Resources may provide links to related resources by defining a member named “links” within the resource’s object representation. Links are defined as an object where the key name represents the name of the relationship and the value is a URL to the related resource(s). For example, here is a representation of a contact with links to the contact’s contact lists and the contact’s organization.

{
   "contact": {
       "id": 1,
       "email": "[email protected]",
       "firstName": "John",
       "lastName": "Smith"
       "links": {
           "contactLists": "https://:account.api-us1.com/api/3/contacts/1/contactLists",
           "organization": "https://:account.api-us1.com/api/3/contacts/1/organization"
       }
   }
}