Jira Service Desk Cloud Developer

Jira Service Desk Cloud Developer

Rate this page:

Servicedesk

Get service desks

GET /rest/servicedeskapi/servicedesk

This method returns all the service desks in the Jira Service Desk 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.

Permissions required: Any

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

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 items to return per page. Default: 100. See the Pagination section for more details.

Format: int32

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk' \
  --header 'Accept: application/json'

Responses

Returns the service desks, on the specified page of the results.

Content typeValue
application/json

PagedDTOServiceDeskDTO

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
{
  "_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"
      }
    }
  ]
}

Get service desk by id

GET /rest/servicedeskapi/servicedesk/{serviceDeskId}

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.

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk to return. This can alternatively be a project identifier.

Format: int64

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}' \
  --header 'Accept: application/json'

Responses

Returns the requested service desk.

Content typeValue
application/json

ServiceDeskDTO

Example response (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"
  }
}

Attach temporary file

POST /rest/servicedeskapi/servicedesk/{serviceDeskId}/attachTemporaryFile

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

1
curl -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.

App scope required: WRITE

OAuth scopes required: 
write:servicedesk-request

Request

Path parameters
serviceDeskId Required

integer

The ID of the Service Desk to which the file will be attached. This can alternatively be a project identifier.

Format: int64
Body parameters
Content typeValue
multipart/form-data

string

Example

1
2
3
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/attachTemporaryFile' \
  --header 'Accept: application/json'

Responses

Returns if the file(s) were attached.

Content typeValue
application/json

anything

Example response (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"
    }
  ]
}

Get customers

GET /rest/servicedeskapi/servicedesk/{serviceDeskId}/customer

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.

App scope required: READ

OAuth scopes required: 
manage:servicedesk-customer

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk the customer list should be returned from. This can alternatively be a project identifier.

Format: int64
Query parameters
query

string

The string used to filter the customer list.

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 users to return per page. Default: 50. See the Pagination section for more details.

Format: int32

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/customer' \
  --header 'Accept: application/json'

Responses

Returns the service desk's customer list.

Content typeValue
application/json

PagedDTOUserDTO

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
{
  "_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": {
          "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"
      }
    }
  ]
}

Add customers

POST /rest/servicedeskapi/servicedesk/{serviceDeskId}/customer

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

App scope required: WRITE

OAuth scopes required: 
manage:servicedesk-customer

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk the customer list should be returned from. This can alternatively be a project identifier.

Format: int64
Body parameters
usernames

Array<string>

This property is no longer available and will be removed from the documentation soon. See the deprecation notice for details. Use accountIds instead.

Unique items: true
accountIds

Array<string>

List of users, specified by account IDs, to add to or remove from a service desk.

Unique items: true

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/servicedesk/{serviceDeskId}/customer' \
  --header 'Content-Type: application/json' \
  --data '{
  "accountIds": [
    "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd",
    "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d69abfa3980ce712caae"
  ],
  "usernames": [
    "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd",
    "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d69abfa3980ce712caae"
  ]
}'

Responses

Returned if all the customers were added to the service desk or were already associated with the service desk.

Remove customers

DELETE /rest/servicedeskapi/servicedesk/{serviceDeskId}/customer

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

Apps cannot access this REST resource.

OAuth scopes required: 
manage:servicedesk-customer

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk the customers should be removed from. This can alternatively be a project identifier.

Format: int64
Body parameters
usernames

Array<string>

This property is no longer available and will be removed from the documentation soon. See the deprecation notice for details. Use accountIds instead.

Unique items: true
accountIds

Array<string>

List of users, specified by account IDs, to add to or remove from a service desk.

Unique items: true

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/customer' \
  --header 'Content-Type: application/json' \
  --data '{
  "accountIds": [
    "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd",
    "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d69abfa3980ce712caae"
  ],
  "usernames": [
    "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd",
    "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d69abfa3980ce712caae"
  ]
}'

Responses

