Assets
Customer
Info
Knowledgebase
Organization
Request
Requesttype
Servicedesk

Rate this page:

Request

Get customer requests

GET /rest/servicedeskapi/request

This method returns all customer requests for the user executing the query.

The returned customer requests are ordered chronologically by the latest activity on each request. For example, the latest status transition or comment.

Permissions required: Permission to access the specified service desk.

Response limitations: For customers, the list returned will include request they created (or were created on their behalf) or are participating in only.

Connect app scope required: READ

OAuth 2.0 scopes required:
ClassicRECOMMENDED:read:servicedesk-request
Granular:read:request:jira-service-management, read:user:jira

Request

Query parameters
searchTerm

string

Filters customer requests where the request summary matches the searchTerm. Wildcards can be used in the searchTerm parameter.

requestOwnership

Array<string>

Filters customer requests using the following values:

  • OWNED_REQUESTS returns customer requests where the user is the creator.
  • PARTICIPATED_REQUESTS returns customer requests where the user is a participant.
  • ORGANIZATION returns customer requests for an organization of which the user is a member when used in conjunction with organizationId.
  • ALL_ORGANIZATIONS returns customer requests that belong to all organizations of which the user is a member.
  • APPROVER returns customer requests where the user is an approver. Can be used in conjunction with approvalStatus to filter pending or complete approvals.
  • ALL_REQUESTS returns all customer requests. Deprecated and will be removed, as the returned requests may change if more values are added in the future. Instead, explicitly list the desired filtering strategies.

Multiple values of the query parameter are supported. For example, requestOwnership=OWNED_REQUESTS&requestOwnership=PARTICIPATED_REQUESTS will only return customer requests where the user is the creator or a participant. If not specified, filtering defaults to OWNED_REQUESTS, PARTICIPATED_REQUESTS, and ALL_ORGANIZATIONS.

requestStatus

string

Filters customer requests where the request is closed, open, or either of the two where:

  • CLOSED_REQUESTS returns customer requests that are closed.
  • OPEN_REQUESTS returns customer requests that are open.
  • ALL_REQUESTS returns all customer requests.
approvalStatus

string

Filters results to customer requests based on their approval status:

  • MY_PENDING_APPROVAL returns customer requests pending the user's approval.
  • MY_HISTORY_APPROVAL returns customer requests where the user was an approver.

Note: Valid only when used with requestOwnership=APPROVER.

organizationId

integer

Filters customer requests that belong to a specific organization (note that the user must be a member of that organization). Note: Valid only when used with requestOwnership=ORGANIZATION.

Format: int32
serviceDeskId

integer

Filters customer requests by service desk.

Format: int32
requestTypeId

integer

Filters customer requests by request type. Note that the serviceDeskId must be specified for the service desk in which the request type belongs.

Format: int32
expand

Array<string>

A multi-value parameter indicating which properties of the customer request to expand, where:

  • serviceDesk returns additional details for each service desk.
  • requestType returns additional details for each request type.
  • participant returns the participant details, if any, for each customer request.
  • sla returns the SLA information on each customer request.
  • status returns the status transitions, in chronological order, for each customer request.
  • attachment returns the attachments for the customer request.
  • action returns the actions that the user can or cannot perform on this customer request.
  • comment returns the comments, if any, for each customer request.
  • comment.attachment returns the attachment details, if any, for each comment.
  • comment.renderedBody (Experimental) returns the rendered body in HTML format (in addition to the raw body) for each comment.
start

integer

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

Format: int32
limit

integer

The maximum number of items to return per page. Default: 50. See the Pagination section for more details.

Format: int32

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returns the customer requests, on the specified page of the results.

Content typeValue
application/json

PagedDTOCustomerRequestDTO

