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

Authentication for REST API requests

If you are integrating directly with the Customer Service Management (CSM) REST APIs it is recommended to use the OAuth 2.0 authorization code grants (3LO) method.

For implementations with low security requirements, such as scripts and bots, it is also possible to use the Basic authentication method.

Authentication for Atlassian Forge Apps

You can access the API from a Forge app using product authentication. Use the requestJira() method of the product fetch API to have authentication applied automatically. Forge apps must declare OAuth 2.0 scopes to be authorized to access. The scopes required for each operation are listed in the documentation.

The URIs for Forge app REST API calls have this structure: /jsm/csm/api/v1/<resource-name>

For example, to retrieve an organization with id 123, the URI would look like: /jsm/csm/api/v1/organization/123

Authentication using OAuth 2.0

OAuth 2.0 authorization code grants (3LO) for security (3LO scopes are shown as for operations OAuth scopes required). See OAuth 2.0 (3LO) apps for details.

Authentication for Atlassian Connect apps

Support for Atlassian Connect apps to interact with the CSM APIs is currently unavailable.

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.

Jira Customer Service Management is built upon the Jira platform and Jira Service Management product. As such, in Jira Customer Service Management you also have access to both the Jira platform and Jira Service Management REST APIs.

• Browse the Jira platform REST APIs

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

For detailed information on roles and permissions, see the Permissions overview and Setting up service project 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 project Administrator (Project role - Administrators) - assigned to specific service projects and manages those service project's configurations.
• Agent (Project role - Service Desk Team) - assigned to specific service projects and manages and responds to Requests.
• Customer - can submit and update their Requests, and may participate in Requests raised by other Customers.

The Jira Customer Service Management REST API enables you to work with a range of objects from Jira Customer Service Management. The main resources provided are:

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

The base URL is composed by a host and a base path followed by a specific endpoint path. The host is always https://api.atlassian.com while the base path is jsm/csm/cloudid/{cloudId}, where {cloudId} is the id of your cloud instance.

For example, to retrieve an organization with id 123 from an instance with cloudId 542c7f77-92c5-41bc-9527-652d767a4c36, the URL would look like: https://api.atlassian.com/jsm/csm/cloudid/542c7f77-92c5-41bc-9527-652d767a4c36/api/v1/organization/123

To find your cloudId follow the instructions on this page

This documentation is for Version 1 of the Customer Service Management (CSM) REST API, which is the latest version.