Fields

Case objects have the following fields and links:

Fields

field name description
id integer identifier for this object
external_id unique external identifier to reference this case to an external system
blurb short summary of, or excerpt from, the case
subject subject of the case
priority number between 1 and 10, 1 being lowest priority
description description or background information
status current state of the case, one of: new, open, pending, resolved, closed, deleted
type channel of the case, one of: chat, twitter, email, qna, facebook, phone
labels array of labels associated with this case
label_ids array of label ids associated with this case
language the case's ISO language code, which returns the site's default language (or nil if not set) unless multi-lingual support is enabled
custom_fields hash of values for custom fields
created_at when this record was created
updated_at when this record was last updated by any action
changed_at when this case was last updated by a user
active_at when this case was last active
received_at when the most recent message was received
locked_until when the lock on this case will expire
first_opened_at when this case was first opened
opened_at when this case was most recently opened
first_resolved_at when this case was first resolved
resolved_at when this case was most recently resolved
suppress_rules set to true to disable rule processing when creating or updating this case
route_status current routing status of the case. this field only appears when routing is enabled for the first time. there are four values: added when a case is first added to desk. this switches to available after a few seconds.available case is not in use and can be routed. assigned case is being presented to a specific user to accept. active a case is open and in edit mode. doesn't necessarily have to have been routed.

Community Question & Answer Fields

field_name description
public_url The public-facing URL for this Q&A

Note that public_url is on the message, not the case. In order to get it on the case you need to pass embed=message in to your request.

Links

rel class embeddable? count? description
self case no no this case
message varies depending on channel yes no the original message for the case
customer customer yes no customer that submitted this case
assigned_user user yes no user assigned to this case
assigned_group group yes no group assigned to this case
locked_by user yes no user currently working on this case
history history no no history for this case
replies reply no yes replies to this case
draft reply yes no draft on this case
notes note no yes notes on this case
attachments attachment no yes attachments on this case
feedbacks customer_feedback yes yes customer feedbacks on this case

Replies, notes, attachments, and feedbacks have an additional field in the _links hash named count. count is the number of resources for that relationship -- for example, a case with 5 attachments will have 5 as the value of the count field within the attachments link. Your application can make fewer requests by taking advantage of this field -- there's no reason to request notes if there aren't any!


List

Retrieve a paginated list of all cases.

GET https://yoursite.desk.com/api/v2/cases

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Searching

All search options for the Cases Search endpoint are also available for use on the Cases List endpoint.

List Parameters

parameter description
company_id Optional field to return a case list based on the company id presented in the request parameter. Use companies endpoint to get all available companies and ids.
https://yoursite.desk.com/api/v2/cases?company_id=1
customer_id Optional field to return a case list based on the customer id presented in the request parameter. Use companies endpoint to get all available customers and ids.
https://yoursite.desk.com/api/v2/cases?customer_id=1
filter_id Optional field to return a case list based on the filter id presented in the request parameter. Use filters endpoint to get all available filters and ids.
https://yoursite.desk.com/api/v2/cases?filter_id=1

Sorting

Sorting is supported by using sort_field and sort_direction parameters in your request.

  • sort_field - case field on which you would like to sort
  • sort_direction - direction to sort - asc for ascending, desc for descending

The following fields can be used for sorting cases: id, created_at, priority, received_at, status, and updated_at. The default sort field is created_at and the default direction is asc.

Limits

The maximum page parameter value for this endpoint is currently 500. To access higher pages, we recommend using a combination of sorting and searching. The most helpful search parameter for this will likely be since_created_at, since_updated_at, or since_id. Combined with sorting by created_at or updated_at, all of your data is easily accessible.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/cases \
    -u email:password \
    -H 'Accept: application/json'

Example Curl Request with sorting

1
2
3
4
$ curl https://yoursite.desk.com/api/v2/cases \
    -u email:password \
    -d 'sort_field=created_at&sort_direction=asc' -G \
    -H 'Accept: application/json'

Example Response

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/cases?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/cases?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/cases?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "id": 1,
        "external_id": null,
        "blurb": null,
        "subject": "Welcome",
        "priority": 5,
        "locked_until": null,
        "description": null,
        "status": "new",
        "type": "email",
        "labels": [

        ],
        "label_ids": [

        ],
        "language": "en_us",
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:24:27Z",
        "changed_at": "2017-08-18T22:23:27Z",
        "active_at": "2017-08-18T22:24:27Z",
        "received_at": "2017-08-18T22:19:27Z",
        "first_opened_at": "2017-08-18T22:20:27Z",
        "opened_at": "2017-08-18T22:21:27Z",
        "first_resolved_at": "2017-08-18T22:24:27Z",
        "resolved_at": "2017-08-18T22:24:27Z",
        "custom_fields": {
          "level": "vip"
        },
        "_links": {
          "self": {
            "href": "/api/v2/cases/1",
            "class": "case"
          },
          "message": {
            "href": "/api/v2/cases/1/message",
            "class": "message"
          },
          "customer": {
            "href": "/api/v2/customers/1",
            "class": "customer"
          },
          "assigned_user": {
            "href": "/api/v2/users/2",
            "class": "user"
          },
          "assigned_group": {
            "href": "/api/v2/groups/1",
            "class": "group"
          },
          "locked_by": null,
          "replies": {
            "href": "/api/v2/cases/1/replies",
            "class": "reply"
          },
          "draft": {
            "href": "/api/v2/cases/1/replies/draft",
            "class": "reply"
          },
          "notes": {
            "href": "/api/v2/cases/1/notes",
            "class": "note"
          },
          "history": {
            "href": "/api/v2/cases/1/history",
            "class": "history"
          },
          "macro_preview": {
            "href": "/api/v2/cases/1/macros/preview",
            "class": "macro_preview"
          },
          "attachments": {
            "href": "/api/v2/cases/1/attachments",
            "class": "attachment"
          }
        }
      },
      {
        "id": 2,
        "external_id": null,
        "blurb": null,
        "subject": "Help Please!",
        "priority": 5,
        "locked_until": null,
        "description": null,
        "status": "new",
        "type": "email",
        "labels": [

        ],
        "label_ids": [

        ],
        "language": "en_us",
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:24:27Z",
        "changed_at": "2017-08-18T22:23:27Z",
        "active_at": "2017-08-18T22:24:27Z",
        "received_at": "2017-08-18T22:19:27Z",
        "first_opened_at": "2017-08-18T22:20:27Z",
        "opened_at": "2017-08-18T22:21:27Z",
        "first_resolved_at": "2017-08-18T22:24:27Z",
        "resolved_at": "2017-08-18T22:24:27Z",
        "custom_fields": {
          "level": "vip"
        },
        "_links": {
          "self": {
            "href": "/api/v2/cases/2",
            "class": "case"
          },
          "message": {
            "href": "/api/v2/cases/2/message",
            "class": "message"
          },
          "customer": {
            "href": "/api/v2/customers/1",
            "class": "customer"
          },
          "assigned_user": {
            "href": "/api/v2/users/2",
            "class": "user"
          },
          "assigned_group": {
            "href": "/api/v2/groups/1",
            "class": "group"
          },
          "locked_by": null,
          "replies": {
            "href": "/api/v2/cases/2/replies",
            "class": "reply"
          },
          "draft": {
            "href": "/api/v2/cases/2/replies/draft",
            "class": "reply"
          },
          "notes": {
            "href": "/api/v2/cases/2/notes",
            "class": "note"
          },
          "history": {
            "href": "/api/v2/cases/2/history",
            "class": "history"
          },
          "macro_preview": {
            "href": "/api/v2/cases/2/macros/preview",
            "class": "macro_preview"
          },
          "attachments": {
            "href": "/api/v2/cases/2/attachments",
            "class": "attachment"
          }
        }
      }
    ]
  }
}

Show

Retrieve a single case.

GET https://yoursite.desk.com/api/v2/cases/:id

  • id will generally be the value generated by Desk.com, but the external_id field can also be used when url encoded and prefaced with "e-". See the example curl request below.

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/1 \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
{
  "id": 1,
  "external_id": null,
  "blurb": null,
  "subject": "Welcome",
  "priority": 5,
  "locked_until": null,
  "description": null,
  "status": "new",
  "type": "email",
  "labels": [

  ],
  "label_ids": [

  ],
  "language": "en_us",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:24:27Z",
  "changed_at": "2017-08-18T22:23:27Z",
  "active_at": "2017-08-18T22:24:27Z",
  "received_at": "2017-08-18T22:19:27Z",
  "first_opened_at": "2017-08-18T22:20:27Z",
  "opened_at": "2017-08-18T22:21:27Z",
  "first_resolved_at": "2017-08-18T22:24:27Z",
  "resolved_at": "2017-08-18T22:24:27Z",
  "custom_fields": {
    "level": "vip"
  },
  "_links": {
    "self": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "message": {
      "href": "/api/v2/cases/1/message",
      "class": "message"
    },
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/2",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": null,
    "replies": {
      "href": "/api/v2/cases/1/replies",
      "class": "reply"
    },
    "draft": {
      "href": "/api/v2/cases/1/replies/draft",
      "class": "reply"
    },
    "notes": {
      "href": "/api/v2/cases/1/notes",
      "class": "note"
    },
    "history": {
      "href": "/api/v2/cases/1/history",
      "class": "history"
    },
    "macro_preview": {
      "href": "/api/v2/cases/1/macros/preview",
      "class": "macro_preview"
    },
    "attachments": {
      "href": "/api/v2/cases/1/attachments",
      "class": "attachment"
    }
  }
}

Example Curl Request with Encoded External ID

  • Querying with a url encoded external_id prefaced with "e-" will lookup a case on external_id instead of id.
1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/e-case%405-300 \
    -u email:password \
    -H 'Accept: application/json'

Example Response from Encoded External ID

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
{
  "id": 1,
  "external_id": "case@5-300",
  "blurb": null,
  "subject": "Welcome",
  "priority": 5,
  "locked_until": null,
  "description": null,
  "status": "new",
  "type": "email",
  "labels": [

  ],
  "label_ids": [

  ],
  "language": "en_us",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:24:27Z",
  "changed_at": "2017-08-18T22:23:27Z",
  "active_at": "2017-08-18T22:24:27Z",
  "received_at": "2017-08-18T22:19:27Z",
  "first_opened_at": "2017-08-18T22:20:27Z",
  "opened_at": "2017-08-18T22:21:27Z",
  "first_resolved_at": "2017-08-18T22:24:27Z",
  "resolved_at": "2017-08-18T22:24:27Z",
  "custom_fields": {
    "level": "vip"
  },
  "_links": {
    "self": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "message": {
      "href": "/api/v2/cases/1/message",
      "class": "message"
    },
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/2",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": null,
    "replies": {
      "href": "/api/v2/cases/1/replies",
      "class": "reply"
    },
    "draft": {
      "href": "/api/v2/cases/1/replies/draft",
      "class": "reply"
    },
    "notes": {
      "href": "/api/v2/cases/1/notes",
      "class": "note"
    },
    "history": {
      "href": "/api/v2/cases/1/history",
      "class": "history"
    },
    "macro_preview": {
      "href": "/api/v2/cases/1/macros/preview",
      "class": "macro_preview"
    },
    "attachments": {
      "href": "/api/v2/cases/1/attachments",
      "class": "attachment"
    }
  }
}

Example Request with draft embed

  • Querying with a url encoded external_id prefaced with "e-" will lookup a case on external_id instead of id.
1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/1?embed=draft \
    -u email:password \
    -H 'Accept: application/json'

