Jira Service Desk Cloud Developer

Jira Service Desk Cloud Developer

About

This is the reference for the Jira Service Desk Cloud REST APIs. The REST APIs are for developers who want to integrate Jira Service Desk with other applications or administrators that want to automate their workflows and processes.

Jira Cloud Platform APIs

Jira Service Desk is built upon the Jira platform. As such, in Jira Service Desk you have access to the Jira platform REST APIs.

If you are writing an Atlassian Connect app, your app can request access to the Jira platform REST APIs by using the correct Jira platform Connect Scopes.

Permissions and roles

Permissions control the level of a user's access to the Jira Service Desk instance, while roles are how the permissions are assigned to individual users.

For detailed information on roles and permissions, see Permissions overview and Setting up service desk users.

Permission types

  • Global - These apply to applications as a whole, not individual projects.
  • Project - Organized into permission schemes, these apply to projects.
  • Issue - Organized into security schemes, these allow the visibility of individual issues to be adjusted.

Roles

  • Jira System Administrator - can perform all Jira administration functions.
  • Jira Administrator - can perform most Jira administration functions.
  • Service desk Administrator (Project role - Administrator) - assigned to specific Service Desks and manages those service desk’s configurations.
  • Agent (Project role - service desk Team member) - assigned to specific Service Desks and manages and responds to Requests.
  • Customer - can submit and update their Requests, and may participate in Requests raised by other Customers.

Service desk types

It is also worth noting that the ability of Customers to raise Requests depends on the service desk type, which can be:

  • Public (sign up): Anyone who has the service desk URL can submit requests, and a user (customer) is created for them when a request is submitted.
  • Open: Any user in the system can submit requests, they don’t need to be associated with the service desk.
  • Closed: Only users associated with the service desk can submit requests.

For more details, see Managing access to your service desk in the Jira Service Desk Cloud documentation.

Authentication

The Jira Service Desk REST API uses the same authentication methods as Jira Cloud.

Authentication for Atlassian Connect apps

If you are building an Atlassian Connect app to interact with the Jira Service Desk Cloud REST API, authentication is handled by JWT (JSON Web Token) technology. This is built into the supported Atlassian Connect libraries. At a high level, a security context is exchanged when the app is installed, and this context is used to create and validate JWT tokens, embedded in API calls. To learn more, read the Authentication for apps guide.

Authentication for REST API requests

If you are integrating directly with the Jira Service Desk Cloud REST APIs it is recommended to use OAuth authentication method. For implementations with low security requirements, such as scripts and bots, it is also possible to use Basic authentication method.

Jira Service Desk itself uses cookie-based authentication in the browser, so you can call the REST API from JavaScript on the page and rely on the authentication that the browser has established.

Authentication for other integrations

Note: This functionality is not available yet, but we will be releasing a developer preview soon.

If you are building an integration that does not use Atlassian Connect, use OAuth 2.0 authorization code grants (also known as three-legged OAuth) for authentication. Note, the base URL for requests made via OAuth 2.0 authorization code grants is https://api.atlassian.com. If you are copying the examples in this document, you'll need to change the URLs from https://your-domain.atlassian.net/{api} to https://api.atlassian.com/ex/jira/{cloudid}/{api}. To learn more, read OAuth 2.0 authorization code grants (3LO).

Scopes

Scopes provide static authorization for Atlassian Connect apps. If you are using your own credentials to make REST calls, then these scopes do not apply.

Scopes are defined in the Connect app descriptor and specify the maximum set of actions that an app may perform: read, write, etc. This security level is enforced by Atlassian Connect and cannot be bypassed by app implementations.

Jira Service Desk REST Scopes:

  • READ – can view, browse, read information from Jira
  • WRITE – can create or edit content in Jira, but not delete them (implies: READ)
  • DELETE – can delete entities from Jira (implies: READ, WRITE)
  • PROJECT_ADMIN – can administer a project in Jira (implies: READ, WRITE, DELETE)
  • ADMIN – can administer the entire Jira instance (implies: READ, WRITE, DELETE, PROJECT_ADMIN)
  • ACT_AS_USER - can enact services on a user's behalf.

Status codes and responses

  • Status 200 Returned if the requested content (GET) is returned or content is updated (PUT).
  • Status 201 Returned if new records are created (PUT).
  • Status 204 Returned where the request may or may not have been actioned, but the outcome is as expected. For example, the request was to remove a customer from an organization, but the customer was not associated with the organization.
  • Status 400 Returned if the request was invalid.
  • Status 401 Returned if the user is not logged in. Resolve by logging the user in and reissuing the call.
  • Status 403 Returned if the user does not have the necessary permission to access the resource or run the method.
  • Status 404 Returned if the passed path parameters do not correspond to an object in the instance, for example, no Organization exists for a passed ID.
  • Status 412 Returned if the API is experimental but the X-ExperimentalApi: opt-in header was not passed. For more details, see Experimental methods.

Resources will return a response body in addition to the error status codes. The returned entity for errors is as follows:

1
2
3
4
5
6
7
{
  "errorMessage": "Here is an error message",
  "i18nErrorMessage": {
    "i18nKey": "some.error.key",
    "parameters": []
  }
}

Experimental methods

Methods marked as experimental may change without notice. To use experimental methods, you must include the X-ExperimentalApi: opt-in header in your requests. Use of this header indicates that you are opting into the experimental preview. Once a resource or method moves out of the experimental phase, then the header will no longer be required or checked.

Feedback on the experimental APIs is welcome and can be provided by submitting a feature request or suggestion through the Atlassian Ecosystem Help Center or the Jira Service Desk Ecosystem.

Pagination

The Jira Service Desk REST API uses pagination to conserve server resources and limit the size of responses. Pagination is enforced for methods that could return a large collection. When you make a request to a paged API, the response will wrap the returned values in a JSON object with paging metadata, as follows:

Request

1
http://host:port/context/rest/api-name/resource-name?start=0&limit=10

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "start" : 0,
    "limit" : 10,
    "size" : 7,
    "isLastPage" : true,
    "values": [
        { /* result 0 */ },
        { /* result 1 */ },
        { /* result 2 */ }
        { /* result 3 */ }
        { /* result 4 */ }
        { /* result 5 */ }
        { /* result 6 */ }
    ]
}

Where:

  • start is the index of the first item returned in the page of results.
  • limit is the total number of items that could be returned per page, subject to the maximum server enforced limit for the resource’s method. If limit isn’t specified the default value of the resource is used.
  • size is the number of items returned on this page.
  • isLastPage indicates whether the page is the last page of results.

Clients can use the start, limit, and size parameters to retrieve the desired number of results. Each resource or method has a unique limit on the maximum number of items returned, which cannot be exceeded. If you request size which is larger than the limit, the number of items returned will be capped at the limit for that resource’s method. This behavior can be identified when the first page shows size is less than limit and isLastPage is false.

The limits set for each resource’s method is an implementation detail and may be changed.

Expansion

To simplify API responses, the Jira Service Desk REST API uses resource expansion: the API will only return parts of the resource when explicitly requested.

Use the expand query parameter to specify the list of entities that you want to be expanded, identifying each of them by name. For example, appending ?expand=serviceDesk&expand=requestType to a request’s URI results in the inclusion of the service desk and request type details in the response. The following URL would be used to get that information for the request with the ID JSD-1:

1
http://host:port/context/rest/servicedeskapi/request/JSD-1?expand=serviceDesk&expand=requestType

Alternatively, you can pass the list of entities you want to be expanded as a single comma-separated parameter, as in:

1
http://host:port/context/rest/servicedeskapi/request/JSD-1?expand=serviceDesk,requestType

To discover the expansion identifiers for each entity, look at the _expands property in the parent object. In the JSON example below, the resource declares participant, status, sla, requestType, and serviceDesk as expandable.

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "_expands": [
        "participant",
        "status",
        "sla",
        "requestType",
        "serviceDesk"
    ],
    "issueId": "107001",
    "issueKey": "HELPDESK-1",
    "requestTypeId": "11001",
    "serviceDeskId": "10001",
    ...

Request language

By default, responses are translated based on the requesting user's language preference, or the Jira site default language if anonymous.

Use the requestLanguage query parameter to have responses translated in a specific language, providing an IETF BCP 47 language tag in the form (language code)-(country code) as the value. E.g. ?requestLanguage=en-US for English (United States). Both static text (e.g. error messages) and dynamic user-entered text (e.g. workflow status names) will be translated, if available.

The languages available are based on the installed languages in Jira. If the language tag specified does not match one of Jira's languages, then the query parameter will have no effect.

Dynamic user-entered translations can be edited in Jira administration for global objects (e.g. priority names) and in Language support under project administration for Service Desk projects (e.g. request type names).

Special headers

