This is the reference for the Customer Service Management Cloud REST APIs. The REST APIs are for developers who want to integrate 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 profile with id 123, the URI would look like: /jsm/csm/api/v1/organization/profile/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.

APIs supporting bulk operations may trigger long-running or computationally expensive tasks. In these cases, calling the API will schedule an asynchronous task and return a response containing the task ID to be used to retrieve the status of the task.

The get task API (GET /api/v1/tasks/{taskId}) response will contain the status field as well as the failures field, if any operations failed. Results are stored for up to 3 days.

Note that asynchronous tasks are not guaranteed to be run in order. In other words, if you need your tasks to execute in a certain order, you should start a task only after the prerequisite task(s) have finished.

Idempotency key

This header allows for bulk operations to be safely retried without accidentally performing the same operation. Subsequent requests with the same key and request body will return the same task id, or validation errors. Reusing the idempotency key with a different request will result in an error.

When calling bulk operation APIs, you must include the idempotency-key header in your requests. The value of this header should be unique for each request and is provided by the client. We suggest using UUIDs as the value.

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.

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

• Browse the Jira platform REST APIs
• Browse the Jira Service Management 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, Project role - Customer Service 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 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, or when calling a bulk API without the Idempotency-key header. For more details, see Experimental methods and Bulk operations.

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.