Example Response with draft embed

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
{
  "id": 1,
  "external_id": null,
  "blurb": null,
  "subject": "Welcome",
  "priority": 5,
  "locked_until": null,
  "description": null,
  "status": "new",
  "type": "email",
  "labels": [

  ],
  "label_ids": [

  ],
  "language": "en_us",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:24:27Z",
  "changed_at": "2017-08-18T22:23:27Z",
  "active_at": "2017-08-18T22:24:27Z",
  "received_at": "2017-08-18T22:19:27Z",
  "first_opened_at": "2017-08-18T22:20:27Z",
  "opened_at": "2017-08-18T22:21:27Z",
  "first_resolved_at": "2017-08-18T22:24:27Z",
  "resolved_at": "2017-08-18T22:24:27Z",
  "custom_fields": {
    "level": "vip"
  },
  "_links": {
    "self": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "message": {
      "href": "/api/v2/cases/1/message",
      "class": "message"
    },
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/2",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": null,
    "replies": {
      "href": "/api/v2/cases/1/replies",
      "class": "reply"
    },
    "draft": {
      "href": "/api/v2/cases/1/replies/draft",
      "class": "reply"
    },
    "notes": {
      "href": "/api/v2/cases/1/notes",
      "class": "note"
    },
    "history": {
      "href": "/api/v2/cases/1/history",
      "class": "history"
    },
    "macro_preview": {
      "href": "/api/v2/cases/1/macros/preview",
      "class": "macro_preview"
    },
    "attachments": {
      "href": "/api/v2/cases/1/attachments",
      "class": "attachment"
    }
  },
  "_embedded": {
    "draft": {
      "subject": "Please help",
      "body": "Help me with my issue!",
      "direction": "in",
      "status": "pending",
      "to": "support@desk.com",
      "from": "john.doe@example.com",
      "cc": null,
      "bcc": null,
      "client_type": "desk_portal",
      "created_at": "2017-08-18T22:19:27Z",
      "updated_at": "2017-08-18T22:19:27Z",
      "hidden_at": null,
      "hidden": false,
      "_links": {
        "self": {
          "href": "/api/v2/cases/1/replies/1",
          "class": "email"
        },
        "case": {
          "href": "/api/v2/cases/1",
          "class": "case"
        },
        "customer": {
          "href": "/api/v2/customer/1",
          "class": "customer"
        },
        "hidden_by": null
      }
    }
  }
}

Create

A case is a collection of messages around an issue. There are two types of messages for a case: the original message that opened the case and the replies.

When creating a case, you must include the original message in the request body. The original message can be for the email, phone, qna, chat or twitter channel.

You may include a customer when creating a new case. There are two ways of linking a customer to a case:

  • Include a customer in the _links section of your request body. Example:
1
2
3
4
customer: {
  href: "/api/v2/customers/:customer_id",
  class: "customer"
}
  • Use the customer cases path when creating a case. Example:
1
2
3
4
5
6
7
bash
$ curl https://yoursite.desk.com/api/v2/customers/:customer_id/cases \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"type":"phone","subject":"Phone Case Subject","priority":4,"status":"open","labels": ["Spam", "Ignore"],"message":{"direction": "in", "body": "Example body"},"_links":{"assigned_group":{"class":"group","href":"/api/v2/groups/1"}}}'

If no customer is included, then you must provide an email address in the from field of the message. If a customer with the email address is found, the new case will be assigned to the customer. If not, a new customer with the provided email address will be created instead. You may also optionally provide a name for the new customer as a case field.

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

New Email Case

Case Fields

Please see Fields for details on case specific fields.

Message Fields

NOTE: You must provide a to, cc or bcc when creating email cases.

field name description
direction direction of the email, in for coming into the agent or out for sending out of the agent.
status email's current status, one of received, draft, pending, sent, or failed
body body of the message.
subject email's subject
from email's from address
to email's to address
cc email's cc address(es)
bcc email's bcc address(es)
created_at time of creation -- defaults to the current time.
updated_at time of update

Example Curl Request

1
2
3
4
5
6
7
bash
$ curl https://yoursite.desk.com/api/v2/cases \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"type":"email","subject":"Email Case Subject","priority":4,"status":"open","labels": ["Spam", "Ignore"],"message":{"direction": "in", "body": "Example body","to":"someone@desk.com","from":"someone-else@desk.com","subject":"My email subject"},"_links":{"customer":{"class":"customer","href":"/api/v2/customers/1"}}}'

Example Request (Inbound Email)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
  "type": "email",
  "subject": "Creating a case via the API",
  "priority": 4,
  "status": "open",
  "labels": [
    "Spam",
    "Ignore"
  ],
  "language": "fr",
  "created_at": "2012-05-01T21:38:48Z",
  "_links": {
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  },
  "message": {
    "direction": "in",
    "status": "received",
    "to": "someone@desk.com",
    "from": "someone-else@desk.com",
    "cc": "alpha@desk.com",
    "bcc": "beta@desk.com",
    "subject": "Creating a case via the API",
    "body": "Please assist me with this case",
    "created_at": "2012-05-02T21:38:48Z"
  }
}

Example Request (Outbound Email)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
  "type": "email",
  "subject": "Creating a case via the API",
  "priority": 4,
  "status": "open",
  "labels": [
    "Spam",
    "Ignore"
  ],
  "created_at": "2012-05-01T21:38:48Z",
  "_links": {
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  },
  "message": {
    "direction": "out",
    "status": "pending",
    "to": "someone@desk.com",
    "from": "someone-else@desk.com",
    "cc": "alpha@desk.com",
    "bcc": "beta@desk.com",
    "subject": "Creating a case via the API",
    "body": "Please assist me with this case",
    "created_at": "2012-05-02T21:38:48Z"
  }
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
{
  "id": 1,
  "external_id": null,
  "blurb": null,
  "subject": "Creating a case via the API",
  "priority": 4,
  "locked_until": null,
  "description": null,
  "status": "open",
  "type": "email",
  "labels": [
    "Spam",
    "Ignore"
  ],
  "label_ids": [

  ],
  "language": "fr",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:24:27Z",
  "changed_at": "2017-08-18T22:23:27Z",
  "active_at": "2017-08-18T22:24:27Z",
  "received_at": "2017-08-18T22:19:27Z",
  "first_opened_at": "2017-08-18T22:20:27Z",
  "opened_at": "2017-08-18T22:21:27Z",
  "first_resolved_at": "2017-08-18T22:24:27Z",
  "resolved_at": "2017-08-18T22:24:27Z",
  "custom_fields": {
    "level": "vip"
  },
  "_links": {
    "self": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "message": {
      "href": "/api/v2/cases/1/message",
      "class": "message"
    },
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "replies": {
      "href": "/api/v2/cases/1/replies",
      "class": "reply"
    },
    "draft": {
      "href": "/api/v2/cases/1/replies/draft",
      "class": "reply"
    },
    "notes": {
      "href": "/api/v2/cases/1/notes",
      "class": "note"
    },
    "history": {
      "href": "/api/v2/cases/1/history",
      "class": "history"
    },
    "macro_preview": {
      "href": "/api/v2/cases/1/macros/preview",
      "class": "macro_preview"
    },
    "attachments": {
      "href": "/api/v2/cases/1/attachments",
      "class": "attachment"
    }
  }
}

New Phone Case

Case Fields

Please see Fields for details on case specific fields.

Message Fields

field name description
direction direction of the phone call, in for coming into the agent or out for sending out of the agent.
body body of the message.
entered_at time the first phone interaction was entered -- defaults to the current time.

Links

Phone cases must be linked to an agent that entered the first phone interaction. You can either set the entered_by link or let it default to the current user making the API request.

Example Curl Request

1
2
3
4
5
6
7
bash
$ curl https://yoursite.desk.com/api/v2/cases \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"type":"phone","subject":"Phone Case Subject","priority":4,"status":"open","labels": ["Spam", "Ignore"],"message":{"direction": "in", "body": "Example body"},"_links":{"customer":{"class":"customer","href":"/api/v2/customers/1"}}}'

