This method returns all the service desks in the Jira Service Management instance that the user has permission to access. Use this method where you need a list of service desks or need to locate a service desk by name or keyword.
Note: This method will be slow if the instance has hundreds of service desks. If you want to fetch a single service desk by its ID, use /rest/servicedeskapi/servicedesk/{serviceDeskId} instead.
Permissions required: Any
Connect app scope required: READ
read:servicedesk-requestread:servicedesk:jira-service-managementinteger
integer
Returns the service desks, on the specified page of the results.
1
2
3
4
curl --request GET \
--url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: 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
{
"_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/servicedesk?start=6&limit=3",
"prev": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk?start=0&limit=3"
},
"values": [
{
"id": "10001",
"projectId": "11001",
"projectName": "IT Help Desk",
"projectKey": "ITH",
"_links": {
"self": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/10001"
}
},
{
"id": "10002",
"projectId": "11002",
"projectName": "HR Self Serve Desk",
"projectKey": "HR",
"_links": {
"self": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/10002"
}
},
{
"id": "10003",
"projectId": "11003",
"projectName": "Foundation Leave",
"projectKey": "FL",
"_links": {
"self": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/10003"
}
}
]
}This method returns a service desk. Use this method to get service desk details whenever your application component is passed a service desk ID but needs to display other service desk details.
Permissions required: Permission to access the Service Desk. For example, being the Service Desk's Administrator or one of its Agents or Users.
Connect app scope required: READ
read:servicedesk-requestread:servicedesk:jira-service-managementstring
RequiredReturns the requested service desk.
1
2
3
4
curl --request GET \
--url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
{
"id": "10001",
"projectId": "11001",
"projectName": "IT Help Desk",
"projectKey": "ITH",
"_links": {
"self": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/10001"
}
}This method adds one or more temporary attachments to a service desk, which can then be permanently attached to a customer request using servicedeskapi/request/{issueIdOrKey}/attachment.
Note: It is possible for a service desk administrator to turn off the ability to add attachments to a service desk.
This method expects a multipart request. The media-type multipart/form-data is defined in RFC 1867. Most client libraries have classes that make dealing with multipart posts simple. For instance, in Java the Apache HTTP Components library provides MultiPartEntity.
Because this method accepts multipart/form-data, it has XSRF protection on it. This means you must submit a header of X-Atlassian-Token: no-check with the request or it will be blocked.
The name of the multipart/form-data parameter that contains the attachments must be file.
For example, to upload a file called myfile.txt in the Service Desk with ID 10001 use
1curl -D- -u customer:customer -X POST -H "X-ExperimentalApi: opt-in" -H "X-Atlassian-Token: no-check" -F "file=@myfile.txt" https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/10001/attachTemporaryFile
Permissions required: Permission to add attachments in this Service Desk.
Connect app scope required: WRITE
write:servicedesk-requestread:request.attachment:jira-service-management, write:request.attachment:jira-service-managementstring
Requiredarray<MultipartFile>
array<string>
string
boolean
object
string
string
Resource
integer
Returns if the file(s) were attached.
any
1
2
3
4
curl --request POST \
--url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/attachTemporaryFile' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
{
"temporaryAttachments": [
{
"temporaryAttachmentId": "temp8186986881700442965",
"fileName": "atlassian.png"
},
{
"temporaryAttachmentId": "temp589064256337898328",
"fileName": "readme.txt"
}
]
}This method returns a list of the customers on a service desk.
The returned list of customers can be filtered using the query parameter. The parameter is matched against customers' displayName, name, or email. For example, searching for "John", "Jo", "Smi", or "Smith" will match a user with display name "John Smith".
Permissions required: Permission to view this Service Desk's customers.
Connect app scope required: READ
manage:servicedesk-customerread:servicedesk.customer:jira-service-management, read:user:jirastring
Requiredstring
integer
integer
Returns the service desk's customer list.
1
2
3
4
curl --request GET \
--url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/customer' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: 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
{
"_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/servicedesk/1/customer?start=2&limit=1",
"prev": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/1/customer?start=0&limit=1"
},
"values": [
{
"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": {
"16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%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",
"32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue",
"48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue"
},
"self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
}
}
]
}Adds one or more customers to a service desk. If any of the passed customers are associated with the service desk, no changes will be made for those customers and the resource returns a 204 success code.
Permissions required: Service desk administrator
Connect app scope required: WRITE
manage:servicedesk-customerread:servicedesk.customer:jira-service-management, write:servicedesk.customer:jira-service-managementstring
Requiredarray<string>
array<string>
Returned if all the customers were added to the service desk or were already associated with the service desk.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl --request POST \
--url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/customer' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"accountIds": [
"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd",
"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d69abfa3980ce712caae"
],
"usernames": [
"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd",
"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d69abfa3980ce712caae"
]
}'This method removes one or more customers from a service desk. The service desk must have closed access. If any of the passed customers are not associated with the service desk, no changes will be made for those customers and the resource returns a 204 success code.
Permissions required: Services desk administrator
Connect apps cannot access this REST resource.
manage:servicedesk-customerread:servicedesk.customer:jira-service-management, delete:servicedesk.customer:jira-service-managementstring
Requiredarray<string>
array<string>
Returned if the customers were removed from the service desk, or any of the customers were not associated with the service desk.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl --request DELETE \
--url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/customer' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"accountIds": [
"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd",
"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d69abfa3980ce712caae"
],
"usernames": [
"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd",
"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d69abfa3980ce712caae"
]
}'Returns articles which match the given query and belong to the knowledge base linked to the service desk.
Permissions required: Permission to access the service desk.
Connect app scope required: READ
read:knowledgebase:jira-service-managementstring
Requiredstring
Requiredboolean
integer
integer
Returns the articles, on the specified page of the results.
1
2
3
4
curl --request GET \
--url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/knowledgebase/article?query={query}' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: 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
{
"_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/servicedesk/%7BserviceDeskId%7D/knowledgebase/article?start=4&limit=2",
"prev": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/%7BserviceDeskId%7D/knowledgebase/article?start=0&limit=2"
},
"values": [
{
"title": "Stolen computer",
"excerpt": "assuming your computer was stolen",
"source": {
"type": "confluence",
"pageId": "8786177",
"spaceKey": "IT"
},
"content": {
"iframeSrc": "https://your-domain.atlassian.net/rest/servicedeskapi/knowledgebase/article/view/8786177"
}
},
{
"title": "Upgrading computer",
"excerpt": "each computer older then 3 years can be upgraded",
"source": {
"type": "confluence",
"pageId": "8785228",
"spaceKey": "IT"
},
"content": {
"iframeSrc": "https://your-domain.atlassian.net/rest/servicedeskapi/knowledgebase/article/view/8785228"
}
}
]
}This method returns the queues in a service desk. To include a customer request count for each queue (in the issueCount field) in the response, set the query parameter includeCount to true (its default is false).
Permissions required: service desk's Agent.
Connect app scope required: READ
read:jira-workread:queue:jira-service-management, read:user:jira, read:jql:jirastring
Requiredboolean
integer
integer
Returns the queues of the service desk, on the specified page of the results.
1
2
3
4
curl --request GET \
--url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/queue' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: 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
{
"_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/servicedesk/1/queue?start=4&limit=2",
"prev": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/1/queue?start=0&limit=2"
},
"values": [
{
"id": "10",
"name": "Unassigned issues",
"jql": "project = SD AND assignee is EMPTY AND resolution = Unresolved ORDER BY \"Time to resolution\" ASC",
"fields": [
"issuetype",
"issuekey",
"summary",
"created",
"reporter",
"duedate"
],
"issueCount": 10,
"_links": {
"self": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/1/queue/10"
}
},
{
"id": "20",
"name": "Assigned to me",
"jql": "project = SD AND assignee = currentUser() AND resolution = Unresolved ORDER BY \"Time to resolution\" ASC",
"fields": [
"issuetype",
"issuekey",
"summary",
"created",
"reporter",
"duedate"
],
"issueCount": 10,
"_links": {
"self": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/1/queue/20"
}
}
]
}This method returns a specific queues in a service desk. To include a customer request count for the queue (in the issueCount field) in the response, set the query parameter includeCount to true (its default is false).
Permissions required: service desk's Agent.
Connect app scope required: READ
read:jira-workread:queue:jira-service-management, read:user:jira, read:jql:jirastring
Requiredinteger
Requiredboolean
Returns the specific queue of the service desk.
1
2
3
4
curl --request GET \
--url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/queue/{queueId}' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"id": "20",
"name": "Assigned to me",
"jql": "project = SD AND assignee = currentUser() AND resolution = Unresolved ORDER BY \"Time to resolution\" ASC",
"fields": [
"issuetype",
"issuekey",
"summary",
"created",
"reporter",
"duedate"
],
"issueCount": 10,
"_links": {
"self": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/1/queue/20"
}
}This method returns the customer requests in a queue. Only fields that the queue is configured to show are returned. For example, if a queue is configured to show description and due date, then only those two fields are returned for each customer request in the queue.
Permissions required: Service desk's agent.
Connect app scope required: READ
read:jira-workread:queue:jira-service-management, read:user:jira, read:issue:jirastring
Requiredinteger
Requiredinteger
integer
Returns the customer requests belonging to the queue, on the specified page of the results.
1
2
3
4
curl --request GET \
--url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/queue/{queueId}/issue' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: 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
{
"_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/servicedesk/1/queue/10/issue?start=2&limit=1",
"prev": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/1/queue/10/issue?start=0&limit=1"
},
"values": [
{
"fields": {
"summary": "My keyboard is broken",
"issuetype": {
"avatarId": 10002,
"description": "For general IT problems and questions. Created by Jira Service Management.",
"iconUrl": "https://your-domain.atlassian.net/servicedesk/issue-type-icons?icon=it-help",
"id": "13",
"name": "IT Help",
"self": "https://your-domain.atlassian.net/rest/api/2/issuetype/13",
"subtask": false
},
"duedate": "2015-11-11T14:17:13.000+0700",
"created": "2015-11-09T14:17:13.000+0700",
"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": {
"16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%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",
"32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue",
"48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue"
},
"self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
}
}
},
"id": "10001",
"key": "SD-1",
"self": "https://your-domain.atlassian.net/rest/servicedeskapi/rest/api/2/issue/10001"
}
]
}This method returns all customer request types from a service desk. There are two parameters for filtering the returned list:
groupId which filters the results to items in the customer request type group.searchQuery which is matched against request types' name or description. For example, the strings "Install", "Inst", "Equi", or "Equipment" will match a request type with the name "Equipment Installation Request".Note: This API by default will filter out request types hidden in the portal (i.e. request types without groups and request types where a user doesn't have permission) when searchQuery is provided, unless includeHiddenRequestTypesInSearch is set to true. Restricted request types will not be returned for those who aren't admins.
Permissions required: Permission to access the service desk.
Connect app scope required: READ
read:servicedesk-requestread:requesttype:jira-service-managementstring
Requiredinteger
array<string>
string
integer
integer
boolean
string