Example response (application/json)

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
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
{
  "_expands": [
    "participant",
    "status",
    "sla",
    "requestType",
    "serviceDesk",
    "attachment",
    "action",
    "comment"
  ],
  "size": 3,
  "start": 3,
  "limit": 3,
  "isLastPage": false,
  "_links": {
    "base": "https://your-domain.atlassian.net/rest/servicedeskapi",
    "context": "context",
    "next": "https://your-domain.atlassian.net/rest/servicedeskapi/request?start=6&limit=3",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request?start=0&limit=3"
  },
  "values": [
    {
      "_expands": [
        "participant",
        "status",
        "sla",
        "requestType",
        "serviceDesk",
        "attachment",
        "action",
        "comment"
      ],
      "issueId": "107001",
      "issueKey": "HELPDESK-1",
      "requestTypeId": "25",
      "serviceDeskId": "10",
      "createdDate": {
        "iso8601": "2015-10-08T14:42:00+0700",
        "jira": "2015-10-08T14:42:00.000+0700",
        "friendly": "Monday 14:42 PM",
        "epochMillis": 1444290120000
      },
      "reporter": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "requestFieldValues": [
        {
          "fieldId": "summary",
          "label": "What do you need?",
          "value": "Request JSD help via REST"
        },
        {
          "fieldId": "description",
          "label": "Why do you need this?",
          "value": "I need a new *mouse* for my Mac",
          "renderedValue": {
            "html": "<p>I need a new <b>mouse</b> for my Mac</p>"
          }
        }
      ],
      "currentStatus": {
        "status": "Waiting for Support",
        "statusCategory": "NEW",
        "statusDate": {
          "iso8601": "2015-10-08T14:01:00+0700",
          "jira": "2015-10-08T14:01:00.000+0700",
          "friendly": "Today 14:01 PM",
          "epochMillis": 1444287660000
        }
      },
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/issue/107001",
        "web": "https://your-domain.atlassian.net/servicedesk/customer/portal/10/HELPDESK-1",
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/107001",
        "agent": "https://your-domain.atlassian.net/browse/HELPDESK-1"
      }
    },
    {
      "_expands": [
        "participant",
        "status",
        "sla",
        "requestType",
        "serviceDesk",
        "attachment",
        "action",
        "comment"
      ],
      "issueId": "107002",
      "issueKey": "HELPDESK-2",
      "requestTypeId": "25",
      "serviceDeskId": "10",
      "createdDate": {
        "iso8601": "2015-10-08T14:30:00+0700",
        "jira": "2015-10-08T14:30:00.000+0700",
        "friendly": "Monday 14:30 PM",
        "epochMillis": 1444289400000
      },
      "reporter": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "requestFieldValues": [
        {
          "fieldId": "summary",
          "label": "What do you need?",
          "value": "Request a new account"
        },
        {
          "fieldId": "description",
          "label": "Why do you need this?",
          "value": "Create an account on Jira"
        }
      ],
      "currentStatus": {
        "status": "Waiting for Support",
        "statusCategory": "NEW",
        "statusDate": {
          "iso8601": "2015-10-08T14:01:00+0700",
          "jira": "2015-10-08T14:01:00.000+0700",
          "friendly": "Today 14:01 PM",
          "epochMillis": 1444287660000
        }
      },
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/issue/107002",
        "web": "https://your-domain.atlassian.net/servicedesk/customer/portal/10/HELPDESK-2",
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/107002",
        "agent": "https://your-domain.atlassian.net/browse/HELPDESK-2"
      }
    },
    {
      "_expands": [
        "participant",
        "status",
        "sla",
        "requestType",
        "serviceDesk",
        "attachment",
        "action",
        "comment"
      ],
      "issueId": "109006",
      "issueKey": "SIMPLEDESK-6",
      "requestTypeId": "33",
      "serviceDeskId": "12",
      "createdDate": {
        "iso8601": "2015-10-05T14:30:00+0700",
        "jira": "2015-10-05T14:30:00.000+0700",
        "friendly": "Monday 14:30 PM",
        "epochMillis": 1444030200000
      },
      "reporter": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "requestFieldValues": [
        {
          "fieldId": "summary",
          "label": "Summarize the problem",
          "value": "Printer on level 3 did not work"
        },
        {
          "fieldId": "description",
          "value": "Ink cartridge is empty"
        }
      ],
      "currentStatus": {
        "status": "Waiting for Support",
        "statusCategory": "NEW",
        "statusDate": {
          "iso8601": "2015-10-08T14:00:00+0700",
          "jira": "2015-10-08T14:00:00.000+0700",
          "friendly": "Today 14:00 PM",
          "epochMillis": 1444287600000
        }
      },
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/issue/109006",
        "web": "https://your-domain.atlassian.net/servicedesk/customer/portal/12/SIMPLEDESK-6",
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/109006",
        "agent": "https://your-domain.atlassian.net/browse/SIMPLEDESK-6"
      }
    }
  ]
}

Create customer request

POST /rest/servicedeskapi/request

This method creates a customer request in a service desk.

The JSON request must include the service desk and customer request type, as well as any fields that are required for the request type. A list of the fields required by a customer request type can be obtained using servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/field.

The fields required for a customer request type depend on the user's permissions:

  • raiseOnBehalfOf is not available to Users who have the customer permission only.
  • requestParticipants is not available to Users who have the customer permission only or if the feature is turned off for customers.

requestFieldValues is a map of Jira field IDs and their values. See Field input formats, for details of each field's JSON semantics and the values they can take.

Permissions required: Permission to create requests in the specified service desk.

Connect app scope required: WRITE

OAuth 2.0 scopes required:
ClassicRECOMMENDED:write:servicedesk-request
Granular:read:request:jira-service-management, write:request:jira-service-management, read:user:jira

Request

Body parameters
serviceDeskId

string

ID of the service desk in which to create the request.

requestTypeId

string

ID of the request type for the request.

requestFieldValues

object

JSON map of Jira field IDs and their values representing the content of the request.

requestParticipants

Array<string>

List of customers to participate in the request, as a list of accountId values.

raiseOnBehalfOf

string

The accountId of the customer that the request is being raised on behalf of.