Example Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
  "type": "phone",
  "subject": "Creating a case via the API",
  "priority": 4,
  "status": "open",
  "labels": [
    "Spam",
    "Ignore"
  ],
  "_links": {
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "entered_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  },
  "message": {
    "direction": "out",
    "body": "Please assist me with this case"
  }
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
{
  "id": 1,
  "external_id": null,
  "blurb": null,
  "subject": "Welcome",
  "priority": 5,
  "locked_until": null,
  "description": null,
  "status": "new",
  "type": "phone",
  "labels": [

  ],
  "label_ids": [

  ],
  "language": "en_us",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:24:27Z",
  "changed_at": "2017-08-18T22:23:27Z",
  "active_at": "2017-08-18T22:24:27Z",
  "received_at": "2017-08-18T22:19:27Z",
  "first_opened_at": "2017-08-18T22:20:27Z",
  "opened_at": "2017-08-18T22:21:27Z",
  "first_resolved_at": "2017-08-18T22:24:27Z",
  "resolved_at": "2017-08-18T22:24:27Z",
  "custom_fields": {
    "level": "vip"
  },
  "_links": {
    "self": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "message": {
      "href": "/api/v2/cases/1/message",
      "class": "message"
    },
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/2",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": null,
    "replies": {
      "href": "/api/v2/cases/1/replies",
      "class": "reply"
    },
    "draft": {
      "href": "/api/v2/cases/1/replies/draft",
      "class": "reply"
    },
    "notes": {
      "href": "/api/v2/cases/1/notes",
      "class": "note"
    },
    "history": {
      "href": "/api/v2/cases/1/history",
      "class": "history"
    },
    "macro_preview": {
      "href": "/api/v2/cases/1/macros/preview",
      "class": "macro_preview"
    },
    "attachments": {
      "href": "/api/v2/cases/1/attachments",
      "class": "attachment"
    }
  }
}

New QNA Case

Case Fields

Please see Fields for details on case specific fields.

Message Fields

field name description
subject subject of the question
body body of the question

Links

QNA cases must link to a Topic for which the question is being asked.

Multi-Brand Customers NOTE: If your site uses multiple brands, you will also need to link to the brands for which the QNA will be associated.

Example Curl Request

1
2
3
4
5
6
7
bash
$ curl https://yoursite.desk.com/api/v2/cases \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"type":"qna","subject":"Case subject","priority":4,"status":"open","labels": ["QNA"],"message":{"subject": "Example subject", "body": "Example body", "_links": { "topic": { "href": "/api/v2/topics/1", "class": "topic" }}},"_links":{"customer":{"class":"customer","href":"/api/v2/customers/1"}}}'

Example Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
  "type": "qna",
  "subject": "Creating a QNA case via the API",
  "priority": 4,
  "status": "open",
  "labels": [
    "QNA"
  ],
  "_links": {
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "entered_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  },
  "message": {
    "subject": "How far is the moon from earth?",
    "body": "I'm trying to eyeball it, but nothing comes to mind. Do you know how far away it is?",
    "_links": {
      "topic": {
        "href": "/api/v2/topics/1",
        "class": "topic"
      }
    }
  }
}

Example Request (with Multiple Brands)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
{
  "type": "qna",
  "subject": "Creating a QNA case via the API",
  "priority": 4,
  "status": "open",
  "labels": [
    "QNA"
  ],
  "_links": {
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "entered_by": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  },
  "message": {
    "subject": "How far is the moon from earth?",
    "body": "I'm trying to eyeball it, but nothing comes to mind. Do you know how far away it is?",
    "_links": {
      "topic": {
        "href": "/api/v2/topics/1",
        "class": "topic"
      },
      "brands": [
        {
          "href": "/api/v2/brands/1",
          "class": "brand"
        },
        {
          "href": "/api/v2/brands/2",
          "class": "brand"
        },
        {
          "href": "/api/v2/brands/3",
          "class": "brand"
        }
      ]
    }
  }
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
{
  "id": 1,
  "external_id": null,
  "blurb": null,
  "subject": "Welcome",
  "priority": 5,
  "locked_until": null,
  "description": null,
  "status": "new",
  "type": "qna",
  "labels": [

  ],
  "label_ids": [

  ],
  "language": "en_us",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:24:27Z",
  "changed_at": "2017-08-18T22:23:27Z",
  "active_at": "2017-08-18T22:24:27Z",
  "received_at": "2017-08-18T22:19:27Z",
  "first_opened_at": "2017-08-18T22:20:27Z",
  "opened_at": "2017-08-18T22:21:27Z",
  "first_resolved_at": "2017-08-18T22:24:27Z",
  "resolved_at": "2017-08-18T22:24:27Z",
  "custom_fields": {
    "level": "vip"
  },
  "_links": {
    "self": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "message": {
      "href": "/api/v2/cases/1/message",
      "class": "message"
    },
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/2",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": null,
    "replies": {
      "href": "/api/v2/cases/1/replies",
      "class": "reply"
    },
    "draft": {
      "href": "/api/v2/cases/1/replies/draft",
      "class": "reply"
    },
    "notes": {
      "href": "/api/v2/cases/1/notes",
      "class": "note"
    },
    "history": {
      "href": "/api/v2/cases/1/history",
      "class": "history"
    },
    "macro_preview": {
      "href": "/api/v2/cases/1/macros/preview",
      "class": "macro_preview"
    },
    "attachments": {
      "href": "/api/v2/cases/1/attachments",
      "class": "attachment"
    }
  }
}

New Twitter Case

Case Fields

Please see Fields for details on case specific fields.

Message Fields

field name description
direction direction of the tweet, in for coming into the agent or out for sending out of the agent.
body body of the tweet.
tweet_type mention or dm. mention is a public tweet, dm is a private direct message between users. defaults to mention
status for outbound tweets; one of draft, pending_approval, pending, sent, or failed. defaults to pending, which will cause the tweet to be sent.

Links

Twitter cases must be linked to the Twitter Account used for sending the tweet, or to show which account received it for an inbound Twitter case.

Example Curl Request

1
2
3
4
5
6
7
bash
$ curl https://yoursite.desk.com/api/v2/cases \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"type":"twitter","subject":"@desk_dev we're using your API!","status":"open","message":{"direction": "out", "body": "@desk_dev we're using your API!", "status" : "pending"}, "_links": {"twitter_account": {"href": "/api/v2/twitter_accounts/1"}}}'

Example Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "type": "twitter",
  "subject": "@desk_dev we're using your API!",
  "status": "pending",
  "message": {
    "direction": "out",
    "body": "@desk_dev we're using your API!",
    "status": "pending",
    "_links": {
      "twitter_account": {
        "href": "/api/v2/twitter_accounts/1",
        "class": "twitter_account"
      }
    }
  },
  "_links": {
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    }
  }
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
{
  "id": 1,
  "external_id": null,
  "blurb": null,
  "subject": "@desk_dev we're using your API!",
  "priority": 5,
  "locked_until": null,
  "description": null,
  "status": "pending",
  "type": "twitter",
  "labels": [

  ],
  "label_ids": [

  ],
  "language": "en_us",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:24:27Z",
  "changed_at": "2017-08-18T22:23:27Z",
  "active_at": "2017-08-18T22:24:27Z",
  "received_at": "2017-08-18T22:19:27Z",
  "first_opened_at": "2017-08-18T22:20:27Z",
  "opened_at": "2017-08-18T22:21:27Z",
  "first_resolved_at": "2017-08-18T22:24:27Z",
  "resolved_at": "2017-08-18T22:24:27Z",
  "custom_fields": {
    "level": "vip"
  },
  "_links": {
    "self": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "message": {
      "href": "/api/v2/cases/1/message",
      "class": "message"
    },
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/2",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": null,
    "replies": {
      "href": "/api/v2/cases/1/replies",
      "class": "reply"
    },
    "draft": {
      "href": "/api/v2/cases/1/replies/draft",
      "class": "reply"
    },
    "notes": {
      "href": "/api/v2/cases/1/notes",
      "class": "note"
    },
    "history": {
      "href": "/api/v2/cases/1/history",
      "class": "history"
    },
    "macro_preview": {
      "href": "/api/v2/cases/1/macros/preview",
      "class": "macro_preview"
    },
    "attachments": {
      "href": "/api/v2/cases/1/attachments",
      "class": "attachment"
    },
    "twitter_account": {
      "href": "/api/v2/twitter_accounts/1",
      "class": "twitter_account"
    }
  }
}

New Chat Case

Case Fields

Please see Fields for details on case specific fields.

Message Fields

field name description
body body of the message
direction direction of the message

Example Curl Request

1
2
3
4
5
6
7
8
bash
$ curl https://yoursite.desk.com/api/v2/cases \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"type":"chat","subject":"Case subject","message":{"body": "Example body",
       "direction":"in"}, "_links":{"customer":{class:"customer",href:"/api/v2/customers/43"}}}'

Example Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "type": "chat",
  "subject": "Case Subject",
  "priority": 4,
  "status": "open",
  "message": {
    "direction": "out",
    "body": "Example body"
  },
  "_links": {
    "customer": {
      "href": "/api/v2/customers/43",
      "class": "customer"
    }
  }
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
{
  "id": 30,
  "external_id": null,
  "blurb": null,
  "subject": "Case Subject",
  "priority": 4,
  "locked_until": null,
  "description": null,
  "status": "open",
  "type": "chat",
  "labels": [

  ],
  "label_ids": [

  ],
  "language": "en",
  "active_at": null,
  "created_at": "2014-05-14T19:18:05Z",
  "updated_at": "2014-05-14T19:18:05Z",
  "received_at": null,
  "first_opened_at": null,
  "opened_at": null,
  "first_resolved_at": null,
  "resolved_at": null,
  "custom_fields": {
  },
  "_links": {
    "self": {
      "href": "/api/v2/cases/30",
      "class": "case"
    },
    "message": {
      "href": "/api/v2/cases/30/message",
      "class": "chat"
    },
    "customer": {
      "href": "/api/v2/customers/43",
      "class": "customer"
    },
    "labels": {
      "href": "/api/v2/cases/30/labels",
      "class": "label"
    },
    "assigned_user": null,
    "assigned_group": null,
    "locked_by": null,
    "history": {
      "href": "/api/v2/cases/30/history",
      "class": "history"
    },
    "case_links": {
      "href": "/api/v2/cases/30/links",
      "class": "case_link"
    },
    "macro_preview": {
      "href": "/api/v2/cases/30/macros/preview",
      "class": "macro_preview"
    },
    "replies": {
      "href": "/api/v2/cases/30/replies",
      "class": "reply",
      "count": 0
    },
    "draft": {
      "href": "/api/v2/cases/30/replies/draft",
      "class": "reply"
    },
    "notes": {
      "href": "/api/v2/cases/30/notes",
      "class": "note",
      "count": 0
    },
    "attachments": {
      "href": "/api/v2/cases/30/attachments",
      "class": "attachment",
      "count": 0
    }
  }
}

Update

Update a case that is not locked by another user.

PATCH https://yoursite.desk.com/api/v2/cases/:id

  • id will generally be the value generated by Desk.com, but the external_id field can also be used when url encoded and prefaced with "e-". See the example curl request below.

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

field name description
external_id External identifier to reference this case. Must be unique.
subject Subject of the case
priority Priority of the case (1-10)
locked_until If set, automatically expire the locked_by link at this time to release the lock and allow other users to update this case.
description Description of the case
status Status of the case: new, open, pending, resolved, closed
label_action Whether to append or replace the labels (see below). The default is append.
labels An array of labels to associate with this case. An empty array (using a label_action of replace) will clear all labels from the case.
custom_fields Values for case custom fields. Pass a hash of custom field names and values.
created_at Time of creation
updated_at Time of last modification

Links

name description
assigned_user Assigned user to this case. User must be a member of the assigned group.
macros Array of macro links to add to case history.
assigned_group Assigned group to this case.
locked_by User that this case is locked to. Any update attempts from other users will fail as long as this case is locked.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/:id \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"subject":"Updated Subject","_links":{"assigned_group":{"class":"group","href":"/api/v2/groups/1"}}}'

Example Curl Request with macros

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/:id \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"subject":"Updated Subject","_links":{"macros":[{"class":"macro","href":"/api/v2/macros/1"},{"class":"macro","href":"/api/v2/macros/2"}]}}'

Example Request Body

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "subject": "Updated",
  "status": "pending",
  "labels": [
    "Spam",
    "Test"
  ],
  "label_action": "replace",
  "custom_fields": {
    "level": "super"
  },
  "_links": {
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    }
  }
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
{
  "id": 1,
  "external_id": null,
  "blurb": null,
  "subject": "Updated",
  "priority": 5,
  "locked_until": null,
  "description": null,
  "status": "pending",
  "type": "email",
  "labels": [
    "Spam",
    "Test"
  ],
  "label_ids": [

  ],
  "language": "en_us",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:24:27Z",
  "changed_at": "2017-08-18T22:23:27Z",
  "active_at": "2017-08-18T22:24:27Z",
  "received_at": "2017-08-18T22:19:27Z",
  "first_opened_at": "2017-08-18T22:20:27Z",
  "opened_at": "2017-08-18T22:21:27Z",
  "first_resolved_at": "2017-08-18T22:24:27Z",
  "resolved_at": "2017-08-18T22:24:27Z",
  "custom_fields": {
    "level": "super"
  },
  "_links": {
    "self": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "message": {
      "href": "/api/v2/cases/1/message",
      "class": "message"
    },
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/2",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": null,
    "replies": {
      "href": "/api/v2/cases/1/replies",
      "class": "reply"
    },
    "draft": {
      "href": "/api/v2/cases/1/replies/draft",
      "class": "reply"
    },
    "notes": {
      "href": "/api/v2/cases/1/notes",
      "class": "note"
    },
    "history": {
      "href": "/api/v2/cases/1/history",
      "class": "history"
    },
    "macro_preview": {
      "href": "/api/v2/cases/1/macros/preview",
      "class": "macro_preview"
    },
    "attachments": {
      "href": "/api/v2/cases/1/attachments",
      "class": "attachment"
    }
  }
}

Example Response with macros

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
{
  "id": 1,
  "external_id": null,
  "blurb": null,
  "subject": "Updated",
  "priority": 5,
  "locked_until": null,
  "description": null,
  "status": "pending",
  "type": "email",
  "labels": [
    "Spam",
    "Test"
  ],
  "label_ids": [

  ],
  "language": "en_us",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:24:27Z",
  "changed_at": "2017-08-18T22:23:27Z",
  "active_at": "2017-08-18T22:24:27Z",
  "received_at": "2017-08-18T22:19:27Z",
  "first_opened_at": "2017-08-18T22:20:27Z",
  "opened_at": "2017-08-18T22:21:27Z",
  "first_resolved_at": "2017-08-18T22:24:27Z",
  "resolved_at": "2017-08-18T22:24:27Z",
  "custom_fields": {
    "level": "super"
  },
  "_links": {
    "self": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "message": {
      "href": "/api/v2/cases/1/message",
      "class": "message"
    },
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/2",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": null,
    "replies": {
      "href": "/api/v2/cases/1/replies",
      "class": "reply"
    },
    "draft": {
      "href": "/api/v2/cases/1/replies/draft",
      "class": "reply"
    },
    "notes": {
      "href": "/api/v2/cases/1/notes",
      "class": "note"
    },
    "history": {
      "href": "/api/v2/cases/1/history",
      "class": "history"
    },
    "macro_preview": {
      "href": "/api/v2/cases/1/macros/preview",
      "class": "macro_preview"
    },
    "attachments": {
      "href": "/api/v2/cases/1/attachments",
      "class": "attachment"
    },
    "macros": [
      {
        "href": "/api/v2/macros/1",
        "class": "macro"
      }
    ]
  }
}

Example Curl Request with Encoded External ID

  • Querying with a url encoded external_id prefaced with "e-" will lookup a case on external_id instead of id.
