Cloud

Jira Service Management Cloud / Reference / REST API

Servicedesk

Operations

GET

Get service desks

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

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:servicedesk-request

Granular:read:servicedesk:jira-service-management

Connect app scope required: READ

Request

Query parameters

start

integer

limit

integer

Responses

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

application/json

PagedDTOServiceDeskDTO

GET/rest/servicedeskapi/servicedesk

curl

Node.js

Java

Python

PHP

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

200Response

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

Get service desk by id

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.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:servicedesk-request

Granular:read:servicedesk:jira-service-management

Connect app scope required: READ

Request

Path parameters

serviceDeskId

string

Required

Responses

Returns the requested service desk.

application/json

ServiceDeskDTO

GET/rest/servicedeskapi/servicedesk/{serviceDeskId}

curl

Node.js

Java

Python

PHP

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

200Response

{
  "id": "10001",
  "projectId": "11001",
  "projectName": "IT Help Desk",
  "projectKey": "ITH",
  "_links": {
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/10001"
  }
}

POST

Attach temporary file

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.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:write:servicedesk-request

Granular:read:request.attachment:jira-service-management, write:request.attachment:jira-service-management

Connect app scope required: WRITE

Request

Path parameters

serviceDeskId

string

Required

Request bodymultipart/form-data

array<MultipartFile>

bytes

array<string>

contentType

string

empty

boolean

inputStream

object

name

string

originalFilename

string

resource

Resource

size

integer

Responses

Returns if the file(s) were attached.

application/json

any

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

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/attachTemporaryFile' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

201Response

{
  "temporaryAttachments": [
    {
      "temporaryAttachmentId": "temp8186986881700442965",
      "fileName": "atlassian.png"
    },
    {
      "temporaryAttachmentId": "temp589064256337898328",
      "fileName": "readme.txt"
    }
  ]
}

GET

Get customersExperimental

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.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:servicedesk-customer

Granular:read:servicedesk.customer:jira-service-management, read:user:jira

Connect app scope required: READ

Request

Path parameters

serviceDeskId

string

Required

Query parameters

query

string

start

integer

limit

integer

Responses

Returns the service desk's customer list.

application/json

PagedDTOUserDTO

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

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/customer' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

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

POST

Add customers

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

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:servicedesk-customer

Granular:read:servicedesk.customer:jira-service-management, write:servicedesk.customer:jira-service-management

Connect app scope required: WRITE

Request

Path parameters

serviceDeskId

string

Required

Request bodyapplication/json

accountIds

array<string>

usernames

array<string>

Responses

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

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

curl

Node.js

Java

Python

PHP

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"
  ]
}'

DEL

Remove customersExperimental

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

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:servicedesk-customer

Granular:read:servicedesk.customer:jira-service-management, delete:servicedesk.customer:jira-service-management

Connect apps cannot access this REST resource.

Request

Path parameters

serviceDeskId

string

Required

Request bodyapplication/json

accountIds

array<string>

usernames

array<string>

Responses

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

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

curl

Node.js

Java

Python

PHP

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"
  ]
}'

GET

Get articles

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.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

read:knowledgebase:jira-service-management

Connect app scope required: READ

Request

Path parameters

serviceDeskId

string

Required

Query parameters

query

string

Required

highlight

boolean

start

integer

limit

integer

cursor

string

prev

boolean

Responses

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

application/json

PagedDTOArticleDTO

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

curl

Node.js

Java

Python

PHP

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'

200Response

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

GET

Get queues

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.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:queue:jira-service-management, read:user:jira, read:jql:jira

Connect app scope required: READ

Request

Path parameters

serviceDeskId

string

Required

Query parameters

includeCount

boolean

start

integer

limit

integer

Responses

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

application/json

PagedDTOQueueDTO

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

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/queue' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

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

Get queue

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.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:queue:jira-service-management, read:user:jira, read:jql:jira

Connect app scope required: READ

Request

Path parameters

serviceDeskId

string

Required

queueId

integer

Required

Query parameters

includeCount

boolean

Responses

Returns the specific queue of the service desk.

application/json

QueueDTO

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

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/queue/{queueId}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

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

Get issues in queue

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.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:jira-work

Granular:read:queue:jira-service-management, read:user:jira, read:issue:jira