The following request and response headers define important metadata for the Service Desk REST API resources.

  • X-Atlassian-Token (request): Operations that accept multipart/form-data must include the X-Atlassian-Token: no-check header in requests. Otherwise the request will be blocked by XSRF protection.
  • X-ExperimentalApi (request): Experimental operations must include the X-ExperimentalApi: opt-in header in requests. Otherwise the request will not be processed. See Experimental methods for more details.
  • x-atlassian-force-account-id (request): Operations with the x-atlassian-force-account-id: true header will behave as if GDPR changes are enforced (for example, deprecated fields removed). Use this header to test if your integration is GDPR-compliant. See the migration guide for details.
  • X-AUSERNAME (response): This response header contains either the username of the authenticated user or anonymous. Note that this header is not returned if the request includes the x-atlassian-force-account-id: true header.
  • X-AACCOUNTID (response): This response header contains the Atlassian account ID of the authenticated user.

Using project identifiers

For convenience, any of the resources that require a {serviceDeskId} path parameter also accepts other identifiers.

For example, if a ServiceDesk(id: 15) corresponds to a Project(id: 10012, key: ABC), then issuing a request to any of:

1
2
3
4
5
6
7
/rest/servicedeskapi/servicedesk/ABC

/rest/servicedeskapi/servicedesk/projectKey:ABC

/rest/servicedeskapi/servicedesk/projectId:10012

/rest/servicedeskapi/servicedesk/serviceDeskId:15

is equivalent to issuing a request to:

1
/rest/servicedeskapi/servicedesk/15

Field input formats

Summary - A single line of text.

1
"summary": "An explanation is one line of text."

Description - Multiple lines of text.

1
"description": "A description is multiples lines of text\n separated by\n line feeds.",

Components - Multiple values addressed by 'name'.

1
"components" : [ { "name": "Active Directory"} , { "name": "Network Switch" } ]

Due date - A date in 'YYYY-MM-DD' format.

1
"duedate" : "2015-11-18"

Labels - An array of string values.

1
"labels" : ["examplelabelnumber1", "examplelabelnumber2"]

Checkbox custom field - A custom UI field that enables multiple values to be selected from a defined list of values, with values addressed by 'value' or id.

1
2
3
4
5
"customfield_11440" : [{ "value" : "option1"}, {"value" : "option2"}]

or

"customfield_11440" : [{ "id" : 10112}, {"id" : 10115}]

Date picker custom field - A custom UI field that enables a date in 'YYYY-MM-DD' format to be picked.

1
"customfield_11441" : "2015-11-18"

Date time picker custom field - A custom UI field enables a datetime in ISO 8601 ('YYYY-MM-DDThh:mm:ss.sTZD') format to be picked.

1
"customfield_11442" : "2015-11-18T14:39:00.000+1100"

Labels custom field - A custom UI field that is an array of strings.

1
"customfield_11443" : [ "rest_label1", "rest_label2" ]

Number custom field - A custom UI field that enables a number to be entered.

1
"customfield_11444" : 666

Radio button custom field - A custom UI field that enables a single value to be selected from a defined list of values, with values addressed by value or id.

1
2
3
4
5
"customfield_11445" : { "value": "option2" }

or

"customfield_11445" : { "id": 10112 }

Cascading select custom field - A custom UI field that enables a single parent value and then a related child value to be selected, with values addressed by value or id.

1
2
3
4
5
"customfield_11447" : { "value": "parent_option1", "child": { "value" : "p1_child1"} }

or

"customfield_11447" : { "id": 10112, "child": { "id" : 10115 } }

Multi-select custom field - A custom UI field that enables multiple values to be selected from a defined list of values, with values addressed by value or id.

1
2
3
4
5
"customfield_11448" : [ { "value": "option1" }, { "value": "option2" } ]

or

"customfield_11448" : [ { "id": 10112 }, { "id": 10115 } ]

Single-select custom field - A custom UI field that enables a single value to be selected from a defined list of values, with values address by value or id.

1
2
3
4
5
"customfield_11449" : { "value": "option3" }

or

"customfield_11449" : { "id": 10112 }

Multi-line text custom field - A custom UI field that enables multiple lines of text to be entered.

1
"customfield_11450": "Multiples lines of text\n separated by\n line feeds"

Text custom field - A custom UI field that enables a single line of text to be entered.

1
"customfield_11450": "A single line of text."

URL custom field - A custom UI field that enables a URL to be entered.

1
"customfield_11452" : "http://www.atlassian.com",

Single-user picker custom field - A custom UI field that enables a single user to be selected.

1
"customfield_11453" : { "name":"tommytomtomahawk" },

Multi-user picker custom field - A custom UI field that enables multiple users to be selected.

1
"customfield_11458" : [ { "name":"inigomontoya" }, { "name":"tommytomtomahawk" }]

Attachment - Attachments, using IDs of temporary attachments as provided by the /attachTemporaryFile API.

1
"attachment" : ["4786e3a5-52be-4d5b-bf3d-5f53e54f4559", "1187b2b7-8a75-4eac-88b2-b6e43129ef5c"]

Resource summary

The Jira Service Desk REST API enable you to work with a range of objects from the Jira Service Desk. The main resources provided are:

ResourceDescription
customerThis resource represents customers within your Jira instance. Use it to create new customers.
infoThis resource provides details of the Jira Service Desk software version, builds, and related links.
organizationThis resource enables you to group Jira Service Desk customers together. Use it to create and delete organizations, and add and remove customers from them.
requestThis resource represents the customer requests in your service desks. Use it to create new requests and update request details, such as attachments and comments as well as take actions to update request status or review SLA performance.
requesttypeThis resource enables a list of customer request types, a way to categorize requests in a service desk, to be obtained.
servicedeskThis resource represents a service desk. Use it to retrieve the service desks in your Jira instance, managed the requests service desks can handle, manage the associated customers and organizations, and retrieve details of request queues.

Customer

Create customer

POST /rest/servicedeskapi/customer

This method adds a customer to the Jira Service Desk instance by passing a JSON file including an email address and display name. The display name does not need to be unique. The record's identifiers, name and key, are automatically generated from the request details.

Permissions required: Jira Administrator Global permission

App scope required: ADMIN

OAuth scopes required: 
manage:servicedesk-customer

Request

Body parameters
email

string

Customer's email address.

fullName

string

Deprecated, please use 'displayName'.

displayName

string

Customer's name for display in the UI.

Example

1
2
3
4
5
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/customer' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '"{\"email\":\"fred@example.com\",\"displayName\":\"Fred F. User\"}"'

Responses

Returns the customer details.

Content typeValue
application/json

UserDTO

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "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"
  }
}

Info

Get info

GET /rest/servicedeskapi/info

This method retrieves information about the Jira Service Desk instance such as software version, builds, and related links.

Permissions required: None, the user does not need to be logged in.

App scope required: READ

Request

There are no parameters for this request.

Example

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

Responses

Returns the runtime information for the Jira Service Desk instance.

Content typeValue
application/json

SoftwareInfoDTO

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "version": "3.0.1",
  "platformVersion": "7.0.1",
  "buildDate": {
    "iso8601": "2015-09-15T02:34:00+0700",
    "jira": "2015-09-15T02:34:00.000+0700",
    "friendly": "Monday 02:34 AM",
    "epochMillis": 1442259240000
  },
  "buildChangeSet": "c6679417c550918e7c94a9eaaada133f15dc8ff0",
  "isLicensedForUse": true,
  "_links": {
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/info"
  }
}

Knowledgebase

Get articles

Experimental

GET /rest/servicedeskapi/knowledgebase/article

Returns articles which match the given query string across all service desks.

Permissions required: Permission to access the customer portal.

App scope required: READ

Request

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 @@@hl@@@term@@@endhl@@@} syntax. Default: false.

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/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/knowledgebase/article?start=4&limit=2",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/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/wiki/plugins/servlet/remotepageview?pageId=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/wiki/plugins/servlet/remotepageview?pageId=8785228"
      }
    }
  ]
}

Organization

Get organizations

GET /rest/servicedeskapi/organization

This method returns a list of organizations in the Jira Service Desk instance. Use this method when you want to present a list of organizations or want to locate an organization by name.

Permissions required: Any

Response limitations: If the user is a customer, only those organizations of which the customer is a member are listed.

App scope required: READ

OAuth scopes required: 
manage:servicedesk-customer

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 organizations 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/organization' \
  --header 'Accept: application/json'

Responses

Returns paginated list of organizations.

Content typeValue
application/json

PagedDTOOrganizationDTO

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
{
  "_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/organization?start=2&limit=1",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/organization?start=0&limit=1"
  },
  "values": [
    {
      "id": "1",
      "name": "Charlie Cakes Franchises",
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/organization/1"
      }
    }
  ]
}

Create organization

POST /rest/servicedeskapi/organization

This method creates an organization by passing the name of the organization.

Permissions required: Service desk administrator or agent. Note: Permission to create organizations can be switched to users with the Jira administrator permission, using the Organization management feature.

App scope required: ADMIN

OAuth scopes required: 
manage:servicedesk-customer

Request

Body parameters
name

string

Name of the organization.

Example

1
2
3
4
5
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '"{\"name\":\"Charlie Cakes Franchises\"}"'

Responses

Returns the created organization.

Content typeValue
application/json

OrganizationDTO

Example response (application/json)

1
2
3
4
5
6
7
{
  "id": "1",
  "name": "Charlie Cakes Franchises",
  "_links": {
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/organization/1"
  }
}

Get organization

GET /rest/servicedeskapi/organization/{organizationId}