1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/e-case%405-300 \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"subject":"Updated Subject","_links":{"assigned_group":{"class":"group","href":"/api/v2/groups/1"}}}'

Example Response from Encoded External ID

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
{
  "id": 1,
  "external_id": "case@5-300",
  "blurb": null,
  "subject": "Welcome",
  "priority": 5,
  "locked_until": null,
  "description": null,
  "status": "new",
  "type": "email",
  "labels": [

  ],
  "label_ids": [

  ],
  "language": "en_us",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:24:27Z",
  "changed_at": "2017-08-18T22:23:27Z",
  "active_at": "2017-08-18T22:24:27Z",
  "received_at": "2017-08-18T22:19:27Z",
  "first_opened_at": "2017-08-18T22:20:27Z",
  "opened_at": "2017-08-18T22:21:27Z",
  "first_resolved_at": "2017-08-18T22:24:27Z",
  "resolved_at": "2017-08-18T22:24:27Z",
  "custom_fields": {
    "level": "vip"
  },
  "_links": {
    "self": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "message": {
      "href": "/api/v2/cases/1/message",
      "class": "message"
    },
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/2",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": null,
    "replies": {
      "href": "/api/v2/cases/1/replies",
      "class": "reply"
    },
    "draft": {
      "href": "/api/v2/cases/1/replies/draft",
      "class": "reply"
    },
    "notes": {
      "href": "/api/v2/cases/1/notes",
      "class": "note"
    },
    "history": {
      "href": "/api/v2/cases/1/history",
      "class": "history"
    },
    "macro_preview": {
      "href": "/api/v2/cases/1/macros/preview",
      "class": "macro_preview"
    },
    "attachments": {
      "href": "/api/v2/cases/1/attachments",
      "class": "attachment"
    }
  }
}

Case Locking

We provide the ability to lock cases in order to prevent multiple agents from submitting responses or otherwise updating a case. Once locked, only the agent who holds the lock may update the case. If a case is locked and another agent tries to update the case, they will receive a 409 - Conflict response.

Locking a Case

Locking a case is done by setting the locked_by to an agent.

1
2
3
4
5
6
7
{
  "_links": {
    "locked_by": {
      "href": "/api/v2/users/1"
    }
  }
}

Unlocking a Case

Unlocking a case is done by setting the locked_by link to null.

1
2
3
4
5
{
  "_links": {
    "locked_by": null
  }
}

Delete Case

Delete a case from the Desk.com can be done by using the DELETE method on an HTTP request.

Delete a case

DELETE https://yoursite.desk.com/api/v2/cases/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

The user that call is made on behalf of needs to have the permission to delete a case. The delete permission can be set in the admin.

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/cases/:id \
    -u email:password \
    -X DELETE \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Example Response

1
204 No Content

If there is a problem that occurred with the delete, the response status will be:

1
422 Unprocessable Entity

Case Undeleting

You can undelete a deleted case by sending a PATCH request for a deleted case. This will undelete a case and revert the status back to its previous status. You can also provide a new status value; refer to case fields. This request will ignore any other attribute updates included in the same request. If an invalid status value is provided, it will be ignored and you will receive a 422 - Unprocessable Entity response.


Forward Case

Forward a case and all attachments to 1 or more email addresses

POST https://yoursite.desk.com/api/v2/cases/:id/forward

Fields

field name description
to comma separated list of email addresses
note_text (optional) text to also create a new Case Note

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/:id/forward \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"to":"doe.john@example.com,doe.jane@example.com","note_text":"example note"}'

Example Response

1
201 Created

If there is a problem that occurred with the forward, the response status will be:

1
422 Unprocessable Entity

Route Case

Automatically choose the next case an agent should work on. By default, Desk.com will choose the most important case for the agent, based on a combination of case priority and other factors. An optional filter_id can be provided, which will route all cases in that filter, sorted by its default sort_direction and sort_field. After a case is routed, locked_by and locked_until should be set on the case to indicate that the user has accepted it.

POST https://yoursite.desk.com/api/v2/cases/routing

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

field name description
user_routing_status Routing status. One of online, offline, or busy. Cases will only be routed if set to online.
filter_id optional Filter id to use for routing instead of using the default routing algorithm.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/routing \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"user_routing_status":"online"}'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
{
  "id": 1,
  "external_id": null,
  "blurb": null,
  "subject": "Welcome",
  "priority": 5,
  "locked_until": null,
  "description": null,
  "status": "new",
  "type": "email",
  "labels": [

  ],
  "label_ids": [

  ],
  "language": "en_us",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:24:27Z",
  "changed_at": "2017-08-18T22:23:27Z",
  "active_at": "2017-08-18T22:24:27Z",
  "received_at": "2017-08-18T22:19:27Z",
  "first_opened_at": "2017-08-18T22:20:27Z",
  "opened_at": "2017-08-18T22:21:27Z",
  "first_resolved_at": "2017-08-18T22:24:27Z",
  "resolved_at": "2017-08-18T22:24:27Z",
  "custom_fields": {
    "level": "vip"
  },
  "_links": {
    "self": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "message": {
      "href": "/api/v2/cases/1/message",
      "class": "message"
    },
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/2",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": null,
    "replies": {
      "href": "/api/v2/cases/1/replies",
      "class": "reply"
    },
    "draft": {
      "href": "/api/v2/cases/1/replies/draft",
      "class": "reply"
    },
    "notes": {
      "href": "/api/v2/cases/1/notes",
      "class": "note"
    },
    "history": {
      "href": "/api/v2/cases/1/history",
      "class": "history"
    },
    "macro_preview": {
      "href": "/api/v2/cases/1/macros/preview",
      "class": "macro_preview"
    },
    "attachments": {
      "href": "/api/v2/cases/1/attachments",
      "class": "attachment"
    }
  }
}

Unsend Case

Undo a recently sent interaction using the POST method. You have 10 seconds from the time you send the interaction to issue an unsend request.

After issuing a successful request, the interaction will be in a draft status.

Undo Sent Interactions must be enabled in the admin.

POST https://yoursite.desk.com/api/v2/cases/:id/unsend

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Note You may only issue an unsend request for a case that you have locked.

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/cases/:id/unsend \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
{
  "id": 1,
  "external_id": null,
  "blurb": null,
  "subject": "Welcome",
  "priority": 5,
  "locked_until": null,
  "description": null,
  "status": "new",
  "type": "email",
  "labels": [

  ],
  "label_ids": [

  ],
  "language": "en_us",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:24:27Z",
  "changed_at": "2017-08-18T22:23:27Z",
  "active_at": "2017-08-18T22:24:27Z",
  "received_at": "2017-08-18T22:19:27Z",
  "first_opened_at": "2017-08-18T22:20:27Z",
  "opened_at": "2017-08-18T22:21:27Z",
  "first_resolved_at": "2017-08-18T22:24:27Z",
  "resolved_at": "2017-08-18T22:24:27Z",
  "custom_fields": {
    "level": "vip"
  },
  "_links": {
    "self": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "message": {
      "href": "/api/v2/cases/1/message",
      "class": "message"
    },
    "customer": {
      "href": "/api/v2/customers/1",
      "class": "customer"
    },
    "assigned_user": {
      "href": "/api/v2/users/2",
      "class": "user"
    },
    "assigned_group": {
      "href": "/api/v2/groups/1",
      "class": "group"
    },
    "locked_by": null,
    "replies": {
      "href": "/api/v2/cases/1/replies",
      "class": "reply"
    },
    "draft": {
      "href": "/api/v2/cases/1/replies/draft",
      "class": "reply"
    },
    "notes": {
      "href": "/api/v2/cases/1/notes",
      "class": "note"
    },
    "history": {
      "href": "/api/v2/cases/1/history",
      "class": "history"
    },
    "macro_preview": {
      "href": "/api/v2/cases/1/macros/preview",
      "class": "macro_preview"
    },
    "attachments": {
      "href": "/api/v2/cases/1/attachments",
      "class": "attachment"
    }
  }
}

Message Fields

Message objects have the following fields and links:

Common Fields

field name description
direction direction of the reply, in for coming into the agent or out for sending out of the agent
body body of the reply
created_at time of creation
updated_at time last updated
suppress_rules set to true to disable rule processing when creating or updating this message

Email Fields

field name description
status email's current status, one of received, pending, sent, or failed
subject email's subject
from email's from address
to email's to address
cc email's cc address(es)
bcc email's bcc address(es)
client_type email's client name that originated the email (ie. 'desk_portal' and 'desk_widget' represent emails from the customer support center)

The following additional email fields are available on request by using the fields request parameter:

field name description
headers email's parsed headers
headers_raw email's raw header string
body_text the plaintext version of the email body
body_html the HTML version of the email body, if available

Tweet Fields

field name description
type type of tweet, mention for mentions or dm for direct messages
to if type is dm, this is the receiver's twitter username
from sender's twitter username
status Tweet's current status: can be one of received, draft, pending, sent, or failed
twitter_status_id id of the tweet, as a string

Facebook Message/Post Fields

field name description
status comment's current status, one of received, draft, pending, sent, or failed
from_facebook_name sender's facebook username

Community Question Fields

field name description
subject The question's subject
answers_disallowed_at Time when community answers were disallowed or 'null'
are_answers_disallowed Whether or not this question allows community answers
agent_answer_count Number of answers by agents
customer_answer_count Number of answers by customers
public_url The publicly accessible location of this question
hidden Whether or not this question and answer thread is hidden
hidden_at When this question and answer thread was hidden

Links

Community Question Links

name class description embeddable?
answers_disallowed_by user user who disallowed community answers for the question no
topic topic topic this community question belongs to no

Facebook Message/Post Links

name class description embeddable?
facebook_feed facebook_feed the Facebook Feed to which this message was posted no

Show Message

Retrieve the original message for this case. Depending on the case's channel, this message will be a chat, community_question, email, facebook_message, facebook_post, phone_call, or tweet object. All messages share a set of common fields, along with some channels having additional fields noted below.

If the message is an email, some additional fields are available on request (not by default) via the fields request parameter. These are: headers (a parsed version of the email headers), headers_raw, body_text and body_html.

GET https://yoursite.desk.com/api/v2/cases/:case_id/message

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/message \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "subject": "Please help",
  "body": "Help me with my issue!",
  "direction": "in",
  "status": "pending",
  "to": "support@desk.com",
  "from": "john.doe@example.com",
  "cc": null,
  "bcc": null,
  "client_type": "desk_portal",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "hidden_at": null,
  "hidden": false,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/message",
      "class": "email"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "customer": {
      "href": "/api/v2/customer/1",
      "class": "customer"
    },
    "hidden_by": null
  }
}

Update Message

You can perform actions on some types of messages. Actions can only be performed on sent messages. If you are performing an action, you cannot simultaneously update the attributes of the message.

Draft (unsent) messages can be updated many times. Once a message has transitioned to something other than draft status, then it can no longer be updated*.

* The one exception to this is hiding. Depending on the channel, messages may be hidden / unhidden via the boolean hidden param.

Channel Hide
email Yes (boolean)
community question Yes (boolean)
community answer Yes (boolean)
chat No
phone No
twitter No
facebook No

NOTE: If the case is locked by another user the request will fail with a 409 - Conflict response.

PATCH https://yoursite.desk.com/api/v2/cases/:case_id/message

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Community Question Fields

field name description
disallow_community_answers Whether or not to disallow community answers for this question

Tweet Fields

field name description
action_type Perform an action on the tweet. Can only perform actions on sent messages. Can be either retweet or favorite.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/message \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"hidden":"true"}'

Example Request Body

1
2
3
{
  "hidden": "true"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "subject": "Re: Please help",
  "body": "Message body",
  "direction": "out",
  "status": "received",
  "to": "doe.john@example.com",
  "from": "john.doe@example.com",
  "cc": null,
  "bcc": null,
  "client_type": "desk_portal",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "hidden_at": "2014-01-03T13:24:54Z",
  "hidden": "true",
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/replies/1",
      "class": "email"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "customer": {
      "href": "/api/v2/customer/1",
      "class": "customer"
    },
    "hidden_by": null
  }
}