channel

string

(Experimental) Shows extra information for the request channel.

adfRequest

boolean

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "requestParticipants": [
    "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d69abfa3980ce712caae"
  ],
  "adfRequest": false,
  "serviceDeskId": "10",
  "requestTypeId": "25",
  "requestFieldValues": {
    "summary": "Request JSD help via REST",
    "description": "I need a new *mouse* for my Mac"
  }
}'

Responses

Returned if the customer request was created.

Content typeValue
application/json

CustomerRequestDTO

Example response (application/json)

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
{
  "_expands": [
    "participant",
    "status",
    "sla",
    "requestType",
    "serviceDesk",
    "attachment",
    "action",
    "comment"
  ],
  "issueId": "107001",
  "issueKey": "HELPDESK-1",
  "requestTypeId": "25",
  "serviceDeskId": "10",
  "createdDate": {
    "iso8601": "2015-10-08T14:42:00+0700",
    "jira": "2015-10-08T14:42:00.000+0700",
    "friendly": "Monday 14:42 PM",
    "epochMillis": 1444290120000
  },
  "reporter": {
    "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "emailAddress": "fred@example.com",
    "displayName": "Fred F. User",
    "active": true,
    "timeZone": "Australia/Sydney",
    "_links": {
      "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
      "avatarUrls": {
        "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
        "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
        "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
        "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
      },
      "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
    }
  },
  "requestFieldValues": [
    {
      "fieldId": "summary",
      "label": "What do you need?",
      "value": "Request JSD help via REST"
    },
    {
      "fieldId": "description",
      "label": "Why do you need this?",
      "value": "I need a new *mouse* for my Mac",
      "renderedValue": {
        "html": "<p>I need a new <b>mouse</b> for my Mac</p>"
      }
    }
  ],
  "currentStatus": {
    "status": "Waiting for Support",
    "statusCategory": "NEW",
    "statusDate": {
      "iso8601": "2015-10-08T14:01:00+0700",
      "jira": "2015-10-08T14:01:00.000+0700",
      "friendly": "Today 14:01 PM",
      "epochMillis": 1444287660000
    }
  },
  "_links": {
    "jiraRest": "https://your-domain.atlassian.net/rest/api/2/issue/107001",
    "web": "https://your-domain.atlassian.net/servicedesk/customer/portal/10/HELPDESK-1",
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/107001",
    "agent": "https://your-domain.atlassian.net/browse/HELPDESK-1"
  }
}

Get customer request by id or key

GET /rest/servicedeskapi/request/{issueIdOrKey}

This method returns a customer request.

Permissions required: Permission to access the specified service desk.

Response limitations: For customers, only a request they created, was created on their behalf, or they are participating in will be returned.

Note: requestFieldValues does not include hidden fields. To get a list of request type fields that includes hidden fields, see /rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/field

Connect app scope required: READ

OAuth 2.0 scopes required:
ClassicRECOMMENDED:read:servicedesk-request
Granular:read:request:jira-service-management, read:user:jira

Request

Path parameters
issueIdOrKey Required

string

The ID or Key of the customer request to be returned

Query parameters
expand

Array<string>

A multi-value parameter indicating which properties of the customer request to expand, where:

  • serviceDesk returns additional service desk details.
  • requestType returns additional customer request type details.
  • participant returns the participant details.
  • sla returns the SLA information.
  • status returns the status transitions, in chronological order.
  • attachment returns the attachments.
  • action returns the actions that the user can or cannot perform.
  • comment returns the comments.
  • comment.attachment returns the attachment details for each comment.
  • comment.renderedBody (Experimental) return the rendered body in HTML format (in addition to the raw body) for each comment.

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returns the customer request.

Content typeValue
application/json

CustomerRequestDTO

Example response (application/json)

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
{
  "_expands": [
    "participant",
    "status",
    "sla",
    "requestType",
    "serviceDesk",
    "attachment",
    "action",
    "comment"
  ],
  "issueId": "107001",
  "issueKey": "HELPDESK-1",
  "requestTypeId": "25",
  "serviceDeskId": "10",
  "createdDate": {
    "iso8601": "2015-10-08T14:42:00+0700",
    "jira": "2015-10-08T14:42:00.000+0700",
    "friendly": "Monday 14:42 PM",
    "epochMillis": 1444290120000
  },
  "reporter": {
    "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "emailAddress": "fred@example.com",
    "displayName": "Fred F. User",
    "active": true,
    "timeZone": "Australia/Sydney",
    "_links": {
      "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
      "avatarUrls": {
        "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
        "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
        "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
        "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
      },
      "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
    }
  },
  "requestFieldValues": [
    {
      "fieldId": "summary",
      "label": "What do you need?",
      "value": "Request JSD help via REST"
    },
    {
      "fieldId": "description",
      "label": "Why do you need this?",
      "value": "I need a new *mouse* for my Mac",
      "renderedValue": {
        "html": "<p>I need a new <b>mouse</b> for my Mac</p>"
      }
    }
  ],
  "currentStatus": {
    "status": "Waiting for Support",
    "statusCategory": "NEW",
    "statusDate": {
      "iso8601": "2015-10-08T14:01:00+0700",
      "jira": "2015-10-08T14:01:00.000+0700",
      "friendly": "Today 14:01 PM",
      "epochMillis": 1444287660000
    }
  },
  "_links": {
    "jiraRest": "https://your-domain.atlassian.net/rest/api/2/issue/107001",
    "web": "https://your-domain.atlassian.net/servicedesk/customer/portal/10/HELPDESK-1",
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/107001",
    "agent": "https://your-domain.atlassian.net/browse/HELPDESK-1"
  }
}