This method returns details of an organization. Use this method to get organization details whenever your application component is passed an organization ID but needs to display other organization details.

Permissions required: Any

Response limitations: Customers can only retrieve organization of which they are members.

App scope required: READ

OAuth scopes required: 
manage:servicedesk-customer

Request

Path parameters
organizationId Required

integer

The ID of the organization.

Format: int32

Example

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

Responses

Returns the requested organization.

Content typeValue
application/json

OrganizationDTO

Example response (application/json)

1
2
3
4
5
6
7
{
  "id": "1",
  "name": "Charlie Cakes Franchises",
  "_links": {
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/organization/1"
  }
}

Delete organization

DELETE /rest/servicedeskapi/organization/{organizationId}

This method deletes an organization. Note that the organization is deleted regardless of other associations it may have. For example, associations with service desks.

Permissions required: Jira administrator.

App scope required: DELETE

OAuth scopes required: 
manage:servicedesk-customer

Request

Path parameters
organizationId Required

integer

The ID of the organization.

Format: int32

Example

1
2
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}'

Responses

Returned if the organization was deleted.

Get properties keys

GET /rest/servicedeskapi/organization/{organizationId}/property

Returns the keys of all properties for an organization. Use this resource when you need to find out what additional properties items have been added to an organization.

Permissions required: Any

Response limitations: Customers can only access properties of organizations of which they are members.

Apps cannot access this REST resource.

OAuth scopes required: 
manage:servicedesk-customer

Request

Path parameters
organizationId Required

string

The ID of the organization from which keys will be returned.

Example

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

Responses

Returned if the organization was found.

Content typeValue
application/json

PropertyKeys

Example response (application/json)

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

Get property

GET /rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}

Returns the value of a property from an organization. Use this method to obtain the JSON content for an organization's property.

Permissions required: Any

Response limitations: Customers can only access properties of organizations of which they are members.

Apps cannot access this REST resource.

OAuth scopes required: 
manage:servicedesk-customer

Request

Path parameters
organizationId Required

string

The ID of the organization from which the property will be returned.

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/organization/{organizationId}/property/{propertyKey}' \
  --header 'Accept: application/json'

Responses

Returns the organization's property.

Content typeValue
application/json

EntityProperty

Example response (application/json)

1
2
3
4
5
6
7
{
  "key": "organization.attributes",
  "value": {
    "phone": "0800-1233456789",
    "mail": "charlie@example.com"
  }
}

Set property

PUT /rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}

Sets the value of a property for an organization. Use this resource to store custom data against an organization.

Permissions required: Service Desk Administrator or Agent.

Note: Permission to manage organizations can be switched to users with the Jira administrator permission, using the Organization management feature.

Apps cannot access this REST resource.

OAuth scopes required: 
manage:servicedesk-customer

Request

Path parameters
organizationId Required

string

The ID of the organization on which the property will be set.

propertyKey Required

string

The key of the organization's 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/organization/{organizationId}/property/{propertyKey}' \
  --header 'Accept: application/json'

Responses

Returned if the organization property was updated.

Content typeValue
application/json

object

Delete property

DELETE /rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}

Removes a property from an organization.

Permissions required: Service Desk Administrator or Agent.

Note: Permission to manage organizations can be switched to users with the Jira administrator permission, using the Organization management feature.

Apps cannot access this REST resource.

OAuth scopes required: 
manage:servicedesk-customer

Request

Path parameters
organizationId Required

string

The ID of the organization from which the property will be removed.

propertyKey Required

string

The key of the property to remove.

Example

1
2
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}'

Responses

Returned if the organization property was removed.

Get users in organization

GET /rest/servicedeskapi/organization/{organizationId}/user

This method returns all the users associated with an organization. Use this method where you want to provide a list of users for an organization or determine if a user is associated with an organization.

Permissions required: Service desk administrator or agent.

App scope required: READ

OAuth scopes required: 
manage:servicedesk-customer

Request

Path parameters
organizationId Required

integer

The ID of the organization.

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 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/organization/{organizationId}/user' \
  --header 'Accept: application/json'

Responses

Returns a paged list of users associated with the organization.

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
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/organization/1/user?start=2&limit=1",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/organization/1/user?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"
      }
    },
    {
      "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd",
      "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd",
      "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd",
      "emailAddress": "bob@example.com",
      "displayName": "Bob D. Builder",
      "active": true,
      "timeZone": "Australia/Sydney",
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd",
        "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:5ad6d3a01db05e2a66fa80bd"
      }
    }
  ]
}

Add users to organization

POST /rest/servicedeskapi/organization/{organizationId}/user

This method adds users to an organization.

Permissions required: Service desk administrator or agent. Note: Permission to add users to an organization can be switched to users with the Jira administrator permission, using the Organization management feature.

App scope required: ADMIN

OAuth scopes required: 
manage:servicedesk-customer

Request

Path parameters
organizationId Required

integer

The ID of the organization.

Format: int32
Body parameters
usernames

Array<string>

List of customers, specified by user names, to add to or remove from the organization. Either usernames or accountIds can be specified, but not both.
Note that usernames has been deprecated. See the migration guide for details. Use accountIds instead.

accountIds

Array<string>

List of customers, specific by account IDs, to add to or remove from the organization. Only one of usernames or accountIds must be specified.

Example

1
2
3
4
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}/user' \
  --header 'Content-Type: application/json' \
  --data '"{\"usernames\":[],\"accountIds\":[\"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b\",\"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd\"]}"'

Responses

Returned if all the users were valid and added to the organization, no response payload is provided.

Remove users from organization

DELETE /rest/servicedeskapi/organization/{organizationId}/user

This method removes users from an organization.

Permissions required: Service desk administrator or agent. Note: Permission to delete users from an organization can be switched to users with the Jira administrator permission, using the Organization management feature.

App scope required: DELETE

OAuth scopes required: 
manage:servicedesk-customer

Request

Path parameters
organizationId Required

integer

The ID of the organization.

Format: int32
Body parameters
usernames

Array<string>

List of customers, specified by user names, to add to or remove from the organization. Either usernames or accountIds can be specified, but not both.
Note that usernames has been deprecated. See the migration guide for details. Use accountIds instead.

accountIds

Array<string>

List of customers, specific by account IDs, to add to or remove from the organization. Only one of usernames or accountIds must be specified.

Example

1
2
3
4
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}/user' \
  --header 'Content-Type: application/json' \
  --data '"{\"usernames\":[],\"accountIds\":[\"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b\",\"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd\"]}"'

Responses

The request completed successfully. No additional content will be sent in the response.

Get organizations

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

This method returns a list of all organizations associated with a service desk.

Permissions required: Service desk's agent.

App scope required: READ

OAuth scopes required: 
manage:servicedesk-customer

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk from which the organization list will 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: 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}/organization' \
  --header 'Accept: application/json'

Responses

Returns the requested organizations list.

Content typeValue
application/json

PagedDTOOrganizationDTO

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
{
  "_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/10001/organization?start=6&limit=3",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/10001/organization?start=0&limit=3"
  },
  "values": [
    {
      "id": "1",
      "name": "Charlie Cakes Franchises",
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/organization/1"
      }
    },
    {
      "id": "2",
      "name": "Atlas Coffee Co",
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/organization/2"
      }
    },
    {
      "id": "3",
      "name": "The Adjustment Bureau",
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/organization/3"
      }
    }
  ]
}

Add organization

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

This method adds an organization to a service desk. If the organization ID is already associated with the service desk, no change is made and the resource returns a 204 success code.

Permissions required: Service desk's agent.

App scope required: WRITE

OAuth scopes required: 
manage:servicedesk-customer

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk to which the organization will be added. This can alternatively be a project identifier.

Format: int32
Body parameters
organizationId

integer

List of organizations, specified by 'ID' field values, to add to or remove from the service desk.

Format: int32

Example

1
2
3
4
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/organization' \
  --header 'Content-Type: application/json' \
  --data '"{\"organizationId\":1}"'

Responses

Returned if the organization was added or the organization was already associated with the service desk.

Remove organization

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

This method removes an organization from a service desk. If the organization ID does not match an organization associated with the service desk, no change is made and the resource returns a 204 success code.

Permissions required: Service desk's agent.

App scope required: DELETE

OAuth scopes required: 
manage:servicedesk-customer

Request

Path parameters
serviceDeskId Required

integer

The ID of the service desk from which the organization will be removed. This can alternatively be a project identifier.

Format: int32
Body parameters
organizationId

integer

List of organizations, specified by 'ID' field values, to add to or remove from the service desk.

Format: int32

Example

1
2
3
4
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/organization' \
  --header 'Content-Type: application/json' \
  --data '"{\"organizationId\":1}"'

Responses

Returned if the organization was removed from the service desk or no such organization was associated with the service desk.

Request

Get customer requests

GET /rest/servicedeskapi/request

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

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

Permissions required: Permission to access the specified service desk.

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

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Query parameters
searchTerm

string

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

requestOwnership

Array<string>

Filters customer requests using the following values:

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

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

requestStatus

string

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

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

string

Filters results to customer requests based on their approval status:

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

Note: Valid only when used with requestOwnership=APPROVER.