Returned if the customers were removed from the service desk, or any of the customers were not associated with the service desk.

Get articles

GET /rest/servicedeskapi/servicedesk/{serviceDeskId}/knowledgebase/article

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.

App scope required: READ

Request

Path parameters
serviceDeskId Required

integer

Format: int64
Query parameters
query

string

The string used to filter the articles (required).

highlight

boolean

If set to true matching query term in the title and excerpt will be highlighted using the {@code

Default: false
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: 100. See the Pagination section for more details.

Format: int32

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/knowledgebase/article' \
  --header 'Accept: application/json'

Responses

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

Content typeValue
application/json

PagedDTOArticleDTO

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
{
  "_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//knowledgebase/article?start=4&limit=2",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk//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"
      }
    }
  ]
}

Get queues

GET /rest/servicedeskapi/servicedesk/{serviceDeskId}/queue

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.

App scope required: READ

OAuth scopes required: 
read:jira-work

Request

Path parameters
serviceDeskId Required

integer

ID of the service desk whose queues will be returned. This can alternatively be a project identifier.

Format: int64
Query parameters
includeCount

boolean

Specifies whether to include each queue's customer request (issue) count in the response.

Default: false
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
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/queue' \
  --header 'Accept: application/json'

Responses

Returns the queues of the service desk, on the specified page of the results.

Content typeValue
application/json

PagedDTOQueueDTO

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
{
  "_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"
      }
    }
  ]
}

Get queue

GET /rest/servicedeskapi/servicedesk/{serviceDeskId}/queue/{queueId}

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.

App scope required: READ

OAuth scopes required: 
read:jira-work

Request

Path parameters
serviceDeskId Required

integer

ID of the service desk whose queues will be returned. This can alternatively be a project identifier.

Format: int64
queueId Required

integer

ID of the required queue.

Format: int64
Query parameters
includeCount

boolean

Specifies whether to include each queue's customer request (issue) count in the response.

Default: false

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/queue/{queueId}' \
  --header 'Accept: application/json'

Responses

Returns the specific queue of the service desk.

Content typeValue
application/json

QueueDTO

Example response (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"
  }
}

Get issues in queue

GET /rest/servicedeskapi/servicedesk/{serviceDeskId}/queue/{queueId}/issue

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.

App scope required: READ

OAuth scopes required: 
read:jira-work

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk containing the queue to be queried. This can alternatively be a project identifier.

Format: int64
queueId Required

integer

The ID of the queue whose customer requests will be returned.

Format: int64
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 items to return per page. Default: 50. See the Pagination section for more details.

Format: int32

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/queue/{queueId}/issue' \
  --header 'Accept: application/json'

Responses

Returns the customer requests belonging to the queue, on the specified page of the results.

Content typeValue
application/json

PagedDTOIssueBean

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
{
  "_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": [
    {
      "id": "10001",
      "self": "https://your-domain.atlassian.net/rest/servicedeskapi/rest/api/2/issue/10001",
      "key": "SD-1",
      "fields": {
        "summary": "My keyboard is broken",
        "issuetype": {
          "self": "https://your-domain.atlassian.net/rest/api/2/issuetype/13",
          "id": "13",
          "description": "For general IT problems and questions. Created by Jira Service Desk.",
          "iconUrl": "https://your-domain.atlassian.net/servicedesk/issue-type-icons?icon=it-help",
          "name": "IT Help",
          "subtask": false,
          "avatarId": 10002
        },
        "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": {
              "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"
          }
        }
      }
    }
  ]
}

Get request types

GET /rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype

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".

Permissions required: Permission to access the service desk.

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk whose customer request types are to be returned. This can alternatively be a project identifier.

Format: int32
Query parameters
groupId

integer

Filters results to those in a customer request type group.

Format: int32
expand

Array<string>

searchQuery

string

The string to be used to filter the results.

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: 100. See the Pagination section for more details.

Format: int32

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype' \
  --header 'Accept: application/json'