Get approvals

GET /rest/servicedeskapi/request/{issueIdOrKey}/approval

This method returns all approvals on a customer request.

Permissions required: Permission to view the customer request.

Connect app scope required: READ

OAuth 2.0 scopes required:
ClassicRECOMMENDED:read:servicedesk-request
Granular:read:request.approval:jira-service-management, read:user:jira

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the customer request to be queried for its approvals.

Query parameters
start

integer

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

Format: int32
limit

integer

The maximum number of approvals to return per page. Default: 50. See the Pagination section for more details.

Format: int32

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/approval' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returns the customer request's approvals.

Content typeValue
application/json

PagedDTOApprovalDTO

Example response (application/json)

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
{
  "_expands": [],
  "size": 3,
  "start": 3,
  "limit": 3,
  "isLastPage": false,
  "_links": {
    "base": "https://your-domain.atlassian.net/rest/servicedeskapi",
    "context": "context",
    "next": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2/approval?start=6&limit=3",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2/approval?start=0&limit=3"
  },
  "values": [
    {
      "id": "1",
      "name": "Please approve this request",
      "finalDecision": "approved",
      "canAnswerApproval": false,
      "approvers": [
        {
          "approver": {
            "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "emailAddress": "fred@example.com",
            "displayName": "Fred F. User",
            "active": true,
            "timeZone": "Australia/Sydney",
            "_links": {
              "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
              "avatarUrls": {
                "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
                "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
                "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
                "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
              },
              "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
            }
          },
          "approverDecision": "approved"
        }
      ],
      "createdDate": {
        "iso8601": "2016-09-28T14:01:00+0700",
        "jira": "2016-09-28T14:01:00.000+0700",
        "friendly": "Monday 14:01 PM",
        "epochMillis": 1475046060000
      },
      "completedDate": {
        "iso8601": "2016-09-29T14:30:00+0700",
        "jira": "2016-09-29T14:30:00.000+0700",
        "friendly": "Today 14:30 PM",
        "epochMillis": 1475134200000
      },
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2/approval/1"
      }
    },
    {
      "id": "2",
      "name": "Waiting for approval",
      "finalDecision": "declined",
      "canAnswerApproval": false,
      "approvers": [
        {
          "approver": {
            "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "emailAddress": "fred@example.com",
            "displayName": "Fred F. User",
            "active": true,
            "timeZone": "Australia/Sydney",
            "_links": {
              "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
              "avatarUrls": {
                "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
                "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
                "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
                "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
              },
              "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
            }
          },
          "approverDecision": "approved"
        }
      ],
      "createdDate": {
        "iso8601": "2016-10-05T14:01:00+0700",
        "jira": "2016-10-05T14:01:00.000+0700",
        "friendly": "Wednesday 14:01 PM",
        "epochMillis": 1475650860000
      },
      "completedDate": {
        "iso8601": "2016-10-06T14:30:00+0700",
        "jira": "2016-10-06T14:30:00.000+0700",
        "friendly": "Thursday 14:30 PM",
        "epochMillis": 1475739000000
      },
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2/approval/2"
      }
    }
  ]
}

Get approval by id

GET /rest/servicedeskapi/request/{issueIdOrKey}/approval/{approvalId}

This method returns an approval. Use this method to determine the status of an approval and the list of approvers.

Permissions required: Permission to view the customer request.

Connect app scope required: READ

OAuth 2.0 scopes required:
ClassicRECOMMENDED:read:servicedesk-request
Granular:read:request.approval:jira-service-management, read:user:jira

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the customer request the approval is on.

approvalId Required

integer

The ID of the approval to be returned.

Format: int32

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/approval/{approvalId}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returns the requested approval.

Content typeValue
application/json

ApprovalDTO

Example response (application/json)

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
{
  "id": "1",
  "name": "Please approve this request",
  "finalDecision": "approved",
  "canAnswerApproval": false,
  "approvers": [
    {
      "approver": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "approverDecision": "approved"
    }
  ],
  "createdDate": {
    "iso8601": "2016-09-28T14:01:00+0700",
    "jira": "2016-09-28T14:01:00.000+0700",
    "friendly": "Monday 14:01 PM",
    "epochMillis": 1475046060000
  },
  "completedDate": {
    "iso8601": "2016-09-29T14:30:00+0700",
    "jira": "2016-09-29T14:30:00.000+0700",
    "friendly": "Today 14:30 PM",
    "epochMillis": 1475134200000
  },
  "_links": {
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2/approval/1"
  }
}