organizationId

integer

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

Format: int32
serviceDeskId

integer

Filters customer requests by service desk.

Format: int32
requestTypeId

integer

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

Format: int32
expand

Array<string>

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

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

integer

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

Format: int32
limit

integer

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

Format: int32

Example

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

Responses

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

Content typeValue
application/json

PagedDTOCustomerRequestDTO

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
{
  "_expands": [
    "participant",
    "status",
    "sla",
    "requestType",
    "serviceDesk",
    "attachment",
    "action",
    "comment"
  ],
  "size": 3,
  "start": 3,
  "limit": 3,
  "isLastPage": false,
  "_links": {
    "base": "https://your-domain.atlassian.net/rest/servicedeskapi",
    "context": "context",
    "next": "https://your-domain.atlassian.net/rest/servicedeskapi/request?start=6&limit=3",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request?start=0&limit=3"
  },
  "values": [
    {
      "_expands": [
        "participant",
        "status",
        "sla",
        "requestType",
        "serviceDesk",
        "attachment",
        "action",
        "comment"
      ],
      "issueId": "107001",
      "issueKey": "HELPDESK-1",
      "requestTypeId": "25",
      "serviceDeskId": "10",
      "createdDate": {
        "iso8601": "2015-10-08T14:42:00+0700",
        "jira": "2015-10-08T14:42:00.000+0700",
        "friendly": "Monday 14:42 PM",
        "epochMillis": 1444290120000
      },
      "reporter": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "requestFieldValues": [
        {
          "fieldId": "summary",
          "label": "What do you need?",
          "value": "Request JSD help via REST"
        },
        {
          "fieldId": "description",
          "label": "Why do you need this?",
          "value": "I need a new *mouse* for my Mac",
          "renderedValue": {
            "html": "<p>I need a new <b>mouse</b> for my Mac</p>"
          }
        }
      ],
      "currentStatus": {
        "status": "Waiting for Support",
        "statusCategory": "NEW",
        "statusDate": {
          "iso8601": "2015-10-08T14:01:00+0700",
          "jira": "2015-10-08T14:01:00.000+0700",
          "friendly": "Today 14:01 PM",
          "epochMillis": 1444287660000
        }
      },
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/issue/107001",
        "web": "https://your-domain.atlassian.net/servicedesk/customer/portal/10/HELPDESK-1",
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/107001"
      }
    },
    {
      "_expands": [
        "participant",
        "status",
        "sla",
        "requestType",
        "serviceDesk",
        "attachment",
        "action",
        "comment"
      ],
      "issueId": "107002",
      "issueKey": "HELPDESK-2",
      "requestTypeId": "25",
      "serviceDeskId": "10",
      "createdDate": {
        "iso8601": "2015-10-08T14:30:00+0700",
        "jira": "2015-10-08T14:30:00.000+0700",
        "friendly": "Monday 14:30 PM",
        "epochMillis": 1444289400000
      },
      "reporter": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "requestFieldValues": [
        {
          "fieldId": "summary",
          "label": "What do you need?",
          "value": "Request a new account"
        },
        {
          "fieldId": "description",
          "label": "Why do you need this?",
          "value": "Create an account on Jira"
        }
      ],
      "currentStatus": {
        "status": "Waiting for Support",
        "statusCategory": "NEW",
        "statusDate": {
          "iso8601": "2015-10-08T14:01:00+0700",
          "jira": "2015-10-08T14:01:00.000+0700",
          "friendly": "Today 14:01 PM",
          "epochMillis": 1444287660000
        }
      },
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/issue/107002",
        "web": "https://your-domain.atlassian.net/servicedesk/customer/portal/10/HELPDESK-2",
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/107002"
      }
    },
    {
      "_expands": [
        "participant",
        "status",
        "sla",
        "requestType",
        "serviceDesk",
        "attachment",
        "action",
        "comment"
      ],
      "issueId": "109006",
      "issueKey": "SIMPLEDESK-6",
      "requestTypeId": "33",
      "serviceDeskId": "12",
      "createdDate": {
        "iso8601": "2015-10-05T14:30:00+0700",
        "jira": "2015-10-05T14:30:00.000+0700",
        "friendly": "Monday 14:30 PM",
        "epochMillis": 1444030200000
      },
      "reporter": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "requestFieldValues": [
        {
          "fieldId": "summary",
          "label": "Summarize the problem",
          "value": "Printer on level 3 did not work"
        },
        {
          "fieldId": "description",
          "value": "Ink cartridge is empty"
        }
      ],
      "currentStatus": {
        "status": "Waiting for Support",
        "statusCategory": "NEW",
        "statusDate": {
          "iso8601": "2015-10-08T14:00:00+0700",
          "jira": "2015-10-08T14:00:00.000+0700",
          "friendly": "Today 14:00 PM",
          "epochMillis": 1444287600000
        }
      },
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/issue/109006",
        "web": "https://your-domain.atlassian.net/servicedesk/customer/portal/12/SIMPLEDESK-6",
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/109006"
      }
    }
  ]
}

Create customer request

POST /rest/servicedeskapi/request

This method creates a customer request in a service desk.

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

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

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

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

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

App scope required: WRITE

OAuth scopes required: 
write:servicedesk-request

Request

Body parameters
serviceDeskId

string

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

requestTypeId

string

ID of the request type for the request.

requestFieldValues

object

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

requestParticipants

Array<string>

List of customers to participate in the request, as a list of name or accountId values.
Note that name has been deprecated, in favour of accountId (see the migration guide for details).

raiseOnBehalfOf

string

The name or accountId of the customer the request is being raised on behalf of.
Note that name has been deprecated, in favour of accountId (see the migration guide for details).

channel

string

(Experimental) Shows extra information for the request channel.

Example

1
2
3
4
5
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '"{\"serviceDeskId\":\"10\",\"requestTypeId\":\"25\",\"requestFieldValues\":{\"summary\":\"Request JSD help via REST\",\"description\":\"I need a new *mouse* for my Mac\"},\"requestParticipants\":[\"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d69abfa3980ce712caae\"]}"'

Responses

Returned if the customer request was created.

Content typeValue
application/json

CustomerRequestDTO

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
{
  "_expands": [
    "participant",
    "status",
    "sla",
    "requestType",
    "serviceDesk",
    "attachment",
    "action",
    "comment"
  ],
  "issueId": "107001",
  "issueKey": "HELPDESK-1",
  "requestTypeId": "25",
  "serviceDeskId": "10",
  "createdDate": {
    "iso8601": "2015-10-08T14:42:00+0700",
    "jira": "2015-10-08T14:42:00.000+0700",
    "friendly": "Monday 14:42 PM",
    "epochMillis": 1444290120000
  },
  "reporter": {
    "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "emailAddress": "fred@example.com",
    "displayName": "Fred F. User",
    "active": true,
    "timeZone": "Australia/Sydney",
    "_links": {
      "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
      "avatarUrls": {
        "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
        "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
        "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
        "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
      },
      "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
    }
  },
  "requestFieldValues": [
    {
      "fieldId": "summary",
      "label": "What do you need?",
      "value": "Request JSD help via REST"
    },
    {
      "fieldId": "description",
      "label": "Why do you need this?",
      "value": "I need a new *mouse* for my Mac",
      "renderedValue": {
        "html": "<p>I need a new <b>mouse</b> for my Mac</p>"
      }
    }
  ],
  "currentStatus": {
    "status": "Waiting for Support",
    "statusCategory": "NEW",
    "statusDate": {
      "iso8601": "2015-10-08T14:01:00+0700",
      "jira": "2015-10-08T14:01:00.000+0700",
      "friendly": "Today 14:01 PM",
      "epochMillis": 1444287660000
    }
  },
  "_links": {
    "jiraRest": "https://your-domain.atlassian.net/rest/api/2/issue/107001",
    "web": "https://your-domain.atlassian.net/servicedesk/customer/portal/10/HELPDESK-1",
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/107001"
  }
}

Get customer request by id or key

GET /rest/servicedeskapi/request/{issueIdOrKey}

This method returns a customer request.

Permissions required: Permission to access the specified service desk.

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

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

The ID or Key of the customer request to be returned

Query parameters
expand

Array<string>

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

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

Example

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

Responses

Returns the customer request.

Content typeValue
application/json