Responses

Returns the requested customer request types, on the specified page of the results.

Content typeValue
application/json

PagedDTORequestTypeDTO

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
{
  "_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/28/requesttype?start=6&limit=3",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/28/requesttype?start=0&limit=3"
  },
  "values": [
    {
      "_expands": [],
      "id": "11001",
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/28/requesttype/11001"
      },
      "name": "Get IT Help",
      "description": "Get IT Help",
      "helpText": "Please tell us clearly the problem you have within 100 words.",
      "issueTypeId": "12345",
      "serviceDeskId": "28",
      "groupIds": [
        "12"
      ],
      "icon": {
        "id": "12345",
        "_links": {
          "iconUrls": {
            "48x48": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=large&avatarId=12345",
            "24x24": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=small&avatarId=12345",
            "16x16": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=xsmall&avatarId=12345",
            "32x32": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=medium&avatarId=12345"
          }
        }
      }
    },
    {
      "_expands": [],
      "id": "11002",
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/28/requesttype/11002"
      },
      "name": "Request a new account",
      "description": "Request a new account",
      "issueTypeId": "12345",
      "serviceDeskId": "28",
      "groupIds": [
        "13",
        "14"
      ],
      "icon": {
        "id": "12346",
        "_links": {
          "iconUrls": {
            "48x48": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=large&avatarId=12346",
            "24x24": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=small&avatarId=12346",
            "16x16": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=xsmall&avatarId=12346",
            "32x32": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=medium&avatarId=12346"
          }
        }
      }
    },
    {
      "_expands": [],
      "id": "11003",
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/28/requesttype/11003"
      },
      "name": "Hardware request",
      "description": "Request a hardware support",
      "issueTypeId": "12345",
      "serviceDeskId": "28",
      "groupIds": [
        "13"
      ],
      "icon": {
        "id": "12347",
        "_links": {
          "iconUrls": {
            "48x48": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=large&avatarId=12347",
            "24x24": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=small&avatarId=12347",
            "16x16": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=xsmall&avatarId=12347",
            "32x32": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=medium&avatarId=12347"
          }
        }
      }
    }
  ]
}

Create request type

POST /rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype

This method enables a customer request type to be added to a service desk based on an issue type. Note that not all customer request type fields can be specified in the request and these fields are given the following default values:

  • Request type icon is given the headset icon.
  • Request type groups is left empty, which means this customer request type will not be visible on the customer portal.
  • Request type status mapping is left empty, so the request type has no custom status mapping but inherits the status map from the issue type upon which it is based.

  • Request type field mapping is set to show the required fields as specified by the issue type used to create the customer request type.

These fields can be updated by a service desk administrator using the Request types option in Project settings.
Request Types are created in next-gen projects by creating Issue Types. Please use the Jira Cloud Platform Create issue type endpoint instead.

Permissions required: Service desk's administrator

App scope required: PROJECT_ADMIN

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk where the customer request type is to be created. This can alternatively be a project identifier.

Format: int32
Body parameters
issueTypeId

string

ID of the request type to add to the service desk.

name

string

Name of the request type on the service desk.

description

string

Description of the request type on the service desk.

helpText

string

Help text for the request type on the service desk.

Example

1
2
3
4
5
6
7
8
9
10
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "issueTypeId": "12345",
  "helpText": "Please tell us clearly the problem you have within 100 words.",
  "name": "Get IT Help",
  "description": "Get IT Help"
}'

Responses

Returns the customer request type created.

Content typeValue
application/json

RequestTypeDTO

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
{
  "_expands": [],
  "id": "11001",
  "_links": {
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/28/requesttype/11001"
  },
  "name": "Get IT Help",
  "description": "Get IT Help",
  "helpText": "Please tell us clearly the problem you have within 100 words.",
  "issueTypeId": "12345",
  "serviceDeskId": "28",
  "groupIds": [
    "12"
  ],
  "icon": {
    "id": "12345",
    "_links": {
      "iconUrls": {
        "48x48": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=large&avatarId=12345",
        "24x24": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=small&avatarId=12345",
        "16x16": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=xsmall&avatarId=12345",
        "32x32": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=medium&avatarId=12345"
      }
    }
  }
}