Connect app scope required: READ

Request

Path parameters

serviceDeskId

string

Required

queueId

integer

Required

Query parameters

start

integer

limit

integer

Responses

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

application/json

PagedDTOIssueBean

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

curl

Node.js

Java

Python

PHP

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'

200Response

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

GET

Get request types

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.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:servicedesk-request

Granular:read:requesttype:jira-service-management

Connect app scope required: READ

Request

Path parameters

serviceDeskId

string

Required

Query parameters

groupId

integer

expand

array<string>

searchQuery

string

start

integer

limit

integer

includeHiddenRequestTypesInSearch

boolean

restrictionStatus

string

Responses

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

application/json

PagedDTORequestTypeDTO

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

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

{
  "_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",
      "portalId": "2",
      "groupIds": [
        "12"
      ],
      "icon": {
        "id": "12345",
        "_links": {
          "iconUrls": {
            "48x48": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12345?size=large",
            "24x24": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12345?size=small",
            "16x16": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12345?size=xsmall",
            "32x32": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12345?size=medium"
          }
        }
      }
    },
    {
      "_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",
      "portalId": "2",
      "groupIds": [
        "13",
        "14"
      ],
      "icon": {
        "id": "12346",
        "_links": {
          "iconUrls": {
            "48x48": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12346?size=large",
            "24x24": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12346?size=small",
            "16x16": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12346?size=xsmall",
            "32x32": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12346?size=medium"
          }
        }
      }
    },
    {
      "_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",
      "portalId": "2",
      "groupIds": [
        "13"
      ],
      "icon": {
        "id": "12347",
        "_links": {
          "iconUrls": {
            "48x48": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12347?size=large",
            "24x24": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12347?size=small",
            "16x16": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12347?size=xsmall",
            "32x32": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12347?size=medium"
          }
        }
      }
    }
  ]
}

POST

Create request typeExperimental

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

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

read:requesttype:jira-service-management

write:requesttype:jira-service-management

Connect app scope required: PROJECT_ADMIN

Request

Path parameters

serviceDeskId

string

Required

Request bodyapplication/json

description

string

helpText

string

issueTypeId

string

name

string

Responses

Returns the customer request type created.

application/json

RequestTypeDTO

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

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "description": "Get IT Help",
  "helpText": "Please tell us clearly the problem you have within 100 words.",
  "issueTypeId": "12345",
  "name": "Get IT Help"
}'

200Response

{
  "_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",
  "portalId": "2",
  "groupIds": [
    "12"
  ],
  "icon": {
    "id": "12345",
    "_links": {
      "iconUrls": {
        "48x48": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12345?size=large",
        "24x24": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12345?size=small",
        "16x16": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12345?size=xsmall",
        "32x32": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12345?size=medium"
      }
    }
  }
}

POST

Check request type permissionsExperimental

Returns:

a list of request type IDs where the given user has permission to administer.
a list of request type IDs where the given user has permission to submit the request.

If no account ID is provided, the operation returns details for the logged in user.

Note that:

invalid request type IDs are ignored.
a maximum of 50 request types can be checked.

Permissions required:

Administer Jira or Project Administrator to check the permissions for other users.

However, Connect apps can make a call from the app server to the product to obtain permission details for any user, without admin permission. This Connect app ability doesn't apply to calls made using AP.request() in a browser.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:servicedesk-request

Granular:read:requesttype:jira-service-management

Connect app scope required: READ

Request

Path parameters

serviceDeskId

string

Required

Request bodyapplication/json

Details of the permissions to check.

accountId

string

permissions

array<string>

requestTypeIds

array<integer>

Responses

Returned if the request is successful.

application/json

RequestTypePermissionCheckResponse

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

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/permissions/check' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "accountId": "<string>",
  "permissions": [
    "canCreateRequest"
  ],
  "requestTypeIds": [
    2154
  ]
}'

200Response

{
  "canAdminister": [
    2154
  ],
  "canCreateRequest": [
    2154
  ]
}

GET

Get request type by id

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

This operation can be accessed anonymously.

Permissions required: Permission to access the service desk.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:servicedesk-request

Granular:read:requesttype:jira-service-management

Connect apps cannot access this REST resource.

Request

Path parameters