Answer approval

POST /rest/servicedeskapi/request/{issueIdOrKey}/approval/{approvalId}

This method enables a user to Approve or Decline an approval on a customer request. The approval is assumed to be owned by the user making the call.

Permissions required: User is assigned to the approval request.

Connect app scope required: WRITE

OAuth 2.0 scopes required:
ClassicRECOMMENDED:write:servicedesk-request
Granular:read:request.approval:jira-service-management, write:request.approval:jira-service-management, read:user:jira

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the customer request to be updated.

approvalId Required

integer

The ID of the approval to be updated.

Format: int32
Body parameters
decision

string

Response to the approval request.

Valid values: approve, decline

Example

1
2
3
4
5
6
7
8
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/approval/{approvalId}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "decision": "approve"
}'

Responses

Returns the updated approval.

Content typeValue
application/json

ApprovalDTO

Example response (application/json)

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
{
  "id": "1",
  "name": "Please approve this request",
  "finalDecision": "approved",
  "canAnswerApproval": false,
  "approvers": [
    {
      "approver": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "approverDecision": "approved"
    }
  ],
  "createdDate": {
    "iso8601": "2016-09-28T14:01:00+0700",
    "jira": "2016-09-28T14:01:00.000+0700",
    "friendly": "Monday 14:01 PM",
    "epochMillis": 1475046060000
  },
  "completedDate": {
    "iso8601": "2016-09-29T14:30:00+0700",
    "jira": "2016-09-29T14:30:00.000+0700",
    "friendly": "Today 14:30 PM",
    "epochMillis": 1475134200000
  },
  "_links": {
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2/approval/1"
  }
}

Get attachments for request

GET /rest/servicedeskapi/request/{issueIdOrKey}/attachment

This method returns all the attachments for a customer requests.

Permissions required: Permission to view the customer request.

Response limitations: Customers will only get a list of public attachments.

Connect app scope required: READ

OAuth 2.0 scopes required:
ClassicRECOMMENDED:read:servicedesk-request
Granular:read:request.attachment:jira-service-management, read:user:jira

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the customer request from which the attachments will be listed.

Query parameters
start

integer

The starting index of the returned attachment. Base index: 0. See the Pagination section for more details.

Format: int32
limit

integer

The maximum number of comments to return per page. Default: 50. See the Pagination section for more details.

Format: int32

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/attachment' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returns the visible attachments from the customer request.

Content typeValue
application/json

PagedDTOAttachmentDTO

Example response (application/json)

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
{
  "_expands": [],
  "size": 2,
  "start": 2,
  "limit": 2,
  "isLastPage": false,
  "_links": {
    "base": "https://your-domain.atlassian.net/rest/servicedeskapi",
    "context": "context",
    "next": "https://your-domain.atlassian.net/rest/servicedeskapi/request/IT-15/comment/1001/attachment?start=4&limit=2",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/IT-15/comment/1001/attachment?start=0&limit=2"
  },
  "values": [
    {
      "filename": "screenshot.png",
      "author": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "created": {
        "iso8601": "2015-10-09T10:22:00+0700",
        "jira": "2015-10-09T10:22:00.000+0700",
        "friendly": "Today 10:22 AM",
        "epochMillis": 1444360920000
      },
      "size": 23123,
      "mimeType": "image/png",
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/attachment/10000",
        "content": "https://your-domain.atlassian.net/servicedesk/customershim/secure/attachment/10000/screenshot.png",
        "thumbnail": "https://your-domain.atlassian.net/servicedesk/customershim/secure/thumbnail/10000/_thumb_10000.png"
      }
    },
    {
      "filename": "log.txt",
      "author": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "created": {
        "iso8601": "2015-10-09T10:22:00+0700",
        "jira": "2015-10-09T10:22:00.000+0700",
        "friendly": "Today 10:22 AM",
        "epochMillis": 1444360920000
      },
      "size": 32132,
      "mimeType": "text/plain",
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/attachment/10001",
        "content": "https://your-domain.atlassian.net/servicedesk/customershim/secure/attachment/10001/log.txt"
      }
    }
  ]
}

Create attachment

POST /rest/servicedeskapi/request/{issueIdOrKey}/attachment