Delete Message

Delete a message.

For a Twitter message, the tweet will also be deleted from Twitter.

For a Facebook post, all comments will also be deleted.

NOTE: This is not reversable!

Delete a message

DELETE https://yoursite.desk.com/api/v2/cases/:case_id/message

Applicable Channels

Email, Phone, Twitter, Facebook

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/message
    -u email:password \
    -X DELETE \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Example Response

1
204 No Content

Reply Fields

Reply objects have the following fields and links:

Common Fields

field name description
direction Direction of the reply, in for coming into the agent or out for sending out of the agent.
body Body of the reply.
created_at time of creation
updated_at time last updated
sent_at time an outbound reply was sent. nil for inbound replies and all chat replies.
suppress_rules set to true to disable rule processing when creating or updating this reply

Common Links

name class description embeddable?
self email, tweet, community_answer, facebook_comment, facebook_message, chat, or phone_call type of reply no
case case the case for the reply yes
sent_by user the user who sent the reply yes

Email Fields

field name description
status email's current status, one of received, draft, pending, sent, or failed
subject email's subject
from email's from address
to email's to address
cc email's cc address(es)
bcc email's bcc address(es)
client_type email's client name that originated the email (ie. 'desk_portal' and 'desk_widget' represent emails from the customer support center)

The following additional email fields are available on request by using the fields request parameter:

field name description
headers email's parsed headers
headers_raw email's raw header string
body_text the plaintext version of the email body
body_html the HTML version of the email body, if available

Facebook Comment/Message Fields

field name description
status comment's current status, one of received, draft, pending, sent, or failed
from_facebook_name Sender's facebook username
liked Whether or not this comment or post has been liked. Can be true or false.

Facebook Comment/Message Links

name type description embeddable?
facebook_feed facebook_feed the Facebook Feed to which this reply was posted yes

Tweet Fields

field name description
type Type of tweet, mention for mentions or dm for direct messages
to If type is dm, this is the receiver's twitter username
from Sender's twitter username
status Tweet's current status: can be one of received, draft, pending, sent, or failed

Phone Fields

field name description
entered_at Time the phone reply was entered
status Status of the phone reply. One of sent, received or draft.

Phone Links

name class description embeddable?
entered_by user Agent user that entered the reply yes

Community Answer Fields

field name description
from Name of the user that provided this answer
public_url The public-facing URL for this question
is_best_answer Whether or not this answer has been marked as the best one. Can be true or false.
rating The percentage of people who found the article helpful
rating_count The number of ratings given to the article
rating_score The number of people who found the article helpful
hidden Whether or not this question and answer reply is hidden
hidden_at Time when this answer was hidden from the support center
hidden_by The user who hid the reply

Community Answer Links

name class description embeddable?
customer customer Customer voting on the answer yes
topic topic Topic this answer belongs to no

Chat Links

name class description embeddable?
created_by user The user who sent this chat message yes

List Replies

Retrieve a paginated list of all replies for this case. Depending on the case's channel, replies will be a collection of chat_message, community_answer, email, facebook_comment, facebook_message, phone_call, or tweet objects. All replies share a set of common fields, along with some channels having additional details noted below.

GET https://yoursite.desk.com/api/v2/cases/:case_id/replies

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Sorting

Sorting is supported on replies in a filter by using sort_field and sort_direction parameters in your request.

  • sort_field - reply field on which you would like to sort
  • sort_direction - direction to sort - asc for ascending, desc for descending

The following fields can be used for sorting replies: created_at, and updated_at.

Etags

The Case Replies List endpoint has support for ETags. See ETag Caching for details.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/replies \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/replies?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/cases/1/replies?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/cases/1/replies?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "subject": "Please help",
        "body": "Help me with my issue!",
        "direction": "in",
        "status": "pending",
        "to": "support@desk.com",
        "from": "john.doe@example.com",
        "cc": null,
        "bcc": null,
        "client_type": "desk_portal",
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:19:27Z",
        "hidden_at": null,
        "hidden": false,
        "_links": {
          "self": {
            "href": "/api/v2/cases/1/replies/1",
            "class": "email"
          },
          "case": {
            "href": "/api/v2/cases/1",
            "class": "case"
          },
          "customer": {
            "href": "/api/v2/customer/1",
            "class": "customer"
          },
          "hidden_by": null
        }
      },
      {
        "subject": "Re: Please help",
        "body": "Thanks for your question. The answer is 42.",
        "direction": "out",
        "status": "pending",
        "to": "doe.john@example.com",
        "from": "john.doe@example.com",
        "cc": null,
        "bcc": null,
        "client_type": "desk_portal",
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:19:27Z",
        "hidden_at": null,
        "hidden": false,
        "_links": {
          "self": {
            "href": "/api/v2/cases/1/replies/2",
            "class": "email"
          },
          "case": {
            "href": "/api/v2/cases/1",
            "class": "case"
          },
          "customer": {
            "href": "/api/v2/customer/1",
            "class": "customer"
          },
          "hidden_by": null
        }
      }
    ]
  }
}

Show Reply

Retrieve a reply for this case. Depending on the case's channel, the reply will be an email, tweet, phone_call, community_answer, facebook_comment, facebook_message, or chat. All replies share a set of common fields, along with some channels having additional fields noted below.

If the reply is an email, some additional fields are available on request (not by default) via the fields request parameter. These are: headers (a parsed version of the email headers), headers_raw, body_text and body_html.

NOTE: chat cases do not have draft replies

GET https://yoursite.desk.com/api/v2/cases/:case_id/replies/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/replies/:id \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "subject": "Re: Please help",
  "body": "Thanks for your question. The answer is 42.",
  "direction": "out",
  "status": "pending",
  "to": "doe.john@example.com",
  "from": "john.doe@example.com",
  "cc": null,
  "bcc": null,
  "client_type": "desk_portal",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "hidden_at": null,
  "hidden": false,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/replies/2",
      "class": "email"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "customer": {
      "href": "/api/v2/customer/1",
      "class": "customer"
    },
    "hidden_by": null
  }
}

Create Reply

Create a reply for the given case. Depending on the case's channel, a reply can be a email, tweet, phone_call, community_answer, facebook_comment, facebook_message, or chat. All replies share a set of common fields, along with some channels having additional fields noted below.

NOTE: If the case is locked by another user the request will fail with a 409 - Conflict response.

NOTE: If the site is configured to set a case's status to pending when a reply is sent, then creating a reply will set the status of its case to pending.

POST https://yoursite.desk.com/api/v2/cases/:id/replies

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Common Fields

field name description
body Body of the reply.
direction in or out. in is only currently supported for email, community_answer, and chat replies.
status Status can be draft, pending, or sent. Default is pending. Applies to email, tweet, facebook_comment, and facebook_message replies only. Using draft will create the reply as a drafted reply. Setting the status to pending will queue the reply to be sent. Using sent will add the reply to the case but will not actually send the reply. For phone and community_answer, see below.
created_at Time of reply creation. Defaults to the current time.
updated_at Time of reply modification.

Community Answer Fields

field name description
subject Subject of the reply.
status Status can be draft, pending or sent. Default is sent. Using pending or sent will both post the reply to the case and will display on the support center unless hidden.

Email Links

name description
outbound_mailbox Outbound mailbox that will be used for the from and reply_to address.

Community Answer Links

Inbound Community Answers should be linked to the customer who created the answer. If not, the answer creator will default to the current user making the API request.

Tweet Fields

field name description
type Type of tweet, mention for mentions or dm for direct messages.

A 422 response will be returned if a DM is sent to a handle when a mutual friendship does not exist.

Phone Fields

field name description
entered_at Time the phone reply was entered. Defaults to the current time.
status Status can be draft or sent. Default is sent. Passing draft will override any value sent for entered_at with the current time.

Phone Links

Phone replies must be linked to an agent that entered the reply. You can either set the entered_by link or let it default to the current user making the API request.

Validation Codes

code description
no_outbound_mailbox No Outbound Mailbox has been setup for the site. This is required to send email case replies.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/:id/replies \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"body":"My Reply", "direction":"out"}'

Request with an outbound mailbox link:

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/:id/replies \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"body":"My Reply", "direction":"out","_links":{"outbound_mailbox":{"class":"outbound_mailbox","href":"/api/v2/mailboxes/outbound/1"}}}'

Example Request Body

1
2
3
{
  "body": "My Reply"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "subject": "Re: Please help",
  "body": "My Reply",
  "direction": "out",
  "status": "pending",
  "to": "doe.john@example.com",
  "from": "john.doe@example.com",
  "cc": null,
  "bcc": null,
  "client_type": "desk_portal",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "hidden_at": null,
  "hidden": false,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/replies/1",
      "class": "email"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "customer": {
      "href": "/api/v2/customer/1",
      "class": "customer"
    },
    "hidden_by": null
  }
}

Update Reply

You can perform actions on some types of replies. Actions can only be performed on sent replies.

Draft replies can be updated many times. Once a reply has transitioned to something other than draft status, then it can no longer be updated*.

* The one exception to this is hiding. Non-draft replies cannot be updated, but depending on the channel, they may be hidden / unhidden.

Channel Hide
email Yes (boolean)
phone No
chat No
facebook No
community question Yes (boolean)
community answer Yes (boolean)

NOTE: If the case is locked by another user the request will fail with a 409 - Conflict response.

PATCH https://yoursite.desk.com/api/v2/cases/:case_id/replies/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Tweet Fields

In addition to the default fields:

field name description
action_type Perform an action on the tweet. Can only perform actions on published replies. Can be either retweet or favorite.

Facebook Fields

In addition to the default fields:

field_name description
action_type Perform an action on a sent reply. Can be either like or unlike.

Community Answer Fields

In addition to the default fields:

field name description
rating The vote given to the answer by a customer. 1 is a positive vote, 0 is a negative vote. This requires a link to the customer.
is_best_answer Set (true) or unset (false) an answer as the best answer. Setting a best answer will unset a previously set best answer.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/replies/:id \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"body":"Updated reply body", "cc": "new.email@example.com"}'

Example Request Body

1
2
3
4
{
  "body": "Updated reply body",
  "cc": "new.email@example.com"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "subject": "Re: Please help",
  "body": "Updated reply body",
  "direction": "out",
  "status": "draft",
  "to": "doe.john@example.com",
  "from": "john.doe@example.com",
  "cc": "new.email@example.com",
  "bcc": null,
  "client_type": "desk_portal",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "hidden_at": null,
  "hidden": false,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/replies/1",
      "class": "email"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "customer": {
      "href": "/api/v2/customer/1",
      "class": "customer"
    },
    "hidden_by": null
  }
}

Draft Definition

A draft is defined as any outbound interaction that has not been sent. For most interactions, the draft is usually a reply. But there are a few instances where the message can be a draft, such as creating a new email or phone case.

This means most API endpoints that refer to a draft (/api/v2/cases/:case_id/replies/draft for example) will not find a draft message, and vice versa. There is a generic draft endpoint that implements a few common functions.


Delete Reply

Delete a reply.

Reply drafts do not set erased_at or erased_by when deleted. All other delete requests will set erased_at and erased_by.

Reply drafts may be deleted by any user, regardless of role.

For a Twitter reply, the tweet will also be deleted from Twitter.

NOTE: This is not reversable!

Delete a reply

DELETE https://yoursite.desk.com/api/v2/cases/:case_id/replies/:id

Applicable Channels

Email, Phone, Twitter, Facebook

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/replies/:id \
    -u email:password \
    -X DELETE \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Example Response

1
204 No Content

Show Draft

Retrieve the draft for this case. Depending on the case's channel, the draft will be an email, tweet, phone_call, community_answer, facebook_comment, or facebook_message. All drafts share a set of common fields, along with some channels having additional fields noted below.