Get request type by id

GET /rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}

This method returns a customer request type from a service desk.

Permissions required: Permission to access the service desk.

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk whose customer request type is to be returned. This can alternatively be a project identifier.

Format: int32
requestTypeId Required

integer

The ID of the customer request type to be returned.

Format: int32
Query parameters
expand

Array<string>

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}' \
  --header 'Accept: application/json'

Responses

Returns the customer request type item.

Content typeValue
application/json

RequestTypeDTO

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
{
  "_expands": [],
  "id": "11001",
  "_links": {
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/28/requesttype/11001"
  },
  "name": "Get IT Help",
  "description": "Get IT Help",
  "helpText": "Please tell us clearly the problem you have within 100 words.",
  "issueTypeId": "12345",
  "serviceDeskId": "28",
  "groupIds": [
    "12"
  ],
  "icon": {
    "id": "12345",
    "_links": {
      "iconUrls": {
        "48x48": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=large&avatarId=12345",
        "24x24": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=small&avatarId=12345",
        "16x16": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=xsmall&avatarId=12345",
        "32x32": "https://your-domain.atlassian.net/secure/viewavatar?avatarType=SD_REQTYPE&size=medium&avatarId=12345"
      }
    }
  }
}

Get request type fields

GET /rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/field

This method returns the fields for a service desk's customer request type.

Also, the following information about the user's permissions for the request type is returned:

  • canRaiseOnBehalfOf returns true if the user has permission to raise customer requests on behalf of other customers. Otherwise, returns false.
  • canAddRequestParticipants returns true if the user can add customer request participants. Otherwise, returns false.

Permissions required: Permission to view the Service Desk.

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk containing the request types whose fields are to be returned. This can alternatively be a project identifier.

Format: int32
requestTypeId Required

integer

The ID of the request types whose fields are to be returned.

Format: int32

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/field' \
  --header 'Accept: application/json'

Responses

Returns the request type's fields and user permission details, on the specified page of the results.

Content typeValue
application/json

CustomerRequestCreateMetaDTO

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
{
  "requestTypeFields": [
    {
      "fieldId": "summary",
      "name": "What do you need?",
      "required": true,
      "validValues": [],
      "jiraSchema": {
        "type": "string",
        "system": "summary"
      }
    },
    {
      "fieldId": "customfield_10000",
      "name": "Nominee",
      "required": true,
      "validValues": [],
      "jiraSchema": {
        "type": "user",
        "custom": "com.atlassian.jira.plugin.system.customfieldtypes:userpicker",
        "customId": 10000
      }
    },
    {
      "fieldId": "customfield_10001",
      "name": "Gifts",
      "required": true,
      "validValues": [
        {
          "value": "10000",
          "label": "Bottle of Wine",
          "children": []
        },
        {
          "value": "10001",
          "label": "Threadless Voucher",
          "children": []
        },
        {
          "value": "10002",
          "label": "2 Movie Tickets",
          "children": []
        }
      ],
      "jiraSchema": {
        "type": "string",
        "custom": "com.atlassian.jira.plugin.system.customfieldtypes:radiobuttons",
        "customId": 10001
      }
    }
  ],
  "canRaiseOnBehalfOf": true,
  "canAddRequestParticipants": true
}

Get properties keys

GET /rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property

Returns the keys of all properties for a request type.

Properties for a Request Type in next-gen are stored as Issue Type properties and therefore the keys of all properties for a request type are also available by calling the Jira Cloud Platform Get issue type property keys endpoint.

Permissions required: The user must have permission to view the request type.

Apps cannot access this REST resource.

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
requestTypeId Required

integer

The ID of the request type for which keys will be retrieved.

