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.
Note: To include multiple related object types, separate each field by a comma (eg: includes=customers,users).
When fetching customers the API (/api/v2/customers.json?includes=users) response may be something like the following:
Response for Get customers endpoint
{
"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:
Response if 'includes=users' is omitted from request
{
"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
}
}Removing the relationship between any two types can be done by including the delete: true key/value pair. The example response below will remove the tag with id 2 from ticket 83654453.
Response
{
"ticket":{
"id": 83654453,
"tags": [
{
"id": 2,
"type": "tags",
"delete": true
}
]
}
}