GET https://yoursite.desk.com/api/v2/cases/:case_id/replies/draft

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Administrator, Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/replies/draft \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "subject": "Re: Please help",
  "body": "A draft.",
  "direction": "out",
  "status": "pending",
  "to": "doe.john@example.com",
  "from": "john.doe@example.com",
  "cc": null,
  "bcc": null,
  "client_type": "desk_portal",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "hidden_at": null,
  "hidden": false,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/replies/2",
      "class": "email"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "customer": {
      "href": "/api/v2/customer/1",
      "class": "customer"
    },
    "hidden_by": null
  }
}

Update Draft

Draft replies can be updated many times. Once a reply has transitioned to something other than draft status, then it can no longer be updated.

NOTE: If the case is locked by another user the request will fail with a 409 - Conflict response.

PATCH https://yoursite.desk.com/api/v2/cases/:case_id/replies/draft

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/replies/draft \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"body":"Updated reply body", "cc": "new.email@example.com"}'

Example Request Body

1
2
3
4
{
  "body": "Updated draft body",
  "cc": "new.email@example.com"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "subject": "Re: Please help",
  "body": "Updated draft body",
  "direction": "out",
  "status": "draft",
  "to": "doe.john@example.com",
  "from": "john.doe@example.com",
  "cc": "new.email@example.com",
  "bcc": null,
  "client_type": "desk_portal",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "hidden_at": null,
  "hidden": false,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/replies/1",
      "class": "email"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "customer": {
      "href": "/api/v2/customer/1",
      "class": "customer"
    },
    "hidden_by": null
  }
}

Create Draft

Create a reply draft for the given case. Depending on the case's channel, a draft can be a email, tweet, phone_call, community_answer, facebook_comment, or facebook_message. All drafts share a set of common fields, along with some channels having additional fields noted below.

NOTE: If the case is locked by another user the request will fail with a 409 - Conflict response.

Additionally, only one draft can exist for a given case. If a draft currently exists the request will fail with a 409 - Conflict response.

POST https://yoursite.desk.com/api/v2/cases/:id/replies/draft

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Common Fields

Optional. Same as Create Reply

NOTE: An empty payload will create a default draft for the given case.

The default draft will have the :from, :to, :cc, :bcc and :subject fields populated.

NOTE: A partially populated payload, such as one that only contains :body, will honor the passed in params but also set populate the defaults.

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/cases/:id/replies/draft \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \

Example Request Body

1
2
3
{
  "body": "My Draft"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "subject": "Re: Please help",
  "body": "My Draft",
  "direction": "out",
  "status": "draft",
  "to": "doe.john@example.com",
  "from": "john.doe@example.com",
  "cc": null,
  "bcc": null,
  "client_type": "desk_portal",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "hidden_at": null,
  "hidden": false,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/replies/1",
      "class": "email"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "customer": {
      "href": "/api/v2/customer/1",
      "class": "customer"
    },
    "hidden_by": null
  }
}

Note Fields

Note objects have the following fields and links:

field name description
body Message body.
created_at Time of creation.
updated_at Time last updated.
erased_at Time at which an agent erased this note.
suppress_rules set to true to disable rule processing when creating or updating this note

Links

rel class description
self note this note
user user the user that created this note
erased_by user the user that erased this note
case case the case this note belongs to

List Notes

Retrieve a paginated list of notes for this case. Notes are private internal messages created by agents.

GET https://yoursite.desk.com/api/v2/cases/:case_id/notes

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

Please see Show Note for details on the specific fields.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/notes \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/notes?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/cases/1/notes?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/cases/1/notes?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "body": "Please assist me with this case",
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:19:27Z",
        "erased_at": null,
        "_links": {
          "self": {
            "href": "/api/v2/cases/1/notes/1",
            "class": "note"
          },
          "case": {
            "href": "/api/v2/cases/1",
            "class": "case"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          },
          "erased_by": null
        }
      },
      {
        "body": "No problem, I'm investigating",
        "created_at": "2017-08-18T22:28:33Z",
        "updated_at": "2017-08-18T22:28:33Z",
        "erased_at": null,
        "_links": {
          "self": {
            "href": "/api/v2/cases/1/notes/2",
            "class": "note"
          },
          "case": {
            "href": "/api/v2/cases/1",
            "class": "case"
          },
          "user": {
            "href": "/api/v2/users/2",
            "class": "user"
          },
          "erased_by": null
        }
      }
    ]
  }
}

Show Note

Retrieve a private case note.

GET https://yoursite.desk.com/api/v2/cases/:case_id/notes/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/notes/:id \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "body": "Please assist me with this case",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "erased_at": null,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/notes/1",
      "class": "note"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "user": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "erased_by": null
  }
}

Create Note

Create a private note for the given case.

POST https://yoursite.desk.com/api/v2/cases/:id/notes

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

field name description
body Text body of the note.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/:id/notes \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"body":"Please assist me with this case"}'

Example Request Body

1
2
3
{
  "body": "Please assist me with this case"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "body": "Please assist me with this case",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "erased_at": null,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/notes/1",
      "class": "note"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "user": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "erased_by": null
  }
}

Update Note

Update a private note for the given case.

PATCH https://yoursite.desk.com/api/v2/cases/:case_id/notes/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

field name description
body Body of the note.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/notes/:id \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"body":"Please assist me with this case"}'

Example Request Body

1
2
3
{
  "body": "Please assist me with this case"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "body": "Please assist me with this case",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "erased_at": null,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/notes/1",
      "class": "note"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "user": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "erased_by": null
  }
}

Delete Note

Delete a private note for the given case.

DELETE https://yoursite.desk.com/api/v2/cases/:case_id/notes/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/notes/:id \
    -u email:password \
    -X DELETE \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Example Response

1
204 No Content

Attachment Fields

Attachment objects have the following fields and links:

Fields

field name description
file_name name of the file
content_type file's content type, e.g. image/png
size file size
url url to get the file; see Attachment URLs
erased_at when the attachment was erased; see Delete Attachment
created_at when the attachment was created
updated_at when the attachment was last updated

Case Attachment Links

rel class description
self attachment this attachment
case case the case to which this attachment belongs
erased_by user the user that erased this attachment
uploaded_by user the user that uploaded this attachment

Message Attachment Links

All case attachment links plus

rel class description
message varies based on message type the message to which this attachment belongs

Reply Attachment Links

All case attachment links plus

rel class description
reply varies based on reply type the reply to which this attachment belongs

Attachment URLs

The Attachment resource will contain a reference to an Attachment URL resource. You can fetch the actual file from this endpoint.

Download Attachment

GET https://yoursite.desk.com/api/v2/cases/:case_id/attachments/:id/url

Redirects to the location of the actual file. The URL will be in the Location HTTP header. This URL will expire after a short duration and should be used immediately.


List Attachments

Retrieve a paginated list of all attachments for this case. This includes private case attachments along with those on replies and the original message.

Attachments sent to customers will have a link to uploaded_by and also have a link to either a message or reply.

Private case attachments will have a link to uploaded_by and will not have a link to a message or reply.

Attachments received from customers will not have a link to uploaded_by, but will have a link to a message or reply.

Erased attachments are not included in the results from this endpoint.

List All Case Attachments

GET https://yoursite.desk.com/api/v2/cases/:case_id/attachments

List Message Attachments

GET https://yoursite.desk.com/api/v2/cases/:case_id/message/attachments

List Reply Attachments

GET https://yoursite.desk.com/api/v2/cases/:case_id/replies/:reply_id/attachments

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/attachments \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/attachments?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/cases/1/attachments?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/cases/1/attachments?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "file_name": "awesome_pic.png",
        "content_type": "image/png",
        "size": 500,
        "url": "http://example.com/short_lived_link_to_the_file_content",
        "erased_at": null,
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:19:27Z",
        "_links": {
          "self": {
            "href": "/api/v2/cases/1/attachments/1",
            "class": "attachment"
          },
          "case": {
            "href": "/api/v2/cases/1",
            "class": "case"
          }
        }
      },
      {
        "file_name": "another_awesome_pic.png",
        "content_type": "image/png",
        "size": 500,
        "url": "http://example.com/short_lived_link_to_the_file_content",
        "erased_at": null,
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:19:27Z",
        "_links": {
          "self": {
            "href": "/api/v2/cases/1/attachments/2",
            "class": "attachment"
          },
          "case": {
            "href": "/api/v2/cases/2",
            "class": "case"
          }
        }
      }
    ]
  }
}

Show Attachment

Retrieve an attachment.

Show Case Attachment

GET https://yoursite.desk.com/api/v2/cases/:case_id/attachments/:id

Show Message Attachment

GET https://yoursite.desk.com/api/v2/cases/:case_id/message/attachments/:id

Show Reply Attachment

GET https://yoursite.desk.com/api/v2/cases/:case_id/replies/:reply_id/attachments/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/attachments/:id \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "file_name": "awesome_pic.png",
  "content_type": "image/png",
  "size": 500,
  "url": "http://example.com/short_lived_link_to_the_file_content",
  "erased_at": null,
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/attachments/1",
      "class": "attachment"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    }
  }
}

Create Attachment

Create a case attachment

Create a private case attachment.

POST https://yoursite.desk.com/api/v2/cases/:id/attachments

Create a reply attachment

Create an attachment for one of the replies in the case.

POST https://yoursite.desk.com/api/v2/cases/:case_id/replies/:reply_id/attachments

Create a message attachment

Create an attachment for the original message in the case.

POST https://yoursite.desk.com/api/v2/cases/:id/message/attachments

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