This method adds one or more temporary files (attached to the request's service desk using servicedesk/{serviceDeskId}/attachTemporaryFile) as attachments to a customer request and set the attachment visibility using the public flag. Also, it is possible to include a comment with the attachments.

To get a list of attachments for a comment on the request use servicedeskapi/request/{issueIdOrKey}/comment/{commentId}/attachment.

Permissions required: Permission to add an attachment.

Request limitations: Customers can set attachments to public visibility only.

Connect app scope required: WRITE

OAuth 2.0 scopes required:
ClassicRECOMMENDED:write:servicedesk-request
Granular:read:request.attachment:jira-service-management, write:request.attachment:jira-service-management, read:user:jira

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the customer request to which the attachment will be added.

Body parameters
temporaryAttachmentIds

Array<string>

List of IDs for the temporary attachments to be added to the customer request.

additionalComment

AdditionalCommentDTO

Comment about the attachments.

public

boolean

Indicates whether the attachments are to be public (true) or private/internal (false).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/attachment' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "temporaryAttachmentIds": [
    "temp910441317820424274",
    "temp3600755449679003114"
  ],
  "public": true,
  "additionalComment": {
    "body": "Please find the screenshot and the log file attached."
  }
}'

Responses

Returns the attachments and comment.

Content typeValue
application/json

AttachmentCreateResultDTO

Example response (application/json)

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
{
  "comment": {
    "_expands": [
      "attachment",
      "renderedBody"
    ],
    "id": "1000",
    "body": "Please find the screenshot and the log file attached. !screenshot.png|thumbnail! [^log.txt] _(32 kB)_",
    "public": true,
    "author": {
      "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
      "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
      "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
      "emailAddress": "fred@example.com",
      "displayName": "Fred F. User",
      "active": true,
      "timeZone": "Australia/Sydney",
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "avatarUrls": {
          "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
          "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
          "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
          "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
        },
        "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
      }
    },
    "created": {
      "iso8601": "2015-10-09T10:22:00+0700",
      "jira": "2015-10-09T10:22:00.000+0700",
      "friendly": "Today 10:22 AM",
      "epochMillis": 1444360920000
    },
    "_links": {
      "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2000/comment/1000"
    }
  },
  "attachments": {
    "_expands": [],
    "size": 2,
    "start": 2,
    "limit": 2,
    "isLastPage": false,
    "_links": {
      "base": "https://your-domain.atlassian.net/rest/servicedeskapi",
      "context": "context",
      "next": "https://your-domain.atlassian.net/rest/servicedeskapi/request/IT-15/comment/1001/attachment?start=4&limit=2",
      "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/IT-15/comment/1001/attachment?start=0&limit=2"
    },
    "values": [
      {
        "filename": "screenshot.png",
        "author": {
          "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "emailAddress": "fred@example.com",
          "displayName": "Fred F. User",
          "active": true,
          "timeZone": "Australia/Sydney",
          "_links": {
            "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "avatarUrls": {
              "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
              "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
              "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
              "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
            },
            "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
          }
        },
        "created": {
          "iso8601": "2015-10-09T10:22:00+0700",
          "jira": "2015-10-09T10:22:00.000+0700",
          "friendly": "Today 10:22 AM",
          "epochMillis": 1444360920000
        },
        "size": 23123,
        "mimeType": "image/png",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/attachment/10000",
          "content": "https://your-domain.atlassian.net/servicedesk/customershim/secure/attachment/10000/screenshot.png",
          "thumbnail": "https://your-domain.atlassian.net/servicedesk/customershim/secure/thumbnail/10000/_thumb_10000.png"
        }
      },
      {
        "filename": "log.txt",
        "author": {
          "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "emailAddress": "fred@example.com",
          "displayName": "Fred F. User",
          "active": true,
          "timeZone": "Australia/Sydney",
          "_links": {
            "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "avatarUrls": {
              "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
              "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
              "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
              "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
            },
            "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
          }
        },
        "created": {
          "iso8601": "2015-10-09T10:22:00+0700",
          "jira": "2015-10-09T10:22:00.000+0700",
          "friendly": "Today 10:22 AM",
          "epochMillis": 1444360920000
        },
        "size": 32132,
        "mimeType": "text/plain",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/attachment/10001",
          "content": "https://your-domain.atlassian.net/servicedesk/customershim/secure/attachment/10001/log.txt"
        }
      }
    ]
  }
}

Get attachment content

GET /rest/servicedeskapi/request/{issueIdOrKey}/attachment/{attachmentId}

Returns the contents of an attachment.

To return a thumbnail of the attachment, use servicedeskapi/request/{issueIdOrKey}/attachment/{attachmentId}/thumbnail.

Permissions required: For the issue containing the attachment:

Connect app scope required: READ

OAuth 2.0 scopes required:
ClassicRECOMMENDED:read:servicedesk-request
Granular:read:request.attachment:jira-service-management, read:user:jira

Request

Path parameters
issueIdOrKey Required

string

The ID or key for the customer request the attachment is associated with

attachmentId Required

integer

The ID for the attachment

Format: int64

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/attachment/{attachmentId}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

200 response

Content typeValue
application/json

anything

Get attachment thumbnail

GET /rest/servicedeskapi/request/{issueIdOrKey}/attachment/{attachmentId}/thumbnail

Returns the thumbnail of an attachment.

To return the attachment contents, use servicedeskapi/request/{issueIdOrKey}/attachment/{attachmentId}.