CustomerRequestDTO

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
{
  "_expands": [
    "participant",
    "status",
    "sla",
    "requestType",
    "serviceDesk",
    "attachment",
    "action",
    "comment"
  ],
  "issueId": "107001",
  "issueKey": "HELPDESK-1",
  "requestTypeId": "25",
  "serviceDeskId": "10",
  "createdDate": {
    "iso8601": "2015-10-08T14:42:00+0700",
    "jira": "2015-10-08T14:42:00.000+0700",
    "friendly": "Monday 14:42 PM",
    "epochMillis": 1444290120000
  },
  "reporter": {
    "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "emailAddress": "fred@example.com",
    "displayName": "Fred F. User",
    "active": true,
    "timeZone": "Australia/Sydney",
    "_links": {
      "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
      "avatarUrls": {
        "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
        "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
        "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
        "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
      },
      "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
    }
  },
  "requestFieldValues": [
    {
      "fieldId": "summary",
      "label": "What do you need?",
      "value": "Request JSD help via REST"
    },
    {
      "fieldId": "description",
      "label": "Why do you need this?",
      "value": "I need a new *mouse* for my Mac",
      "renderedValue": {
        "html": "<p>I need a new <b>mouse</b> for my Mac</p>"
      }
    }
  ],
  "currentStatus": {
    "status": "Waiting for Support",
    "statusCategory": "NEW",
    "statusDate": {
      "iso8601": "2015-10-08T14:01:00+0700",
      "jira": "2015-10-08T14:01:00.000+0700",
      "friendly": "Today 14:01 PM",
      "epochMillis": 1444287660000
    }
  },
  "_links": {
    "jiraRest": "https://your-domain.atlassian.net/rest/api/2/issue/107001",
    "web": "https://your-domain.atlassian.net/servicedesk/customer/portal/10/HELPDESK-1",
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/107001"
  }
}

Get approvals

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

This method returns all approvals on a customer request.

Permissions required: Permission to view the customer request.

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

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

Query parameters
start

integer

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

Format: int32
limit

integer

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

Format: int32

Example

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

Responses

Returns the customer request's approvals.

Content typeValue
application/json

PagedDTOApprovalDTO

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
{
  "_expands": [],
  "size": 3,
  "start": 3,
  "limit": 3,
  "isLastPage": false,
  "_links": {
    "base": "https://your-domain.atlassian.net/rest/servicedeskapi",
    "context": "context",
    "next": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2/approval?start=6&limit=3",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2/approval?start=0&limit=3"
  },
  "values": [
    {
      "id": "1",
      "name": "Please approve this request",
      "finalDecision": "approved",
      "canAnswerApproval": false,
      "approvers": [
        {
          "approver": {
            "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "emailAddress": "fred@example.com",
            "displayName": "Fred F. User",
            "active": true,
            "timeZone": "Australia/Sydney",
            "_links": {
              "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
              "avatarUrls": {
                "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
                "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
                "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
                "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
              },
              "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
            }
          },
          "approverDecision": "approved"
        }
      ],
      "createdDate": {
        "iso8601": "2016-09-28T14:01:00+0700",
        "jira": "2016-09-28T14:01:00.000+0700",
        "friendly": "Monday 14:01 PM",
        "epochMillis": 1475046060000
      },
      "completedDate": {
        "iso8601": "2016-09-29T14:30:00+0700",
        "jira": "2016-09-29T14:30:00.000+0700",
        "friendly": "Today 14:30 PM",
        "epochMillis": 1475134200000
      },
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2/approval/1"
      }
    },
    {
      "id": "2",
      "name": "Waiting for approval",
      "finalDecision": "declined",
      "canAnswerApproval": false,
      "approvers": [
        {
          "approver": {
            "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "emailAddress": "fred@example.com",
            "displayName": "Fred F. User",
            "active": true,
            "timeZone": "Australia/Sydney",
            "_links": {
              "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
              "avatarUrls": {
                "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
                "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
                "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
                "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
              },
              "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
            }
          },
          "approverDecision": "approved"
        }
      ],
      "createdDate": {
        "iso8601": "2016-10-05T14:01:00+0700",
        "jira": "2016-10-05T14:01:00.000+0700",
        "friendly": "Wednesday 14:01 PM",
        "epochMillis": 1475650860000
      },
      "completedDate": {
        "iso8601": "2016-10-06T14:30:00+0700",
        "jira": "2016-10-06T14:30:00.000+0700",
        "friendly": "Thursday 14:30 PM",
        "epochMillis": 1475739000000
      },
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2/approval/2"
      }
    }
  ]
}

Get approval by id

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

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

Permissions required: Permission to view the customer request.

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

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

approvalId Required

integer

The ID of the approval to be returned.

Format: int32

Example

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

Responses

Returns the requested approval.

Content typeValue
application/json

ApprovalDTO

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
  "id": "1",
  "name": "Please approve this request",
  "finalDecision": "approved",
  "canAnswerApproval": false,
  "approvers": [
    {
      "approver": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "approverDecision": "approved"
    }
  ],
  "createdDate": {
    "iso8601": "2016-09-28T14:01:00+0700",
    "jira": "2016-09-28T14:01:00.000+0700",
    "friendly": "Monday 14:01 PM",
    "epochMillis": 1475046060000
  },
  "completedDate": {
    "iso8601": "2016-09-29T14:30:00+0700",
    "jira": "2016-09-29T14:30:00.000+0700",
    "friendly": "Today 14:30 PM",
    "epochMillis": 1475134200000
  },
  "_links": {
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2/approval/1"
  }
}

Answer approval

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

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

Permissions required: User is assigned to the approval request.

App scope required: WRITE

OAuth scopes required: 
write:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

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

approvalId Required

integer

The ID of the approval to be updated.

Format: int32
Body parameters
decision

string

Response to the approval request.

Valid values: approve, decline

Example

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

Responses

Returns the updated approval.

Content typeValue
application/json

ApprovalDTO

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
{
  "id": "1",
  "name": "Please approve this request",
  "finalDecision": "approved",
  "canAnswerApproval": false,
  "approvers": [
    {
      "approver": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "approverDecision": "approved"
    }
  ],
  "createdDate": {
    "iso8601": "2016-09-28T14:01:00+0700",
    "jira": "2016-09-28T14:01:00.000+0700",
    "friendly": "Monday 14:01 PM",
    "epochMillis": 1475046060000
  },
  "completedDate": {
    "iso8601": "2016-09-29T14:30:00+0700",
    "jira": "2016-09-29T14:30:00.000+0700",
    "friendly": "Today 14:30 PM",
    "epochMillis": 1475134200000
  },
  "_links": {
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2/approval/1"
  }
}

Get attachments for request

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

This method returns all the attachments for a customer requests.

Permissions required: Permission to view the customer request.

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

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

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

Query parameters
start

integer

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

Format: int32
limit

integer

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

Format: int32

Example

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

Responses

Returns the visible attachments from the customer request.

Content typeValue
application/json

PagedDTOAttachmentDTO

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
{
  "_expands": [],
  "size": 2,
  "start": 2,
  "limit": 2,
  "isLastPage": false,
  "_links": {
    "base": "https://your-domain.atlassian.net/rest/servicedeskapi",
    "context": "context",
    "next": "https://your-domain.atlassian.net/rest/servicedeskapi/request/IT-15/comment/1001/attachment?start=4&limit=2",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/IT-15/comment/1001/attachment?start=0&limit=2"
  },
  "values": [
    {
      "filename": "screenshot.png",
      "author": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "created": {
        "iso8601": "2015-10-09T10:22:00+0700",
        "jira": "2015-10-09T10:22:00.000+0700",
        "friendly": "Today 10:22 AM",
        "epochMillis": 1444360920000
      },
      "size": 23123,
      "mimeType": "image/png",
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/attachment/10000",
        "content": "https://your-domain.atlassian.net/servicedesk/customershim/secure/attachment/10000/screenshot.png",
        "thumbnail": "https://your-domain.atlassian.net/servicedesk/customershim/secure/thumbnail/10000/_thumb_10000.png"
      }
    },
    {
      "filename": "log.txt",
      "author": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "created": {
        "iso8601": "2015-10-09T10:22:00+0700",
        "jira": "2015-10-09T10:22:00.000+0700",
        "friendly": "Today 10:22 AM",
        "epochMillis": 1444360920000
      },
      "size": 32132,
      "mimeType": "text/plain",
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/attachment/10001",
        "content": "https://your-domain.atlassian.net/servicedesk/customershim/secure/attachment/10001/log.txt"
      }
    }
  ]
}

Create attachment

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

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

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

Permissions required: Permission to add an attachment.

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

App scope required: WRITE

OAuth scopes required: 
write:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

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

Body parameters
temporaryAttachmentIds

Array<string>

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

additionalComment

AdditionalCommentDTO

Comment about the attachments.

public

boolean

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

Example

1
2
3
4
5
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/attachment' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '"{\"temporaryAttachmentIds\":[\"temp910441317820424274\",\"temp3600755449679003114\"],\"public\":true,\"additionalComment\":{\"body\":\"Please find the screenshot and the log file attached.\"}}"'

Responses

Returns the attachments and comment.

Content typeValue
application/json