serviceDeskId

string

Required

requestTypeId

string

Required

Query parameters

expand

array<string>

Responses

Returns the customer request type item.

application/json

RequestTypeDTO

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

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

{
  "_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",
  "portalId": "2",
  "groupIds": [
    "12"
  ],
  "icon": {
    "id": "12345",
    "_links": {
      "iconUrls": {
        "48x48": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12345?size=large",
        "24x24": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12345?size=small",
        "16x16": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12345?size=xsmall",
        "32x32": "https://your-domain.atlassian.net/rest/api/2/universal_avatar/view/type/SD_REQTYPE/avatar/12345?size=medium"
      }
    }
  }
}

DEL

Delete request typeExperimental

This method deletes a customer request type from a service desk, and removes it from all customer requests.
This only supports classic projects.

Permissions required: Service desk administrator.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

manage:jira-project

Connect app scope required: PROJECT_ADMIN

Request

Path parameters

serviceDeskId

string

Required

requestTypeId

integer

Required

Responses

Returned if the request type is deleted.

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

curl

Node.js

Java

Python

PHP

1
2
3

curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}' \
  --header 'Authorization: Bearer <access_token>'

GET

Get request type fields

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. However, hidden fields would be visible to only Service desk's Administrator.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:servicedesk-request

Granular:read:requesttype:jira-service-management

Connect app scope required: READ

Request

Path parameters

serviceDeskId

string

Required

requestTypeId

integer

Required

Query parameters

expand

array<string>

Responses

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

application/json

CustomerRequestCreateMetaDTO

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

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/field' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

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

GET

Get properties keysExperimental

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.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:servicedesk-request

Granular:read:requesttype.property:jira-service-management

Connect apps cannot access this REST resource.

Request

Path parameters

requestTypeId

integer

Required

serviceDeskId

string

Required

Responses

Returned if the request type was found.

application/json

PropertyKeys

List of property keys.

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

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

{
  "entityPropertyKeyBeans": [
    {
      "key": "requestType.attributes",
      "self": "/rest/servicedeskapi/servicedesk/1/requestType/2/property/propertyKey"
    }
  ]
}

GET

Get propertyExperimental

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.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:servicedesk-request

Granular:read:requesttype.property:jira-service-management

Connect apps cannot access this REST resource.

Request

Path parameters

serviceDeskId

string

Required

requestTypeId

integer

Required

propertyKey

string

Required

Responses

Returned if the request type property was returned.

application/json

EntityProperty

An entity property, for more information see Entity properties.

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

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property/{propertyKey}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

{
  "key": "organization.attributes",
  "value": {
    "color": "green",
    "priority": "high"
  }
}

PUT

Set propertyExperimental

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 Management agent license.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-project

Granular:read:requesttype.property:jira-service-management, write:requesttype.property:jira-service-management

Connect apps cannot access this REST resource.

Request

Path parameters

serviceDeskId

string

Required

requestTypeId

integer

Required

propertyKey

string

Required

Responses

Returned if the request type property is updated.

application/json

any

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

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property/{propertyKey}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

DEL

Delete propertyExperimental

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 Management agent license.

Data Security Policy: Exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:manage:jira-project

Granular:read:requesttype.property:jira-service-management, delete:requesttype.property:jira-service-management

Connect apps cannot access this REST resource.

Request

Path parameters

serviceDeskId

string

Required

requestTypeId

integer

Required

propertyKey

string

Required

Responses

Returned if the request type property was removed.

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

curl

Node.js

Java

Python

PHP

1
2
3

curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttype/{requestTypeId}/property/{propertyKey}' \
  --header 'Authorization: Bearer <access_token>'

GET

Get request type groups

This method returns a service desk's customer request type groups. Jira Service Management 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.

Data Security Policy: Not exempt from app access rules

Scopes

OAuth 2.0 scopes required:

ClassicRECOMMENDED:read:servicedesk-request

Granular:read:requesttype:jira-service-management

Connect app scope required: READ

Request

Path parameters

serviceDeskId

string

Required

Query parameters

start

integer

limit

integer

Responses

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

application/json

PagedDTORequestTypeGroupDTO

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

curl

Node.js

Java

Python

PHP

curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/requesttypegroup' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

200Response

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