Permissions required: For the issue containing the attachment:

Connect app scope required: READ

OAuth 2.0 scopes required:
ClassicRECOMMENDED:read:servicedesk-request
Granular:read:request.attachment:jira-service-management, read:user:jira

Request

Path parameters
issueIdOrKey Required

string

The ID or key for the customer request the attachment is associated with

attachmentId Required

integer

The ID of the attachment.

Format: int64

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/attachment/{attachmentId}/thumbnail' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

200 response

Content typeValue
application/json

anything

Get request comments

GET /rest/servicedeskapi/request/{issueIdOrKey}/comment

This method returns all comments on a customer request. No permissions error is provided if, for example, the user doesn't have access to the service desk or request, the method simply returns an empty response.

Permissions required: Permission to view the customer request.

Response limitations: Customers are returned public comments only.

Connect app scope required: READ

OAuth 2.0 scopes required:
ClassicRECOMMENDED:read:servicedesk-request
Granular:read:request.comment:jira-service-management, read:user:jira

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the customer request whose comments will be retrieved.

Query parameters
public

boolean

Specifies whether to return public comments or not. Default: true.

internal

boolean

Specifies whether to return internal comments or not. Default: true.

expand

Array<string>

A multi-value parameter indicating which properties of the comment to expand:

  • attachment returns the attachment details, if any, for each comment. (If you want to get all attachments for a request, use servicedeskapi/request/{issueIdOrKey}/attachment.)
  • renderedBody (Experimental) returns the rendered body in HTML format (in addition to the raw body) for each comment.
start

integer

The starting index of the returned comments. Base index: 0. See the Pagination section for more details.

Format: int32
limit

integer

The maximum number of comments to return per page. Default: 50. See the Pagination section for more details.

Format: int32

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/comment' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returns the comments, on the specified page of the results.

Content typeValue
application/json

PagedDTOCommentDTO

Example response (application/json)

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
{
  "_expands": [],
  "size": 1,
  "start": 1,
  "limit": 1,
  "isLastPage": false,
  "_links": {
    "base": "https://your-domain.atlassian.net/rest/servicedeskapi",
    "context": "context",
    "next": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2000/comment?start=2&limit=1",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2000/comment?start=0&limit=1"
  },
  "values": [
    {
      "_expands": [
        "attachment",
        "renderedBody"
      ],
      "id": "1000",
      "body": "Hello there",
      "public": true,
      "author": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "created": {
        "iso8601": "2015-10-09T10:22:00+0700",
        "jira": "2015-10-09T10:22:00.000+0700",
        "friendly": "Today 10:22 AM",
        "epochMillis": 1444360920000
      },
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2000/comment/1000"
      }
    }
  ]
}

Create request comment

POST /rest/servicedeskapi/request/{issueIdOrKey}/comment

This method creates a public or private (internal) comment on a customer request, with the comment visibility set by public. The user recorded as the author of the comment.

Permissions required: User has Add Comments permission.

Request limitations: Customers can set comments to public visibility only.

Connect app scope required: WRITE

OAuth 2.0 scopes required:
ClassicRECOMMENDED:write:servicedesk-request
Granular:read:request.comment:jira-service-management, write:request.comment:jira-service-management, read:user:jira

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the customer request to which the comment will be added.

Body parameters
body

string

Content of the comment.

public

boolean

Indicates whether the comment is public (true) or private/internal (false).

Example

1
2
3
4
5
6
7
8
9
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/comment' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "public": true,
  "body": "Hello there"
}'

Responses

Returns the comment.

Content typeValue
application/json

CommentDTO

Example response (application/json)

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
{
  "_expands": [
    "attachment",
    "renderedBody"
  ],
  "id": "1000",
  "body": "Hello there",
  "public": true,
  "author": {
    "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "emailAddress": "fred@example.com",
    "displayName": "Fred F. User",
    "active": true,
    "timeZone": "Australia/Sydney",
    "_links": {
      "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
      "avatarUrls": {
        "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
        "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
        "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
        "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
      },
      "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
    }
  },
  "created": {
    "iso8601": "2015-10-09T10:22:00+0700",
    "jira": "2015-10-09T10:22:00.000+0700",
    "friendly": "Today 10:22 AM",
    "epochMillis": 1444360920000
  },
  "_links": {
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2000/comment/1000"
  }
}

Get request comment by id

GET /rest/servicedeskapi/request/{issueIdOrKey}/comment/{commentId}

This method returns details of a customer request's comment.

Permissions required: Permission to view the customer request.

Response limitations: Customers can only view public comments on requests where they are the reporter or a participant whereas agents can see both internal and public comments.

Connect app scope required: READ

OAuth 2.0 scopes required:
ClassicRECOMMENDED:read:servicedesk-request
Granular:read:request.comment:jira-service-management, read:user:jira

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the customer request that contains the comment.

commentId Required

integer

The ID of the comment to retrieve.