AttachmentCreateResultDTO

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
{
  "comment": {
    "_expands": [
      "attachment",
      "renderedBody"
    ],
    "id": "1000",
    "body": "Please find the screenshot and the log file attached. !screenshot.png|thumbnail! [^log.txt] _(32 kB)_",
    "public": true,
    "author": {
      "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
      "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
      "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
      "emailAddress": "fred@example.com",
      "displayName": "Fred F. User",
      "active": true,
      "timeZone": "Australia/Sydney",
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "avatarUrls": {
          "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
          "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
          "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
          "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
        },
        "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
      }
    },
    "created": {
      "iso8601": "2015-10-09T10:22:00+0700",
      "jira": "2015-10-09T10:22:00.000+0700",
      "friendly": "Today 10:22 AM",
      "epochMillis": 1444360920000
    },
    "_links": {
      "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2000/comment/1000"
    }
  },
  "attachments": {
    "_expands": [],
    "size": 2,
    "start": 2,
    "limit": 2,
    "isLastPage": false,
    "_links": {
      "base": "https://your-domain.atlassian.net/rest/servicedeskapi",
      "context": "context",
      "next": "https://your-domain.atlassian.net/rest/servicedeskapi/request/IT-15/comment/1001/attachment?start=4&limit=2",
      "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/IT-15/comment/1001/attachment?start=0&limit=2"
    },
    "values": [
      {
        "filename": "screenshot.png",
        "author": {
          "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "emailAddress": "fred@example.com",
          "displayName": "Fred F. User",
          "active": true,
          "timeZone": "Australia/Sydney",
          "_links": {
            "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "avatarUrls": {
              "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
              "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
              "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
              "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
            },
            "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
          }
        },
        "created": {
          "iso8601": "2015-10-09T10:22:00+0700",
          "jira": "2015-10-09T10:22:00.000+0700",
          "friendly": "Today 10:22 AM",
          "epochMillis": 1444360920000
        },
        "size": 23123,
        "mimeType": "image/png",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/attachment/10000",
          "content": "https://your-domain.atlassian.net/servicedesk/customershim/secure/attachment/10000/screenshot.png",
          "thumbnail": "https://your-domain.atlassian.net/servicedesk/customershim/secure/thumbnail/10000/_thumb_10000.png"
        }
      },
      {
        "filename": "log.txt",
        "author": {
          "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "emailAddress": "fred@example.com",
          "displayName": "Fred F. User",
          "active": true,
          "timeZone": "Australia/Sydney",
          "_links": {
            "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
            "avatarUrls": {
              "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
              "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
              "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
              "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
            },
            "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
          }
        },
        "created": {
          "iso8601": "2015-10-09T10:22:00+0700",
          "jira": "2015-10-09T10:22:00.000+0700",
          "friendly": "Today 10:22 AM",
          "epochMillis": 1444360920000
        },
        "size": 32132,
        "mimeType": "text/plain",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/attachment/10001",
          "content": "https://your-domain.atlassian.net/servicedesk/customershim/secure/attachment/10001/log.txt"
        }
      }
    ]
  }
}

Get request comments

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

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

Permissions required: Permission to view the customer request.

Response limitations: Customers are returned public comments only.

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

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

Query parameters
public

boolean

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

internal

boolean

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

expand

Array<string>

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

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

integer

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

Format: int32
limit

integer

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

Format: int32

Example

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

Responses

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

Content typeValue
application/json

PagedDTOCommentDTO

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
  "_expands": [],
  "size": 1,
  "start": 1,
  "limit": 1,
  "isLastPage": false,
  "_links": {
    "base": "https://your-domain.atlassian.net/rest/servicedeskapi",
    "context": "context",
    "next": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2000/comment?start=2&limit=1",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2000/comment?start=0&limit=1"
  },
  "values": [
    {
      "_expands": [
        "attachment",
        "renderedBody"
      ],
      "id": "1000",
      "body": "Hello there",
      "public": true,
      "author": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "created": {
        "iso8601": "2015-10-09T10:22:00+0700",
        "jira": "2015-10-09T10:22:00.000+0700",
        "friendly": "Today 10:22 AM",
        "epochMillis": 1444360920000
      },
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2000/comment/1000"
      }
    }
  ]
}

Create request comment

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

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

Permissions required: User has Add Comments permission.

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

App scope required: WRITE

OAuth scopes required: 
write:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

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

Body parameters
body

string

Content of the comment.

public

boolean

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

Example

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

Responses

Returns the comment.

Content typeValue
application/json

CommentDTO

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
  "_expands": [
    "attachment",
    "renderedBody"
  ],
  "id": "1000",
  "body": "Hello there",
  "public": true,
  "author": {
    "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "emailAddress": "fred@example.com",
    "displayName": "Fred F. User",
    "active": true,
    "timeZone": "Australia/Sydney",
    "_links": {
      "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
      "avatarUrls": {
        "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
        "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
        "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
        "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
      },
      "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
    }
  },
  "created": {
    "iso8601": "2015-10-09T10:22:00+0700",
    "jira": "2015-10-09T10:22:00.000+0700",
    "friendly": "Today 10:22 AM",
    "epochMillis": 1444360920000
  },
  "_links": {
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2000/comment/1000"
  }
}

Get request comment by id

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

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

Permissions required: Permission to view the customer request.

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

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

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

commentId Required

integer

The ID of the comment to retrieve.

Format: int64
Query parameters
expand

Array<string>

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

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

Example

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

Responses

Returns the comment.

Content typeValue
application/json

CommentDTO

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
  "_expands": [
    "attachment",
    "renderedBody"
  ],
  "id": "1000",
  "body": "Hello there",
  "public": true,
  "author": {
    "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
    "emailAddress": "fred@example.com",
    "displayName": "Fred F. User",
    "active": true,
    "timeZone": "Australia/Sydney",
    "_links": {
      "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
      "avatarUrls": {
        "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
        "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
        "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
        "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
      },
      "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
    }
  },
  "created": {
    "iso8601": "2015-10-09T10:22:00+0700",
    "jira": "2015-10-09T10:22:00.000+0700",
    "friendly": "Today 10:22 AM",
    "epochMillis": 1444360920000
  },
  "_links": {
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/2000/comment/1000"
  }
}

Get comment attachments

Experimental

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

This method returns the attachments referenced in a comment.

Permissions required: Permission to view the customer request.

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

Apps cannot access this REST resource.

Request

Path parameters
issueIdOrKey Required

string

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

commentId Required

integer

The ID of the comment.

Format: int64
Query parameters
start

integer

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

Format: int32
limit

integer

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

Format: int32

Example

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

Responses

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

Content typeValue
application/json

PagedDTOAttachmentDTO

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
{
  "_expands": [],
  "size": 2,
  "start": 2,
  "limit": 2,
  "isLastPage": false,
  "_links": {
    "base": "https://your-domain.atlassian.net/rest/servicedeskapi",
    "context": "context",
    "next": "https://your-domain.atlassian.net/rest/servicedeskapi/request/IT-15/comment/1001/attachment?start=4&limit=2",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/IT-15/comment/1001/attachment?start=0&limit=2"
  },
  "values": [
    {
      "filename": "screenshot.png",
      "author": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "created": {
        "iso8601": "2015-10-09T10:22:00+0700",
        "jira": "2015-10-09T10:22:00.000+0700",
        "friendly": "Today 10:22 AM",
        "epochMillis": 1444360920000
      },
      "size": 23123,
      "mimeType": "image/png",
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/attachment/10000",
        "content": "https://your-domain.atlassian.net/servicedesk/customershim/secure/attachment/10000/screenshot.png",
        "thumbnail": "https://your-domain.atlassian.net/servicedesk/customershim/secure/thumbnail/10000/_thumb_10000.png"
      }
    },
    {
      "filename": "log.txt",
      "author": {
        "accountId": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "name": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "key": "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
        "emailAddress": "fred@example.com",
        "displayName": "Fred F. User",
        "active": true,
        "timeZone": "Australia/Sydney",
        "_links": {
          "jiraRest": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b",
          "avatarUrls": {
            "48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue",
            "24x24": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue",
            "16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue",
            "32x32": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue"
          },
          "self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"
        }
      },
      "created": {
        "iso8601": "2015-10-09T10:22:00+0700",
        "jira": "2015-10-09T10:22:00.000+0700",
        "friendly": "Today 10:22 AM",
        "epochMillis": 1444360920000
      },
      "size": 32132,
      "mimeType": "text/plain",
      "_links": {
        "jiraRest": "https://your-domain.atlassian.net/rest/api/2/attachment/10001",
        "content": "https://your-domain.atlassian.net/servicedesk/customershim/secure/attachment/10001/log.txt"
      }
    }
  ]
}

Get subscription status

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

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

Permissions required: Permission to view the customer request.

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

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

Example

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

Responses

Returns the status of the notification subscription.

Content typeValue
application/json

RequestNotificationSubscriptionDTO

Example response (application/json)

1
2
3
{
  "subscribed": true
}

Subscribe

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

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

Permissions required: Permission to view the customer request.

App scope required: WRITE

OAuth scopes required: 
write:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

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

Example

1
2
curl --request PUT \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/notification'

Responses

Returns if the user was subscribed.

Unsubscribe

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

This method unsubscribes the user from notifications from a customer request.

Permissions required: Permission to view the customer request.

App scope required: WRITE

OAuth scopes required: 
write:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the customer request to be unsubscribed from.

Example

1
2
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/notification'

Responses

Returns if the user was unsubscribed.

Get request participants

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

This method returns a list of all the participants on a customer request.

Permissions required: Permission to view the customer request.

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

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

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 request types 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/request/{issueIdOrKey}/participant' \
  --header 'Accept: application/json'

Responses

Returns the customer request's participants, on the specified page of the results.

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/request/1000/participant?start=2&limit=1",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/1000/participant?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 request participants

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

This method adds participants to a customer request.

Permissions required: Permission to manage participants on the customer request.