field name description
file_name name of the file
content_type file's content type, e.g. image/png
content base64 encoded file content

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/cases/:id/attachments \
  -u email:password \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"file_name": "favicon.png", "content_type": "image/png", "content": "iVBORw0KGgoAAAANSUhEUgAAABsAAAAXCAIAAAB1dKN5AAAAGXRFWHRTb2Z0\nd2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyRpVFh0WE1MOmNvbS5hZG9i\nZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2Vo\naUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6\nbnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMy1jMDExIDY2\nLjE0NTY2MSwgMjAxMi8wMi8wNi0xNDo1NjoyNyAgICAgICAgIj4gPHJkZjpS\nREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJk\nZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIg\neG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxu\nczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1s\nbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9S\nZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9w\nIENTNiAoTWFjaW50b3NoKSIgeG1wTU06SW5zdGFuY2VJRD0ieG1wLmlpZDo0\nNkEyOEM5RUE2REUxMUUyODc1NUM1OUZGMTlFMjEwNyIgeG1wTU06RG9jdW1l\nbnRJRD0ieG1wLmRpZDo0NkEyOEM5RkE2REUxMUUyODc1NUM1OUZGMTlFMjEw\nNyI+IDx4bXBNTTpEZXJpdmVkRnJvbSBzdFJlZjppbnN0YW5jZUlEPSJ4bXAu\naWlkOjg5ODY1RDg5QTZENzExRTI4NzU1QzU5RkYxOUUyMTA3IiBzdFJlZjpk\nb2N1bWVudElEPSJ4bXAuZGlkOjg5ODY1RDhBQTZENzExRTI4NzU1QzU5RkYx\nOUUyMTA3Ii8+IDwvcmRmOkRlc2NyaXB0aW9uPiA8L3JkZjpSREY+IDwveDp4\nbXBtZXRhPiA8P3hwYWNrZXQgZW5kPSJyIj8+I+v80gAAAwJJREFUeNqklUtr\nU0EUx2fuvb1pmvSVmvpA2021tMXWoiLiY6MoFHQhgvYTFBTpZ+jChXHjwo3g\nUhe6EAuCoC1uRKVRulBbUFNSWvrC2rTN475mjmdmkkuSpg/t5SaczNzzu//z\nPzMTAwDI/14MCAficrAYyTHIepBlRNsVjhCPEw/E7XLiyu9/IELhZjITWTmb\nx98l3jwdtxk4HFxJN3YCUhcWCFIXBgiNj/x89ehTOpVrO3moh4HFiS1kgrET\nHOcCxGTABA5QS+LbAuJU+TkmcEqmsVWN0nglylMgUSyIqmXhvqG5Ag7HjLLS\nFEWNqOokDqT3IkeaBaobvhsWEyOUkN5G3YANHimWVCdEKWmO9KhAVM0BXyPO\nNpq0q14L6tRAa0B5BPmK8tIIMC7GJU5ALZf/WVh3HFYdCRkh09doauR4RI+Y\nVP00vAJLvdwtgjIJxcHV5Wz82fjU+4SbczFH02hL1z5S2Bp1VdTHCaLLQNns\n5G0SjqiqUSAS5yYXR2Mj9rrl53AOya/zm7XUwH2DFEcSHSaaiMaxgptrS+nR\n2Ft73d75RkAioEwb3ZVondKATlecPPTLk7iPO3el4/zVzpqw+X1sZvhxPLPJ\nawzc3o7soFgcQDrrtWiAIiuD2z7tvPg8rZ67dLPn2sApFSO3tT1679ZLziuc\nMlpGHBvE4oCLfk9A4HAUP2GDppLLzBPrmFJ6ub+nOA2JHScOVtaoFifW2Byg\nKLB4LpdxVBAIGqG66rLMyN5wHmHqJRptJpbB4bDW3aDT0pzahqAKrKz7e36t\njDibWFZBYzRUQmyr1c5GjdZQhWOtpT0aDJkqfv7wI2fcn8K2JCeXVHzk2IHi\nLP3B3aFybf7bNJpOWVMTixgvzqxOxGex/Uuzqx9e//BwfQBZmE5FmsM3Bs/g\nk34W3fpfwco6sdvDc8mVyq/UtcH7fe29JRq3OcOra8w7sT7sbKWpqoGhi2W4\n7TXmtx3jWOnY6C/shmt7Tftru0+3Xrh+tL6pZuPDdDf/hRWvvwIMAJE9J8AO\nRSMOAAAAAElFTkSuQmCC\n"}' -k

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "file_name": "awesome_pic.png",
  "content_type": "image/png",
  "size": 500,
  "url": "http://example.com/short_lived_link_to_the_file_content",
  "erased_at": null,
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/attachments/1",
      "class": "attachment"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    }
  }
}

Delete Attachment

Delete an attachment.

Attachments on message or reply drafts do not set erased_at or erased_by when deleted. All other delete requests will set erased_at and erased_by.

Delete a case attachment

DELETE https://yoursite.desk.com/api/v2/cases/:case_id/attachments/:id

Delete a message attachment

DELETE https://yoursite.desk.com/api/v2/cases/:case_id/message/attachments/:id

Delete a reply attachment

DELETE https://yoursite.desk.com/api/v2/cases/:case_id/replies/:reply_id/attachments/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Note: the user making the request must have permission to delete content. This can be set in the Admin.

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/attachments/:id \
    -u email:password \
    -X DELETE \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Example Response

1
204 No Content

Macro Preview

Retrieve a preview for applying a set of macros to a case.

POST https://yoursite.desk.com/api/v2/cases/:case_id/macros/preview

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

field name description
ignore_body If set to true, will ignore the body on the draft when applying macros. This means any quick reply macros will be performed against an empty body. This does not actually modify the draft.

Links

name description
macros Array of macro links to preview. Use macros endpoint to get all available macros.

Parameters

To only see the changes that the macro will have on the case, use the changes_only parameter. The values are true and false. If set to false or not specified, the response will return the entire case.

Example Curl Request

Macros will be applied in the order of the links array body.

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/macros/preview \
    -u email:password \
    -X POST \
    -d '{"_links":{"macros":[{"class":"macro","href":"/api/v2/macros/1"},{"class":"macro","href":"/api/v2/macros/2"}]}}'
    -H 'Accept: application/json'

Example Response

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
{
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/macros/preview",
      "class": "page"
    },
    "macros": [
      {
        "href": "/api/v2/macros/2",
        "class": "macro"
      },
      {
        "href": "/api/v2/macros/1",
        "class": "macro"
      }
    ],
    "articles": [
      {
        "href": "/api/v2/articles/2",
        "class": "article"
      },
      {
        "href": "/api/v2/articles/1",
        "class": "article"
      }
    ]
  },
  "_embedded": {
    "case": {
      "id": 1,
      "external_id": null,
      "blurb": null,
      "subject": "Welcome",
      "priority": 5,
      "locked_until": null,
      "description": null,
      "status": "new",
      "type": "email",
      "labels": [

      ],
      "label_ids": [

      ],
      "language": "en_us",
      "created_at": "2017-08-18T22:19:27Z",
      "updated_at": "2017-08-18T22:24:27Z",
      "changed_at": "2017-08-18T22:23:27Z",
      "active_at": "2017-08-18T22:24:27Z",
      "received_at": "2017-08-18T22:19:27Z",
      "first_opened_at": "2017-08-18T22:20:27Z",
      "opened_at": "2017-08-18T22:21:27Z",
      "first_resolved_at": "2017-08-18T22:24:27Z",
      "resolved_at": "2017-08-18T22:24:27Z",
      "custom_fields": {
        "level": "vip"
      },
      "_links": {
        "self": {
          "href": "/api/v2/cases/1",
          "class": "case"
        },
        "message": {
          "href": "/api/v2/cases/1/message",
          "class": "message"
        },
        "customer": {
          "href": "/api/v2/customers/1",
          "class": "customer"
        },
        "assigned_user": {
          "href": "/api/v2/users/2",
          "class": "user"
        },
        "assigned_group": {
          "href": "/api/v2/groups/1",
          "class": "group"
        },
        "locked_by": null,
        "replies": {
          "href": "/api/v2/cases/1/replies",
          "class": "reply"
        },
        "draft": {
          "href": "/api/v2/cases/1/replies/draft",
          "class": "reply"
        },
        "notes": {
          "href": "/api/v2/cases/1/notes",
          "class": "note"
        },
        "history": {
          "href": "/api/v2/cases/1/history",
          "class": "history"
        },
        "macro_preview": {
          "href": "/api/v2/cases/1/macros/preview",
          "class": "macro_preview"
        },
        "attachments": {
          "href": "/api/v2/cases/1/attachments",
          "class": "attachment"
        }
      }
    },
    "reply": {
      "subject": "Please help",
      "body": "Help me with my issue!",
      "direction": "in",
      "status": "pending",
      "to": "support@desk.com",
      "from": "john.doe@example.com",
      "cc": null,
      "bcc": null,
      "client_type": "desk_portal",
      "created_at": "2017-08-18T22:19:27Z",
      "updated_at": "2017-08-18T22:19:27Z",
      "hidden_at": null,
      "hidden": false,
      "_links": {
        "self": {
          "href": "/api/v2/cases/1/replies/1",
          "class": "email"
        },
        "case": {
          "href": "/api/v2/cases/1",
          "class": "case"
        },
        "customer": {
          "href": "/api/v2/customer/1",
          "class": "customer"
        },
        "hidden_by": null
      }
    },
    "notes": [
      {
        "body": "Please assist me with this case",
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:19:27Z",
        "erased_at": null,
        "_links": {
          "self": {
            "href": "/api/v2/cases/1/notes/1",
            "class": "note"
          },
          "case": {
            "href": "/api/v2/cases/1",
            "class": "case"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          },
          "erased_by": null
        }
      }
    ]
  }
}

Feed

The case feed endpoint returns an interlaced set of the original message, replies, and notes, sorted by updated_at. Note that this does not include any draft replies.

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/feed \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/feed?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/cases/1/feed?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/cases/1/feed?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "subject": "Please help",
        "body": "Help me with my issue!",
        "direction": "in",
        "status": "pending",
        "to": "support@desk.com",
        "from": "john.doe@example.com",
        "cc": null,
        "bcc": null,
        "client_type": "desk_portal",
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:19:27Z",
        "hidden_at": null,
        "hidden": false,
        "_links": {
          "self": {
            "href": "/api/v2/cases/1/replies/1",
            "class": "email"
          },
          "case": {
            "href": "/api/v2/cases/1",
            "class": "case"
          },
          "customer": {
            "href": "/api/v2/customer/1",
            "class": "customer"
          },
          "hidden_by": null
        }
      },
      {
        "body": "Please assist me with this case",
        "created_at": "2017-08-18T22:19:27Z",
        "updated_at": "2017-08-18T22:19:27Z",
        "erased_at": null,
        "_links": {
          "self": {
            "href": "/api/v2/cases/1/notes/1",
            "class": "note"
          },
          "case": {
            "href": "/api/v2/cases/1",
            "class": "case"
          },
          "user": {
            "href": "/api/v2/users/1",
            "class": "user"
          },
          "erased_by": null
        }
      }
    ]
  }
}

History

The case history endpoint will display a paginated list of all events/actions that have happened to the case. This provides a way for you to audit your cases to see what changes were made to the case and who made them.

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Event Types

event type description
case_opened an agent opened the case
case_pending case was set to pending
case_reopened case was reopened
case_resolved case was resolved
case_error_dismissed case error was dismissed
case_updated case was updated
case_merged case was merged with another case
case_linked case was linked to another case
note_created note was created
note_erased note was erased
customer_created customer is created
customer_changed_from_merge customer merge occured
customer_feedback_updated customer feedback provided
macro_applied macro was applied
article_applied knowledge-base article was applied
rule_applied rule was applied
email_pending_send email was waiting to be sent
email_sent email was sent
email_sent_failure email failed to send
email_sent_ack email auto acknowledgement sent
email_sent_ticket_forward email case was forwarded
email_content_erased email content was erased
tweet_pending_send tweet was waiting to be sent
tweet_sent tweet was sent
tweet_sent_failure tweet failed to send
tweet_content_erased tweet content was erased
tweet_retweeted tweet was retweeted
facebook_pending_send facebook was waiting to be sent
facebook_sent facebook was sent
facebook_sent_failure facebook failed to send
facebook_post_content_erased facebook post content was erased
facebook_comment_content_erased facebook comment content was erased
facebook_content_liked facebook content was liked
facebook_content_unliked facebook content was unliked
facebook_content_deleted facebook content was deleted
question_hidden question was hidden
question_unhidden question was unhidden
question_allow_answers answers were allowed for question
question_disallow_answers answers were disallowed for question
answer_marked_best answer was marked best
answer_unmarked_best answer was unmarked best
attachment_created attachment was added
attachment_deleted attachment was deleted
attachment_erased attachment was erased
phone_content_erased phone call content was erased
queue_item_pulled agent pulled case for editing
queue_item_accept agent accepted routed case
queue_item_transferred_queue case transferred to a different queue
queue_item_putback case placed back into queue
queue_item_timeout case timed out in queue

Common Event Properties

field name description
id string identifier for this object
type the type of event (see list of event types)
context context id of the event
created_at date/time that the event was created
_links links to other resources that are relevant to the event

The 'Context'

Sometimes events trigger other events. A good example of this is a rule running as a result of a change made by the agent.

To facilitate the grouping of events triggered by one action we've added a context property to all events. This context is just a value that you can use to group together events that occured in the same context.

Changes

Some events will reflect changes to case fields. These changes are displayed as an array of JSON objects where each object has three properties: field, to, and from. These indicate which field changed as well as the previous value and the new value.

Invoker

Events triggered by a person will contain a link to the invoker/person who triggered it. This can be an agent or a customer.

Sorting

Sorting is supported by using sort_field and sort_direction parameters in your request.

  • sort_field - case field on which you would like to sort
  • sort_direction - direction to sort - asc for ascending, desc for descending