Format: int64
Query parameters
expand

Array<string>

A multi-value parameter indicating which properties of the comment to expand:

  • attachment returns the attachment details, if any, for the comment. (If you want to get all attachments for a request, use servicedeskapi/request/{issueIdOrKey}/attachment.)
  • renderedBody (Experimental) returns the rendered body in HTML format (in addition to the raw body) of the comment.

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/comment/{commentId}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returns the comment.

Content typeValue
application/json

CommentDTO

Example response (application/json)

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
{
  "_expands": [
    "attachment",
    "renderedBody"
  ],
  "id": "1000",
  "body": "Hello there",
  "public": true,
  "author": {
    "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "emailAddress": "fred@example.com",
    "displayName": "Fred F. User",
    "active": true,
    "timeZone": "Australia/Sydney",
    "_links": {
      "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
      "avatarUrls": {
        "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
        "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
        "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
        "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
      },
      "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
    }
  },
  "created": {
    "iso8601": "2015-10-09T10:22:00+0700",
    "jira": "2015-10-09T10:22:00.000+0700",
    "friendly": "Today 10:22 AM",
    "epochMillis": 1444360920000
  },
  "_links": {
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2000/comment/1000"
  }
}

Get comment attachments

Experimental

GET /rest/servicedeskapi/request/{issueIdOrKey}/comment/{commentId}/attachment

This method returns the attachments referenced in a comment.

Permissions required: Permission to view the customer request.

Response limitations: Customers can only view public comments, and retrieve their attachments, on requests where they are the reporter or a participant whereas agents can see both internal and public comments.

Connect apps cannot access this REST resource.

OAuth 2.0 scopes required:
read:request.attachment:jira-service-management
,
read:request.comment:jira-service-management
, read:user:jira

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the customer request that contains the comment.

commentId Required

integer

The ID of the comment.

Format: int64
Query parameters
start

integer

The starting index of the returned comments. Base index: 0. See the Pagination section for more details.

Format: int32
limit

integer

The maximum number of comments to return per page. Default: 50. See the Pagination section for more details.

Format: int32

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/comment/{commentId}/attachment' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returns the attachments, on the specified page of the results.

Content typeValue
application/json

PagedDTOAttachmentDTO

Example response (application/json)

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
{
  "_expands": [],
  "size": 2,
  "start": 2,
  "limit": 2,
  "isLastPage": false,
  "_links": {
    "base": "https://your-domain.atlassian.net/rest/servicedeskapi",
    "context": "context",
    "next": "https://your-domain.atlassian.net/rest/servicedeskapi/request/IT-15/comment/1001/attachment?start=4&limit=2",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/IT-15/comment/1001/attachment?start=0&limit=2"
  },
  "values": [
    {
      "filename": "screenshot.png",
      "author": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "created": {
        "iso8601": "2015-10-09T10:22:00+0700",
        "jira": "2015-10-09T10:22:00.000+0700",
        "friendly": "Today 10:22 AM",
        "epochMillis": 1444360920000
      },
      "size": 23123,
      "mimeType": "image/png",
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/attachment/10000",
        "content": "https://your-domain.atlassian.net/servicedesk/customershim/secure/attachment/10000/screenshot.png",
        "thumbnail": "https://your-domain.atlassian.net/servicedesk/customershim/secure/thumbnail/10000/_thumb_10000.png"
      }
    },
    {
      "filename": "log.txt",
      "author": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "created": {
        "iso8601": "2015-10-09T10:22:00+0700",
        "jira": "2015-10-09T10:22:00.000+0700",
        "friendly": "Today 10:22 AM",
        "epochMillis": 1444360920000
      },
      "size": 32132,
      "mimeType": "text/plain",
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/attachment/10001",
        "content": "https://your-domain.atlassian.net/servicedesk/customershim/secure/attachment/10001/log.txt"
      }
    }
  ]
}

Get subscription status

GET /rest/servicedeskapi/request/{issueIdOrKey}/notification

This method returns the notification subscription status of the user making the request. Use this method to determine if the user is subscribed to a customer request's notifications.

Permissions required: Permission to view the customer request.

Connect app scope required: READ

OAuth 2.0 scopes required:
ClassicRECOMMENDED:read:servicedesk-request
Granular:read:request.notification:jira-service-management, read:user:jira

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the customer request to be queried for subscription status.

Example

1
2
3
4
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/notification' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Returns the status of the notification subscription.

Content typeValue
application/json

RequestNotificationSubscriptionDTO

Example response (application/json)

1
2
3
{
  "subscribed": true
}

Subscribe

PUT /rest/servicedeskapi/request/{issueIdOrKey}/notification

This method subscribes the user to receiving notifications from a customer request.

Permissions required: Permission to view the customer request.

Connect app scope required: WRITE

OAuth 2.0 scopes required:
ClassicRECOMMENDED:write:servicedesk-request
Granular:read:request.notification:jira-service-management, write:request.notification:jira-service-management, read:user:jira