{"openapi":"3.0.0","info":{"title":"JSM CS API","version":"1.0.0"},"servers":[{"url":"{host}/{basePath}","description":"Jira Service Management","variables":{"host":{"default":"https://api.atlassian.com","enum":["https://api.atlassian.com"]},"basePath":{"default":"jsm/csm/cloudid/{cloudId}","enum":["jsm/csm/cloudid/{cloudId}"]}}}],"tags":[{"name":"Organization","description":"Operations related to organizations."},{"name":"Customer","description":"Operations related to customers."}],"components":{"responses":{"Unauthenticated":{"description":"Returned if the user is not logged in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestError"}}}},"Forbidden":{"description":"Returned if the user does not have permission to complete this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestError"}}}},"NotFound":{"description":"Returned if the resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestError"}}}},"InternalError":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestError"}}}}},"schemas":{"OrganizationId":{"type":"string","description":"The unique identifier for organization.","example":"123"},"CustomerId":{"type":"string","description":"The unique identifier for the customer, in the form of an Atlassian Account Identifier (AAID).","example":"2a927c94-363f-4977-a0d6-9477d535f329"},"DetailFieldId":{"type":"string","description":"The unique identifier for the detail field.","example":"321"},"OrganizationName":{"type":"string","description":"The name of the organization.","example":"Atlassian"},"CustomerName":{"type":"string","description":"The name of the customer.","example":"John Doe"},"DetailFieldName":{"type":"string","description":"The name of the detail field.","example":"Region"},"Organization":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/OrganizationId"},"name":{"$ref":"#/components/schemas/OrganizationName"},"details":{"type":"array","items":{"$ref":"#/components/schemas/DetailField"}}},"required":["id","name"]},"Customer":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/CustomerId"},"name":{"$ref":"#/components/schemas/CustomerName"},"details":{"type":"array","items":{"$ref":"#/components/schemas/DetailField"}},"organizations":{"type":"array","items":{"$ref":"#/components/schemas/CustomerOrganization"}}},"required":["id","name"]},"CustomerOrganization":{"type":"object","description":"This represents the ID and name of the organizations which the individual are members of.","properties":{"id":{"$ref":"#/components/schemas/OrganizationId"},"name":{"$ref":"#/components/schemas/OrganizationName"}}},"DetailFieldDefinition":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/DetailFieldName"},"type":{"enum":["TEXT","EMAIL","URL","DATE","NUMBER","BOOLEAN","PHONE","SELECT","MULTISELECT"],"example":"SELECT"},"options":{"type":"array","description":"Field value options if they are allowed for this type. Only available for type SELECT & MULTISELECT. Each option cannot contain a comma and has a maximum length of 255.","items":{"type":"string","maxLength":255},"example":["AU","EU","US"]}},"required":["name","type"]},"DetailFieldContextConfiguration":{"type":"object","description":"Field configuration, i.e. position in the list of fields.","properties":{"position":{"type":"integer","description":"Field position in the list of all fields.","example":"1"}}},"DetailField":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/DetailFieldId"},"name":{"$ref":"#/components/schemas/DetailFieldName"},"type":{"$ref":"#/components/schemas/DetailFieldType"},"values":{"type":"array","description":"The value of the detail field, for the given entity. For example, if the field is a single-value field, then this array will contain a single value. If the field is a multi-value field, then this array will contain multiple values. Each value has a maximum length of 255.","items":{"type":"string","maxLength":255},"example":["EU"]},"configuration":{"$ref":"#/components/schemas/DetailFieldContextConfiguration"}}},"DetailFieldType":{"type":"object","description":"Field type.","properties":{"name":{"type":"string","description":"Field type name.","example":"SELECT"},"options":{"type":"array","description":"Field value options if they are allowed for this type. Only available for types SELECT & MULTISELECT. Each option cannot contain a comma and has a maximum length of 255.","items":{"type":"string","maxLength":255},"example":["AU","EU","US"]}}},"DetailFieldValue":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/DetailFieldId"},"name":{"$ref":"#/components/schemas/DetailFieldName"},"type":{"$ref":"#/components/schemas/DetailFieldType"},"values":{"type":"array","description":"The value of the detail field, for the given entity. For example, if the field is a single-value field, then this array will contain a single value. If the field is a multi-value field, then this array will contain multiple values. Each value has a maximum length of 255.","items":{"type":"string","maxLength":255},"example":["EU"]}}},"UpdateDetailFieldRequest":{"description":"The value(s) of the field to update.","type":"object","minProperties":1,"properties":{"values":{"type":"array","description":"The value of the detail field, for the given entity. For example, if the field is a single-value field, then this array will contain a single value. If the field is a multi-value field, then this array will contain multiple values. Each value has a maximum length of 255.","items":{"type":"string","maxLength":255},"example":["EU"]}}},"UpdateDetailFieldResponse":{"type":"object","description":"Returns the updated field value(s).","$ref":"#/components/schemas/DetailFieldValue"},"RestError":{"type":"object","properties":{"errorMessage":{"type":"string","description":"The error message.","example":"Organization 1 does not exist"},"errors":{"type":"array","description":"A list of error keys associated with the error.","items":{"type":"string"},"example":["jcs.barista.rest.not.found"]},"statusCode":{"type":"integer","description":"The http status returned with this error.","example":"404"}}}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"},"OAuth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://auth.atlassian.com/authorize","tokenUrl":"https://auth.atlassian.com/oauth/token","scopes":{"read:organization.detail:jira-service-management":"Allows the app to read organization details","write:organization.detail:jira-service-management":"Allows the app to create and update details on an organization","read:organization.detail-field:jira-service-management":"Allows the app to read organization detail fields","write:organization.detail-field:jira-service-management":"Allows the app to create and update detail fields on an organization","read:organization:jira-service-management":"Allows the app to read organization information","write:organization:jira-service-management":"Allows the app to create and update organization","read:customer.detail:jira-service-management":"Allows the app to read customer details","write:customer.detail:jira-service-management":"Allows the app to create and update details on a customer","read:customer.detail-field:jira-service-management":"Allows the app to read customer detail fields","write:customer.detail-field:jira-service-management":"Allows the app to create and update detail fields on a customer","read:customer:jira-service-management":"Allows the app to read customer information","write:customer:jira-service-management":"Allows the app to create and update customers"}}}}}},"paths":{"/api/v1/organization/{organizationId}":{"parameters":[{"name":"organizationId","description":"Unique identifier of organizations, must be positive integers only.","in":"path","required":true,"schema":{"$ref":"#/components/schemas/OrganizationId"}}],"get":{"summary":"Get an organization by id","operationId":"get-organization-by-id","security":[{"OAuth2":["read:organization:jira-service-management","read:organization.detail:jira-service-management"]}],"tags":["Organization"],"description":"Returns an organization, including its details.","responses":{"200":{"description":"Returns the requested organization along with its details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"5XX":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/organization/{organizationId}/details":{"parameters":[{"name":"organizationId","description":"Unique identifier of organizations, must be positive integers only.","in":"path","required":true,"schema":{"$ref":"#/components/schemas/OrganizationId"}}],"put":{"summary":"Update the value of a detail field for a given organization","operationId":"update-field-in-organizations","security":[{"OAuth2":["write:organization.detail-field:jira-service-management"]}],"tags":["Organization"],"description":"Updates and returns the new value(s) of the updated field, along with its general configuration (such as ID and Type).","parameters":[{"name":"fieldName","in":"query","description":"The name of the detail field to update the value of.","required":true,"schema":{"type":"string","example":"Region"}}],"requestBody":{"description":"The value(s) of the field to update.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDetailFieldRequest"}}}},"responses":{"200":{"description":"On success, returns the updated field value(s).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDetailFieldResponse"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"5XX":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/customer/{customerId}":{"parameters":[{"name":"customerId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/CustomerId"}}],"get":{"summary":"Get a customer by id","operationId":"get-customer-by-id","security":[{"OAuth2":["read:customer:jira-service-management","read:customer.detail:jira-service-management"]}],"tags":["Customer"],"description":"Returns a Customer, including their details.","responses":{"200":{"description":"Returns the requested individual.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"5XX":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/customer/{customerId}/details":{"parameters":[{"name":"customerId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/CustomerId"}}],"put":{"parameters":[{"name":"fieldName","in":"query","description":"The name of the detail field to update the value of.","required":true,"schema":{"type":"string","example":"Region"}}],"summary":"Update the value of a detail field for a given customer","operationId":"update-field-for-customer","security":[{"OAuth2":["write:customer.detail-field:jira-service-management"]}],"tags":["Customer"],"description":"Updates and returns the new value(s) of the updated field, along with its general configuration (such as ID and Type).","requestBody":{"description":"The value(s) of the field to update.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDetailFieldRequest"}}}},"responses":{"200":{"description":"On success, returns the updated field value(s).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDetailFieldResponse"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"5XX":{"$ref":"#/components/responses/InternalError"}}}}},"x-atlassian-narrative":{"documents":[{"title":"About","anchor":"about","body":"\nThis is the reference for the Jira Customer Service Management Cloud REST APIs. The REST APIs are for developers who\nwant to integrate Jira Customer Service Management with other applications or administrators that want to automate their\nworkflows and processes.\n"},{"title":"Authentication","anchor":"authentication","body":"\n### Authentication for REST API requests\n\nIf you are integrating directly with the Customer Service Management (CSM) REST APIs it is recommended to use\n[OAuth 2.0 authorization code grants (3LO)](https://developer.atlassian.com/cloud/jira/service-desk/oauth-2-authorization-code-grants-3lo-for-apps/) method.\n\nFor implementations with low security requirements, such as scripts and bots, it is also possible to use\n[Basic authentication](https://developer.atlassian.com/cloud/jira/service-desk/jira-rest-api-basic-authentication/) method.\n\n\n### Authentication for Atlassian Connect apps\nSupport for Atlassian Connect app to interact with the CSM APIs is currently unavailable.\n"},{"title":"Jira Cloud Platform REST APIs","anchor":"jira-cloud-platform","body":"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\nplatform and Jira Service Management REST APIs.\n\nIf you are writing an Atlassian Connect app, your app can request access to the Jira platform\nREST APIs by using the correct Jira platform Connect Scopes.\n\n* [Browse the Jira platform REST APIs](/cloud/jira/platform/rest/)\n* [Browse the Jira platform Connect Scopes](/cloud/jira/platform/scopes/)\n"},{"title":"Permissions and roles","anchor":"permissions","body":"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.\n\nFor detailed information on roles and permissions, see [Permissions overview](https://support.atlassian.com/jira-service-management-cloud/docs/overview-of-jira-cloud-permissions/)\nand [Setting up service desk users](https://support.atlassian.com/jira-service-management-cloud/docs/set-up-service-desk-users-to-work-on-requests/).\n\n**Permission types**\n\n- Global - These apply to applications as a whole, not individual projects.\n- Project - Organized into permission schemes, these apply to projects.\n- Issue - Organized into security schemes, these allow the visibility of individual issues to be adjusted.\n\n**Roles**\n\n- Jira System Administrator - can perform all Jira administration functions.\n- Jira Administrator - can perform most Jira administration functions.\n- Service desk Administrator (Project role - Administrator) - assigned to specific Service Desks and manages those service desk’s configurations.\n- Agent (Project role - service desk Team member) - assigned to specific Service Desks and manages and responds to Requests.\n- Customer - can submit and update their Requests, and may participate in Requests raised by other Customers.\n"},{"title":"Resource summary","anchor":"resource-summary","body":"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:\n<table>\n<thead>\n<tr>\n<th>Resource</th>\n<th>Description</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>customer</td>\n<td>This resource represents customers within your Jira instance. It allows for the retrieval and updating of detail fields for customers.</td>\n</tr>\n<tr>\n<td>organization</td>\n<td>This resource enables you to group Jira Customer Service Management customers together. It allows for the retrieval and updating of detail fields for organizations.</td>\n</tr>\n</tbody>\n</table>\n"},{"title":"Scopes","anchor":"scopes","body":"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.\n\nScopes are defined in the [Connect app descriptor](https://developer.atlassian.com/cloud/jira/service-desk/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.\n\n[//]: # (For the list of Jira Customer Service Management REST scopes, see [Scopes]&#40;https://developer.atlassian.com/cloud/jira/service-desk/scopes/&#41;.)\n"},{"title":"Status codes","anchor":"status","body":"- <span class=\"aui-lozenge aui-lozenge-success\">Status 200</span> Returned if the requested content (GET) is returned or content is updated (PUT).\n- <span class=\"aui-lozenge aui-lozenge-success\">Status 201</span> Returned if new records are created (PUT).\n- <span class=\"aui-lozenge aui-lozenge-error\">Status 400</span> Returned if the request was invalid.\n- <span class=\"aui-lozenge aui-lozenge-error\">Status 401</span> Returned if the user is not logged in. Resolve by logging the user in and reissuing the call.\n- <span class=\"aui-lozenge aui-lozenge-error\">Status 403</span> Returned if the user does not have the necessary permission to access the resource or run the method.\n- <span class=\"aui-lozenge aui-lozenge-error\">Status 404</span> Returned if the passed path parameters do not correspond to an object in the instance, for example, no Organization exists for a passed ID.\n"},{"title":"URL structure","anchor":"url-structure","body":"\nThe 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}`,\nwhere `{cloudId}` is the id of your cloud instance.\n\nFor example, to retrieve an organization with id 123 from an instance with cloudId `542c7f77-92c5-41bc-9527-652d767a4c36`, the URL would look like:\n`https://api.atlassian.com/jsm/csm/cloudid/542c7f77-92c5-41bc-9527-652d767a4c36/api/v1/organization/123`\n\nTo find your cloudId follow the instructions on [this](https://confluence.atlassian.com/jirakb/how-to-find-cloud-site-id-1272283178.html#:~:text=Solution,atlassian.net%2F_edge%2Ftenant_info) page\n"},{"title":"Version","anchor":"version","body":"\nThis documentation is for Version 1 of the Customer Service Management (CSM) REST API, which is the latest version.\n\n"}]}}