Note, participants can be added when creating a customer request using the request resource, by defining the participants in the requestParticipants field.

App scope required: WRITE

OAuth scopes required: 
write:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the customer request to have participants added.

Body parameters
usernames

Array<string>

List of users, specified by user names, to add to or remove as participants in the request. Either usernames or accountIds can be specified, but not both.
Note that usernames has been deprecated. See the migration guide for details. Use accountIds instead.

accountIds

Array<string>

List of users, specified by account IDs, to add to or remove as participants in the request. Only one of usernames or accountIds must be specified.

Example

1
2
3
4
5
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/participant' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '"{\"usernames\":[\"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b\",\"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd\",\"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d69abfa3980ce712caae\"],\"accountIds\":[]}"'

Responses

Returns the participants added to the customer request.

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/request/1000/participant?start=2&limit=1",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/1000/participant?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"
      }
    }
  ]
}

Remove request participants

DELETE /rest/servicedeskapi/request/{issueIdOrKey}/participant

This method removes participants from a customer request.

Permissions required: Permission to manage participants on the customer request.

App scope required: DELETE

OAuth scopes required: 
write:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

The ID or key of the customer request to have participants removed.

Body parameters
usernames

Array<string>

List of users, specified by user names, to add to or remove as participants in the request. Either usernames or accountIds can be specified, but not both.
Note that usernames has been deprecated. See the migration guide for details. Use accountIds instead.

accountIds

Array<string>

List of users, specified by account IDs, to add to or remove as participants in the request. Only one of usernames or accountIds must be specified.

Example

1
2
3
4
5
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/participant' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '"{\"usernames\":[\"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b\",\"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd\",\"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d69abfa3980ce712caae\"],\"accountIds\":[]}"'

Responses

Returns the first page of the customer request's participants (after removal of the users).

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/request/1000/participant?start=2&limit=1",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/1000/participant?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"
      }
    }
  ]
}

Get sla information

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

This method returns all the SLA records on a customer request. A customer request can have zero or more SLAs. Each SLA can have recordings for zero or more "completed cycles" and zero or 1 "ongoing cycle". Each cycle includes information on when it started and stopped, and whether it breached the SLA goal.

Permissions required: Agent for the Service Desk containing the queried customer request.

App scope required: READ

OAuth scopes required: 
read:jira-work

Request

Path parameters
issueIdOrKey Required

string

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

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 request types 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/request/{issueIdOrKey}/sla' \
  --header 'Accept: application/json'

Responses

Returns the SLA records on the customer request, on the specified page of the results.

Content typeValue
application/json

PagedDTOSlaInformationDTO

Example response (application/json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
{
  "_expands": [],
  "size": 3,
  "start": 3,
  "limit": 3,
  "isLastPage": false,
  "_links": {
    "base": "https://your-domain.atlassian.net/rest/servicedeskapi",
    "context": "context",
    "next": "https://your-domain.atlassian.net/rest/servicedeskapi/request/101102/sla?start=6&limit=3",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/101102/sla?start=0&limit=3"
  },
  "values": [
    {
      "name": "Time To First Response",
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/101102/sla/10030"
      },
      "completedCycles": [
        {
          "startTime": {
            "iso8601": "2015-10-09T10:45:23+0700",
            "jira": "2015-10-09T10:45:23.000+0700",
            "friendly": "Yesterday 10:45 AM",
            "epochMillis": 1444362323000
          },
          "stopTime": {
            "iso8601": "2015-10-09T10:52:23+0700",
            "jira": "2015-10-09T10:52:23.000+0700",
            "friendly": "Yesterday 10:52 AM",
            "epochMillis": 1444362743000
          },
          "breached": false,
          "goalDuration": {
            "millis": 14400000,
            "friendly": "4h 240m"
          },
          "elapsedTime": {
            "millis": 420000,
            "friendly": "0h 7m"
          },
          "remainingTime": {
            "millis": 13980000,
            "friendly": "3h 233m"
          }
        },
        {
          "startTime": {
            "iso8601": "2015-10-10T10:52:23+0700",
            "jira": "2015-10-10T10:52:23.000+0700",
            "friendly": "Today 10:52 AM",
            "epochMillis": 1444449143000
          },
          "stopTime": {
            "iso8601": "2015-10-10T16:15:23+0700",
            "jira": "2015-10-10T16:15:23.000+0700",
            "friendly": "Today 16:15 PM",
            "epochMillis": 1444468523000
          },
          "breached": true,
          "goalDuration": {
            "millis": 14400000,
            "friendly": "4h 240m"
          },
          "elapsedTime": {
            "millis": 19380000,
            "friendly": "5h 323m"
          },
          "remainingTime": {
            "millis": -4980000,
            "friendly": "-1h -83m"
          }
        }
      ],
      "ongoingCycle": {
        "startTime": {
          "iso8601": "2015-10-10T19:15:23+0700",
          "jira": "2015-10-10T19:15:23.000+0700",
          "friendly": "Today 19:15 PM",
          "epochMillis": 1444479323000
        },
        "breached": false,
        "paused": false,
        "withinCalendarHours": false,
        "goalDuration": {
          "millis": 14400000,
          "friendly": "4h 240m"
        },
        "elapsedTime": {
          "millis": 5640000,
          "friendly": "1h 94m"
        },
        "remainingTime": {
          "millis": 8760000,
          "friendly": "2h 146m"
        }
      }
    },
    {
      "name": "Time To Resolution",
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/101102/sla/10040"
      },
      "completedCycles": [
        {
          "startTime": {
            "iso8601": "2015-10-09T10:45:23+0700",
            "jira": "2015-10-09T10:45:23.000+0700",
            "friendly": "Yesterday 10:45 AM",
            "epochMillis": 1444362323000
          },
          "stopTime": {
            "iso8601": "2015-10-09T20:52:23+0700",
            "jira": "2015-10-09T20:52:23.000+0700",
            "friendly": "Yesterday 20:52 PM",
            "epochMillis": 1444398743000
          },
          "breached": false,
          "goalDuration": {
            "millis": 72000000,
            "friendly": "20h 1200m"
          },
          "elapsedTime": {
            "millis": 36420000,
            "friendly": "10h 607m"
          },
          "remainingTime": {
            "millis": 35580000,
            "friendly": "9h 593m"
          }
        },
        {
          "startTime": {
            "iso8601": "2015-10-10T20:52:23+0700",
            "jira": "2015-10-10T20:52:23.000+0700",
            "friendly": "Today 20:52 PM",
            "epochMillis": 1444485143000
          },
          "stopTime": {
            "iso8601": "2015-10-11T02:15:23+0700",
            "jira": "2015-10-11T02:15:23.000+0700",
            "friendly": "Today 02:15 AM",
            "epochMillis": 1444504523000
          },
          "breached": true,
          "goalDuration": {
            "millis": 72000000,
            "friendly": "20h 1200m"
          },
          "elapsedTime": {
            "millis": 19380000,
            "friendly": "5h 323m"
          },
          "remainingTime": {
            "millis": 52620000,
            "friendly": "14h 877m"
          }
        }
      ],
      "ongoingCycle": {
        "startTime": {
          "iso8601": "2015-10-11T05:15:23+0700",
          "jira": "2015-10-11T05:15:23.000+0700",
          "friendly": "Today 05:15 AM",
          "epochMillis": 1444515323000
        },
        "breached": false,
        "paused": false,
        "withinCalendarHours": false,
        "goalDuration": {
          "millis": 72000000,
          "friendly": "20h 1200m"
        },
        "elapsedTime": {
          "millis": 5640000,
          "friendly": "1h 94m"
        },
        "remainingTime": {
          "millis": 66360000,
          "friendly": "18h 1106m"
        }
      }
    },
    {
      "name": "Time To Retrospective",
      "_links": {
        "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/101102/sla/10050"
      },
      "completedCycles": [
        {
          "startTime": {
            "iso8601": "2015-10-09T10:45:23+0700",
            "jira": "2015-10-09T10:45:23.000+0700",
            "friendly": "Yesterday 10:45 AM",
            "epochMillis": 1444362323000
          },
          "stopTime": {
            "iso8601": "2015-10-10T10:52:23+0700",
            "jira": "2015-10-10T10:52:23.000+0700",
            "friendly": "Yesterday 10:52 AM",
            "epochMillis": 1444449143000
          },
          "breached": false,
          "goalDuration": {
            "millis": 144000000,
            "friendly": "40h 2400m"
          },
          "elapsedTime": {
            "millis": 86820000,
            "friendly": "24h 1447m"
          },
          "remainingTime": {
            "millis": 57180000,
            "friendly": "15h 953m"
          }
        },
        {
          "startTime": {
            "iso8601": "2015-10-11T10:52:23+0700",
            "jira": "2015-10-11T10:52:23.000+0700",
            "friendly": "Today 10:52 AM",
            "epochMillis": 1444535543000
          },
          "stopTime": {
            "iso8601": "2015-10-11T16:15:23+0700",
            "jira": "2015-10-11T16:15:23.000+0700",
            "friendly": "Today 16:15 PM",
            "epochMillis": 1444554923000
          },
          "breached": true,
          "goalDuration": {
            "millis": 144000000,
            "friendly": "40h 2400m"
          },
          "elapsedTime": {
            "millis": 19380000,
            "friendly": "5h 323m"
          },
          "remainingTime": {
            "millis": 124620000,
            "friendly": "34h 2077m"
          }
        }
      ],
      "ongoingCycle": {
        "startTime": {
          "iso8601": "2015-10-11T19:15:23+0700",
          "jira": "2015-10-11T19:15:23.000+0700",
          "friendly": "Today 19:15 PM",
          "epochMillis": 1444565723000
        },
        "breached": false,
        "paused": false,
        "withinCalendarHours": false,
        "goalDuration": {
          "millis": 144000000,
          "friendly": "40h 2400m"
        },
        "elapsedTime": {
          "millis": 5640000,
          "friendly": "1h 94m"
        },
        "remainingTime": {
          "millis": 138360000,
          "friendly": "38h 2306m"
        }
      }
    }
  ]
}

