API 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": "[e-mail]",
        "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": "[e-mail]",
            "firstName": "John",
            "lastName": "Smith"
        },
        {
            "email": "[e-mail]",
            "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": "[e-mail]",
       "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"
       }
   }
}

 

Sideloading

Related resources can be included in a response by setting the include query parameter to a comma delimited list of relationships. Nested relationships may also be included by using a period to chain together relationships. The resulting JSON will include collections for each type of resource and resources will have properties identifying their related resources. This is referred to as “sideloading”. Below is an example of request for contacts including related contact lists, lists and organization.

GET api/3/contacts?include=contactLists.list,organization

{
   "contacts": [
       {
           "id": 1,
           "email": "[e-mail]",
           "firstName": "John",
           "lastName": "Smith",
           "contactLists": [3,5],
           "organization": 7,
       }
   ],
   "contactLists": [
       {
           "id": 3,
           "list": 5
       },
       {
           "id": 6,
           "list": 10
       }
   ],
   "lists": [
       {
           "id": 5,
           "name": "Monthly Newsletter"
       },
       {
           "id": 10,
           "name": "Daily Deals"
       }
   ],
   "organization": [
       {
           "id": 7,
           "name": "NameOfYourOrganization"
       }
   ]
}

 

Meta

Meta data can be represented as a top level member named “meta”. Any information may be provided in the meta data. It’s most common use is to return the total number of records when requesting a collection of resources.

GET api/3/contacts?limit=2

{
   "contacts": [
       {
           "id": 1,
           "email": "[e-mail]",
           "firstName": "John",
           "lastName": "Smith"
       },
       {
           "id": 2,
           "email": "[e-mail]",
           "firstName": "Alice",
           "lastName": "Jones"
       }
 ],
 "meta": {
    "total": 36
  }
}