The following fields can be used for sorting history: created_at and id.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/:id/history \
    -u email:password \
    -H 'Accept: application/json'

Common Response

All events will contain the id of the event, context, a created at date as well as links.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "id": 1,
  "type": "case_opened",
  "context": "1234",
  "created_at": "2017-08-18T22:24:27Z",
  "_links": {
    "invoker": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  }
}

Case Updated Response

case_updated events has a changes array containing the case fields that changed.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
  "id": 2,
  "type": "case_updated",
  "context": "1234",
  "created_at": "2017-08-18T22:24:27Z",
  "changes": [
    {
      "field": "description",
      "from": "some description",
      "to": "some other description"
    },
    {
      "field": "priority",
      "from": 5,
      "to": 10
    },
    {
      "field": "gl_account_number",
      "from": null,
      "to": "1234567"
    },
    {
      "field": "labels",
      "from": [

      ],
      "to": [
        "some",
        "new",
        "labels"
      ]
    }
  ],
  "_links": {
    "invoker": {
      "href": "/api/v2/users/1",
      "class": "user"
    }
  }
}

Note Events

note_created and note_erased will contain a link to the note.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "id": 3,
  "type": "note_created",
  "context": "1234",
  "created_at": "2017-08-18T22:24:27Z",
  "_links": {
    "invoker": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "note": {
      "href": "/api/v2/cases/1/notes/1",
      "class": "note"
    }
  }
}

Macro Events

macro_applied events will contain a link to the macro that was applied.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "id": 4,
  "type": "macro_applied",
  "context": "1234",
  "created_at": "2017-08-18T22:24:27Z",
  "_links": {
    "invoker": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "macro": {
      "href": "/api/v2/macros/1",
      "class": "macro"
    }
  }
}

Article Events

kb_applied events will contain a link to the article that was applied.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "id": 5,
  "type": "kb_applied",
  "context": "1234",
  "created_at": "2017-08-18T22:24:27Z",
  "_links": {
    "invoker": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "article": {
      "href": "/api/v2/articles/1",
      "class": "article"
    }
  }
}

Email Events

email_pending_send, email_sent, email_sent_failure, email_send_ack, email_sent_case_forward and email_content_erased will contain a link to the email.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "id": 7,
  "type": "email_sent",
  "context": "1234",
  "created_at": "2017-08-18T22:24:27Z",
  "_links": {
    "invoker": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "email": {
      "href": "/api/v2/cases/1/replies/2",
      "class": "email"
    }
  }
}

Rule Applied Events

Rules can be embedded in rule_applied events by simply passing rule in the embed parameter. Additionally the event will also contain a link to the rule.

Tweet Events

tweet_pending_send, tweet_sent, tweet_sent_failure, tweet_content_erased and tweet_retweeted will contain a link to the tweet.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "id": 8,
  "type": "tweet_sent",
  "context": "1234",
  "created_at": "2017-08-18T22:24:27Z",
  "_links": {
    "invoker": {
      "href": "/api/v2/users/1",
      "class": "user"
    },
    "tweet": {
      "href": "/api/v2/cases/1/replies/1",
      "class": "tweet"
    }
  }
}

Labels List

Retrieve a paginated list of case labels. This endpoint accepts a max per_page param value of 1000.

GET https://yoursite.desk.com/api/v2/cases/:id/labels

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/1/labels \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/labels?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/cases/1/labels?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/cases/1/labels?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "id": 1,
        "name": "MyLabel",
        "description": "My Label Description",
        "types": [
          "case",
          "macro"
        ],
        "enabled": true,
        "color": "green",
        "position": 1,
        "_links": {
          "self": {
            "href": "/api/v2/labels/1",
            "class": "label"
          }
        }
      },
      {
        "id": 1,
        "name": "Another Label",
        "description": "Label Description",
        "types": [
          "case",
          "macro"
        ],
        "enabled": true,
        "color": "green",
        "position": 2,
        "_links": {
          "self": {
            "href": "/api/v2/labels/2",
            "class": "label"
          }
        }
      }
    ]
  }
}

Split Partial Case

Split text from a case into a new case while leaving original case intact. Analogous to split from highlight in agent view. This works for both original message and for subsequent replies.

POST https://yoursite.desk.com/api/v2/cases/:case_id/replies/:reply_id/splits
GET https://yoursite.desk.com/api/v2/cases/:case_id/replies/:reply_id/splits

POST https://yoursite.desk.com/api/v2/cases/:case_id/message/splits
GET https://yoursite.desk.com/api/v2/cases/:case_id/message/splits

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

field name description
new_ticket_subject The case can be given a new subject if desired.
split_from_text The text being split into a new case. Note that the call will fail if the split_from_text is not present in the reply you are splitting.

Links

name description
from The case from which the split occured.
to The case created by the split.
from_interaction The channel object (currently Email channel only) from which the split occured.
to_interaction The channel object (currently Email channel only) created by the split.

Example Reply Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/replies/:reply_id/splits \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"new_ticket_subject": "<new ticket subject text if desired here>", "split_from_text": "<text present in the reply here>"}}'

Example Message Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/message/splits \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"new_ticket_subject": "<new ticket subject text if desired here>", "split_from_text": "<text present in the originalm message here>"}}'

Example Request Body

1
2
3
4
5
{
  "type": "split",
  "new_ticket_subject": "New case subject",
  "split_from_text": "Text split from original case."
}

Example Replies/Message Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "type": "split_from",
  "created_at": "2017-08-18T22:29:33Z",
  "_links": {
    "self": {
      "href": "/api/v2/cases/36/links/55",
      "class": "case_link"
    },
    "from": {
      "href": "/api/v2/cases/36",
      "class": "case",
      "title": "Original Case Subject"
    },
    "to": {
      "href": "/api/v2/cases/50",
      "class": "case",
      "title": "Case API split API Subject 1"
    },
    "from_interaction": {
      "href": "/api/v2/cases/36/replies/78/splits",
      "class": "email"
    },
    "to_interaction": {
      "href": "/api/v2/cases/50/replies/94/splits",
      "class": "email"
    }
  }
}

List Facebook Likes

Retrieve a list of all likes for this Facebook post and any comments.

GET https://yoursite.desk.com/api/v2/cases/:case_id/message/likes

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/message/likes \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "entries": [
    {
      "facebook_id": "1234_5678",
      "liked_by_page": false,
      "like_count": 0
    },
    {
      "facebook_id": "1234_5678_9012",
      "liked_by_page": true,
      "like_count": 1
    }
  ],
  "_links": {
    "self": {
      "href": "https://yoursite.desk.com/api/v2/facebook_feeds/4/facebook_posts/9/likes",
      "class": "facebook_likes"
    }
  }
}

Create Draft (Generic)

This is a generic version of the draft reply endpoint. It can conditionally update either the message or the reply.

Create a draft for the given case. Depending on the case's channel, a draft can be a email, tweet, phone_call, community_answer, facebook_comment, or facebook_message. All drafts share a set of common fields, along with some channels having additional fields noted below.

NOTE: If the case is locked by another user the request will fail with a 409 - Conflict response.

Additionally, only one draft can exist for a given case. If a draft currently exists the request will fail with a 409 - Conflict response.

If the case does not have a message, then this will create a draft message. If it does have a message, then this will create a new draft reply.

POST https://yoursite.desk.com/api/v2/cases/:id/draft

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Common Fields

Optional. Same as Create Reply

NOTE: An empty payload will create a default draft for the given case.

The default draft will have the :from, :to, :cc, :bcc and :subject fields populated.

NOTE: A partially populated payload, such as one that only contains :body, will honor the passed in params but also set populate the defaults.

Example Curl Request

1
2
3
4
5
$ curl https://yoursite.desk.com/api/v2/cases/:id/draft \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \

Example Request Body

1
2
3
{
  "body": "My Draft"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "subject": "Re: Please help",
  "body": "My Draft",
  "direction": "out",
  "status": "draft",
  "to": "doe.john@example.com",
  "from": "john.doe@example.com",
  "cc": null,
  "bcc": null,
  "client_type": "desk_portal",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "hidden_at": null,
  "hidden": false,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/replies/1",
      "class": "email"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "customer": {
      "href": "/api/v2/customer/1",
      "class": "customer"
    },
    "hidden_by": null
  }
}

Show Draft (Generic)

This is a generic version of the draft reply endpoint. It can conditionally update either the message or the reply.

Retrieve the draft for this case. Depending on the case's channel, the draft will be an email, tweet, phone_call, community_answer, facebook_comment, or facebook_message. All drafts share a set of common fields, along with some channels having additional fields noted below.

If a draft message exists, it will be returned. Otherwise, the draft reply will be returned.

GET https://yoursite.desk.com/api/v2/cases/:case_id/draft

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Administrator, Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/draft \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "subject": "Re: Please help",
  "body": "A draft.",
  "direction": "out",
  "status": "pending",
  "to": "doe.john@example.com",
  "from": "john.doe@example.com",
  "cc": null,
  "bcc": null,
  "client_type": "desk_portal",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "hidden_at": null,
  "hidden": false,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/draft",
      "class": "email"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "customer": {
      "href": "/api/v2/customer/1",
      "class": "customer"
    },
    "hidden_by": null
  }
}

Update Draft (Generic)

This is a generic version of the draft reply endpoint. It can conditionally update either the message or the reply.

Draft replies can be updated many times. Once a reply has transitioned to something other than draft status, it can no longer be updated.

This request will update the draft message if it exists. Otherwise, the draft reply will be updated.

NOTE: If the case is locked by another user the request will fail with a 409 - Conflict response.

PATCH https://yoursite.desk.com/api/v2/cases/:case_id/draft

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Common Fields

field name description
direction Direction of the reply: in for coming into the agent or out for sending out of the agent.
body Body of the reply.
created_at Time of creation.
updated_at Time last updated.
sent_at Time the outbound reply was sent. nil for inbound replies and all chat replies.
suppress_rules Set to true to disable rule processing when creating or updating this reply.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/draft \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"body":"Updated reply body", "cc": "new.email@example.com"}'

Example Request Body

1
2
3
4
{
  "body": "Updated draft body",
  "cc": "new.email@example.com"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "subject": "Re: Please help",
  "body": "Updated draft body",
  "direction": "out",
  "status": "draft",
  "to": "doe.john@example.com",
  "from": "john.doe@example.com",
  "cc": "new.email@example.com",
  "bcc": null,
  "client_type": "desk_portal",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "hidden_at": null,
  "hidden": false,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/replies/1",
      "class": "email"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "customer": {
      "href": "/api/v2/customer/1",
      "class": "customer"
    },
    "hidden_by": null
  }
}

Reset Draft (Generic)

You can reset a draft by PATCHing the draft with a reset=1 parameter.

Resetting a draft will reset it to a pristine state. Internally it will delete the draft and create a new empty draft (so interaction ids will not be preserved). For some interaction types this includes initializing some fields with default values. For example, email drafts will have the To field populated.

PATCH https://yoursite.desk.com/api/v2/cases/:case_id/draft

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Common Fields

field name description
reset You must set this to 1 to reset the draft.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/cases/:case_id/draft \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"reset":1}'

Example Request Body

1
2
3
{
  "reset": 1
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "subject": "Re: Please help",
  "body": "",
  "direction": "out",
  "status": "draft",
  "to": "doe.john@example.com",
  "from": "john.doe@example.com",
  "cc": null,
  "bcc": null,
  "client_type": "desk_portal",
  "created_at": "2017-08-18T22:19:27Z",
  "updated_at": "2017-08-18T22:19:27Z",
  "hidden_at": null,
  "hidden": false,
  "_links": {
    "self": {
      "href": "/api/v2/cases/1/replies/1",
      "class": "email"
    },
    "case": {
      "href": "/api/v2/cases/1",
      "class": "case"
    },
    "customer": {
      "href": "/api/v2/customer/1",
      "class": "customer"
    },
    "hidden_by": null
  }
}