Get sla information by id

GET /rest/servicedeskapi/request/{issueIdOrKey}/sla/{slaMetricId}

This method returns the details for an SLA on a customer request.

Permissions required: Agent for the Service Desk containing the queried customer request.

App scope required: READ

OAuth scopes required: 
read:jira-work

Request

Path parameters
issueIdOrKey Required

string

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

slaMetricId Required

integer

The ID or key of the SLAs metric to be retrieved.

Format: int64

Example

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

Responses

Returns the SLA record, on the specified page of the results.

Content typeValue
application/json

SlaInformationDTO

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
{
  "name": "Time To First Response",
  "_links": {
    "self": "https://your-domain.atlassian.net/rest/servicedeskapi/request/101102/sla/10030"
  },
  "completedCycles": [
    {
      "startTime": {
        "iso8601": "2015-10-09T10:45:23+0700",
        "jira": "2015-10-09T10:45:23.000+0700",
        "friendly": "Yesterday 10:45 AM",
        "epochMillis": 1444362323000
      },
      "stopTime": {
        "iso8601": "2015-10-09T10:52:23+0700",
        "jira": "2015-10-09T10:52:23.000+0700",
        "friendly": "Yesterday 10:52 AM",
        "epochMillis": 1444362743000
      },
      "breached": false,
      "goalDuration": {
        "millis": 14400000,
        "friendly": "4h 240m"
      },
      "elapsedTime": {
        "millis": 420000,
        "friendly": "0h 7m"
      },
      "remainingTime": {
        "millis": 13980000,
        "friendly": "3h 233m"
      }
    },
    {
      "startTime": {
        "iso8601": "2015-10-10T10:52:23+0700",
        "jira": "2015-10-10T10:52:23.000+0700",
        "friendly": "Today 10:52 AM",
        "epochMillis": 1444449143000
      },
      "stopTime": {
        "iso8601": "2015-10-10T16:15:23+0700",
        "jira": "2015-10-10T16:15:23.000+0700",
        "friendly": "Today 16:15 PM",
        "epochMillis": 1444468523000
      },
      "breached": true,
      "goalDuration": {
        "millis": 14400000,
        "friendly": "4h 240m"
      },
      "elapsedTime": {
        "millis": 19380000,
        "friendly": "5h 323m"
      },
      "remainingTime": {
        "millis": -4980000,
        "friendly": "-1h -83m"
      }
    }
  ],
  "ongoingCycle": {
    "startTime": {
      "iso8601": "2015-10-10T19:15:23+0700",
      "jira": "2015-10-10T19:15:23.000+0700",
      "friendly": "Today 19:15 PM",
      "epochMillis": 1444479323000
    },
    "breached": false,
    "paused": false,
    "withinCalendarHours": false,
    "goalDuration": {
      "millis": 14400000,
      "friendly": "4h 240m"
    },
    "elapsedTime": {
      "millis": 5640000,
      "friendly": "1h 94m"
    },
    "remainingTime": {
      "millis": 8760000,
      "friendly": "2h 146m"
    }
  }
}

Get customer request status

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

This method returns a list of all the statuses a customer Request has achieved. A status represents the state of an issue in its workflow. An issue can have one active status only. The list returns the status history in chronological order, most recent (current) status first.

Permissions required: Permission to view the customer request.

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

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

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/request/{issueIdOrKey}/status' \
  --header 'Accept: application/json'

Responses

Returns the customer request's status history, on the specified page of the results.

Content typeValue
application/json

PagedDTOCustomerRequestStatusDTO

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/request/1/status?start=6&limit=3",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/1/status?start=0&limit=3"
  },
  "values": [
    {
      "status": "Waiting for Customer",
      "statusDate": {
        "iso8601": "2015-10-08T14:05:00+0700",
        "jira": "2015-10-08T14:05:00.000+0700",
        "friendly": "Today 14:05 PM",
        "epochMillis": 1444287900000
      }
    },
    {
      "status": "Waiting for Support",
      "statusDate": {
        "iso8601": "2015-10-08T14:01:00+0700",
        "jira": "2015-10-08T14:01:00.000+0700",
        "friendly": "Today 14:01 PM",
        "epochMillis": 1444287660000
      }
    },
    {
      "status": "Waiting for Customer",
      "statusDate": {
        "iso8601": "2015-10-08T14:00:00+0700",
        "jira": "2015-10-08T14:00:00.000+0700",
        "friendly": "Today 14:00 PM",
        "epochMillis": 1444287600000
      }
    }
  ]
}

Get customer transitions

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

This method returns a list of transitions, the workflow processes that moves a customer request from one status to another, that the user can perform on a request. Use this method to provide a user with a list if the actions they can take on a customer request.

Permissions required: Permission to view the customer request.

App scope required: READ

OAuth scopes required: 
read:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

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

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/request/{issueIdOrKey}/transition' \
  --header 'Accept: application/json'

Responses

Returns the transitions available to the user on the customer request.

Content typeValue
application/json

PagedDTOCustomerTransitionDTO

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
{
  "_expands": [],
  "size": 2,
  "start": 2,
  "limit": 2,
  "isLastPage": false,
  "_links": {
    "base": "https://your-domain.atlassian.net/rest/servicedeskapi",
    "context": "context",
    "next": "https://your-domain.atlassian.net/rest/servicedeskapi/request/1/transition?start=4&limit=2",
    "prev": "https://your-domain.atlassian.net/rest/servicedeskapi/request/1/transition?start=0&limit=2"
  },
  "values": [
    {
      "id": "1",
      "name": "Close Request"
    },
    {
      "id": "2",
      "name": "Escalate Request"
    }
  ]
}

Perform customer transition

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

This method performs a customer transition for a given request and transition. An optional comment can be included to provide a reason for the transition.

Permissions required: The user must be able to view the request and have the Transition Issues permission. If a comment is passed the user must have the Add Comments permission.

App scope required: WRITE

OAuth scopes required: 
write:servicedesk-request

Request

Path parameters
issueIdOrKey Required

string

ID or key of the issue to transition

Body parameters
id

string

ID of the transition to be performed.

additionalComment

AdditionalCommentDTO

Comment explaining the reason for the transition.

Example

1
2
3
4
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/request/{issueIdOrKey}/transition' \
  --header 'Content-Type: application/json' \
  --data '"{\"id\":\"1\",\"additionalComment\":{\"body\":\"I have fixed the problem.\"}}"'

Responses

Returned if the request is transitioned.

Requesttype

Get all request types

Experimental

GET /rest/servicedeskapi/requesttype

This method returns all customer request types used in the Jira Service Desk instance, optionally filtered by a query string.

Use servicedeskapi/servicedesk/{serviceDeskId}/requesttype to find the customer request types supported by a specific service desk.

The returned list of customer request types can be filtered using the query parameter. The parameter is matched against the customer request types' name or description. For example, searching for "Install", "Inst", "Equi", or "Equipment" will match a customer request type with the name "Equipment Installation Request".

Permissions required: Any

App scope required: READ

Request

Query parameters
searchQuery

string

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
expand

Array<string>

Example

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

Responses

Returns the 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"
          }
        }
      }
    }
  ]
}

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

Experimental

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>

List of users, specified by user names, to add to or remove from a service desk. Either usernames or accountIds can be specified, but not both.
Note that usernames has been deprecated. See the migration guide 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. Only one of usernames or accountIds must be specified.

Unique items: true

Example

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

Responses

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

Remove customers

Experimental

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>

List of users, specified by user names, to add to or remove from a service desk. Either usernames or accountIds can be specified, but not both.
Note that usernames has been deprecated. See the migration guide 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. Only one of usernames or accountIds must be specified.

Unique items: true

Example

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

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

Experimental

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/wiki/plugins/servlet/remotepageview?pageId=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/wiki/plugins/servlet/remotepageview?pageId=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

Experimental

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 question mark 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.

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
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\",\"name\":\"Get IT Help\",\"description\":\"Get IT Help\",\"helpText\":\"Please tell us clearly the problem you have within 100 words.\"}"'

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

Experimental

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

Returns the keys of all properties for a request type.

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

Experimental

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

Returns the value of the property from a request type.

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

Experimental

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.

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

Experimental

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

Removes a property from a request type.

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