• Organization
  • Customer
Cloud
Customer Service Management / / REST API

About

Postman Collection
OpenAPI

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

Authentication for REST API requests

If you are integrating directly with the Customer Service Management (CSM) REST APIs it is recommended to use 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 Basic authentication method.

Authentication for Atlassian Connect apps

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

Jira Cloud Platform REST APIs

Jira Customer Service Management is built upon the Jira platform, and Jira Service Management product. As such, in Jira Customer Service Management you have access to the Jira platform and Jira Service Management 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 Customer Service Management 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.

Resource summary

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

ResourceDescription
customerThis resource represents customers within your Jira instance. It allows for the retrieval and updating of detail fields for customers.
organizationThis resource enables you to group Jira Customer Service Management customers together. It allows for the retrieval and updating of detail fields for organizations.

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.

Status codes

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

URL structure

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

Version

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