Relationships and Includes

Most data types in desk have or belong to some sort of relationship (most objects keep records of created and updated by at minimum). In order to keep API responses as light and cacheable as possible, the Desk API opts to return relationships in an (optional) included field in the response body. The available includes will be specified for each endpoint.

Example

When fetching customers the API (/api/v2/customers.json?includes=users) response may be something like the following:

{
    "customers": [
        {
            "id": 125482,
            "firstName": "Joe",
            "lastName": "Customer",
            "email": "",
            "contacts": null,
            "organization": "",
            "company": null,
            "extraData": ""
            "notes": "",
            "verifiedEmail": false,
            "linkedinURL": "",
            "facebookURL": "",
            "twitterHandle": "",
            "numTickets": 4,
            "jobTitle": "",
            "phone": "",
            "mobile": "",
            "address": "",
            "avatarURL": "https://customer.teamwork.com/desk/images/avatars/animals/leopard.png",
            "createdAt": "2015-11-18T18:56:08Z",
            "updatedAt": "2015-11-18T18:56:08Z",
            "createdBy": {
                "id": 2,
                "type": "users"
            },
            "updatedBy": {
                "id": 2,
                "type": "users"
            },
            "state": "active"
        },
    ]
    "included": {
        "users": [
            {
                "id": 2,
                "email": "brandon@teamwork.com",
                "firstName": "Brandon",
                "lastName": "Hansen",
                "avatarURL": "1/userAvatar/userlogo1493205327729946000.jpg",
                "editMethod": "markdown",
                "isPartTime": false,
                "ticketReplyRedirect": "Stay",
                "reviewer": false,
                "role": "Admin",
                "sendPushNotifications": true,
                "sendWebNotifications": true,
                "useDeskClient": true,
                "createdAt": "2015-12-01T20:39:10Z",
                "updatedAt": "2019-12-04T20:39:10Z",
                "createdBy": {
                    "id": 999999999,
                    "type": "users"
                },
                "updatedBy": {
                    "id": 999999999,
                    "type": "users"
                },
                "state": "active"
            }
        ]
    },
    "pagination": {
        "records": 456441,
        "pageSize": 1,
        "pages": 456441,
        "page": 1,
        "hasMorePages": true
    }
}

The createdBy and updatedBy fields returned in the customers field are represented as not an integer or direct embed of user object, but as a relationship type. The ID field holds the ID of the related object and the type represents the field name in the included section.

The included field is only returned for object types specified in the includes parameter. For example, if we had fetched the customer list and not added the includes=users query parameter, then the response would be the following:

{
    "customers": [
        {
            "id": 125482,
            "firstName": "Joe",
            "lastName": "Customer",
            "email": "",
            "contacts": null,
            "organization": "",
            "company": null,
            "extraData": ""
            "notes": "",
            "verifiedEmail": false,
            "linkedinURL": "",
            "facebookURL": "",
            "twitterHandle": "",
            "numTickets": 4,
            "jobTitle": "",
            "phone": "",
            "mobile": "",
            "address": "",
            "avatarURL": "https://customer.teamwork.com/desk/images/avatars/animals/leopard.png",
            "createdAt": "2015-11-18T18:56:08Z",
            "updatedAt": "2015-11-18T18:56:08Z",
            "createdBy": {
                "id": 2,
                "type": "users"
            },
            "updatedBy": {
                "id": 2,
                "type": "users"
            },
            "state": "active"
        },
    ]
    "pagination": {
        "records": 456441,
        "pageSize": 1,
        "pages": 456441,
        "page": 1,
        "hasMorePages": true
    }
}

Note: To include multiple related object types, separate each field by a comma (eg: includes=customers,users).