Format: int32
serviceDeskId Required

integer

The ID of the service desk which contains the request type. This can alternatively be a project identifier.

Format: int32

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property' \
  --header 'Accept: application/json'

Responses

Returned if the request type was found.

Content typeValue
application/json

PropertyKeys

Example response (application/json)

1
2
3
4
5
6
7
8
{
  "keys": [
    {
      "self": "/rest/servicedeskapi/servicedesk/1/requestType/2/property/propertyKey",
      "key": "requestType.attributes"
    }
  ]
}

Get property

GET /rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property/{propertyKey}

Returns the value of the property from a request type.

Properties for a Request Type in next-gen are stored as Issue Type properties and therefore also available by calling the Jira Cloud Platform Get issue type property endpoint.

Permissions required: User must have permission to view the request type.

Apps cannot access this REST resource.

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk which contains the request type. This can alternatively be a project identifier.

Format: int32
requestTypeId Required

integer

The ID of the request type from which the property will be retrieved.

Format: int32
propertyKey Required

string

The key of the property to return.

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property/{propertyKey}' \
  --header 'Accept: application/json'

Responses

Returned if the request type property was returned.

Content typeValue
application/json

EntityProperty

Example response (application/json)

1
2
3
4
5
6
7
{
  "key": "organization.attributes",
  "value": {
    "priority": "high",
    "color": "green"
  }
}

Set property

PUT /rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property/{propertyKey}

Sets the value of a request type property. Use this resource to store custom data against a request type.

Properties for a Request Type in next-gen are stored as Issue Type properties and therefore can also be set by calling the Jira Cloud Platform Set issue type property endpoint.

Permissions required: Jira project administrator with a Jira Service Desk agent license.

Apps cannot access this REST resource.

OAuth scopes required: 
manage:jira-project

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk which contains the request type. This can alternatively be a project identifier.

Format: int32
requestTypeId Required

integer

The ID of the request type on which the property will be set.

Format: int32
propertyKey Required

string

The key of the request type property. The maximum length of the key is 255 bytes.

Example

1
2
3
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property/{propertyKey}' \
  --header 'Accept: application/json'

Responses

Returned if the request type property is updated.

Content typeValue
application/json

object

Delete property

DELETE /rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property/{propertyKey}

Removes a property from a request type.

Properties for a Request Type in next-gen are stored as Issue Type properties and therefore can also be deleted by calling the Jira Cloud Platform Delete issue type property endpoint.

Permissions required: Jira project administrator with a Jira Service Desk agent license.

Apps cannot access this REST resource.

OAuth scopes required: 
manage:jira-project

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk which contains the request type. This can alternatively be a project identifier.

Format: int32
requestTypeId Required

integer

The ID of the request type for which the property will be removed.

Format: int32
propertyKey Required

string

The key of the property to remove.

Example

1
2
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property/{propertyKey}'

Responses

Returned if the request type property was removed.

Get request type groups

GET /rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttypegroup

This method returns a service desk's customer request type groups. Jira Service Desk administrators can arrange the customer request type groups in an arbitrary order for display on the customer portal; the groups are returned in this order.

Permissions required: Permission to view the service desk.

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk whose customer request type groups are to be returned. This can alternatively be a project identifier.

Format: int32
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 items to return per page. Default: 100. See the Pagination section for more details.

Format: int32

Example

1
2
3
curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttypegroup' \
  --header 'Accept: application/json'

Responses

Returns the service desk's customer request type groups, on the specified page of the results.

Content typeValue
application/json

PagedDTORequestTypeGroupDTO

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
{
  "_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//requesttypegroup?start=6&limit=3",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk//requesttypegroup?start=0&limit=3"
  },
  "values": [
    {
      "id": "12",
      "name": "Common Requests"
    },
    {
      "id": "13",
      "name": "Logins and Accounts"
    },
    {
      "id": "14",
      "name": "Servers and Infrastructure"
    }
  ]
}

Rate this page: