{"openapi":"3.0.0","info":{"title":"JSM CS API","version":"1.0.0"},"tags":[{"name":"Organization","description":"This resource represents organizations, including their entitlements and organization detail fields."},{"name":"Customer","description":"This resource represents customers, including their entitlements and customer detail fields."},{"name":"Product","description":"This resource represents products."},{"name":"Entitlement","description":"This resource represents entitlements, including their details. Use this to manage entitlement details and detail fields."}],"components":{"responses":{"BadRequest":{"description":"Returned if the request is sent with malformed or invalid data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestError"}}}},"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"}}}},"PreconditionFailed":{"description":"Returned if the experimental opt-in header was not set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestError"}}}},"InternalError":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestError"}}}}},"schemas":{"Organization":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for organization.","example":"123"},"name":{"type":"string","description":"The name of the organization.","example":"Atlassian"},"details":{"type":"array","items":{"$ref":"#/components/schemas/DetailField"}}},"required":["id","name","details"]},"Customer":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the customer, in the form of an Atlassian Account Identifier (AAID).","example":"2a927c94-363f-4977-a0d6-9477d535f329"},"name":{"type":"string","description":"The name of the customer.","example":"John Doe"},"details":{"type":"array","items":{"$ref":"#/components/schemas/DetailField"}},"organizations":{"type":"array","items":{"$ref":"#/components/schemas/CustomerOrganization"}}},"required":["id","name","details"]},"Product":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for product.","example":"3858a61a-d337-42e6-993e-e13e1c366d4f"},"name":{"type":"string","maxLength":200,"description":"The name of the product.","example":"Acme Widget"}},"required":["id","name"]},"EntitledEntity":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the entitled entity","example":"123"},"type":{"type":"string","description":"The type of the entitled entity","enum":["CUSTOMER","ORGANIZATION"],"example":"CUSTOMER"}},"required":["id","type"]},"Entitlement":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for entitlement.","example":"3858a61a-d337-42e6-993e-e13e1c366d4f"},"product":{"$ref":"#/components/schemas/Product"},"entitledEntity":{"$ref":"#/components/schemas/EntitledEntity"},"details":{"type":"array","items":{"$ref":"#/components/schemas/DetailField"}}},"required":["id","product","entitledEntity","details"]},"PaginatedProducts":{"type":"object","properties":{"results":{"type":"array","description":"A list of products","items":{"$ref":"#/components/schemas/Product"}},"nextPageCursor":{"type":"string","description":"Cursor for getting the next page of items. Use this as the value for the `cursor` query parameter to get the next page of results."}},"required":["results","hasNextPage"]},"TaskProgress":{"type":"number","description":"The current progress of this task, expressed as a percentage between 0 and 100.","format":"float","example":80},"TaskElapsedSeconds":{"type":"integer","description":"This field represents the time elapsed in the run of this task. Always provided in seconds.","example":50},"TaskCreatedDateTime":{"type":"string","format":"date-time","description":"Time when this task was created in UTC.","example":"2022-12-31T23:59:59Z"},"TaskUpdateDateTime":{"type":"string","format":"date-time","description":"Time when this task was updated in UTC.","example":"2022-12-31T23:59:59Z"},"TaskResults":{"type":"object","description":"A generic JSON object providing run details for this task. This is not strongly typed and may changes depending on the task being run.","example":{"customerId":"customerId","detailsUpdate":["property2value1","property2value2"]}},"TaskStatus":{"type":"string","enum":["NOT_STARTED","IN_PROGRESS","SUCCEEDED","PARTIALLY_SUCCEEDED","FAILED"],"example":"IN_PROGRESS"},"Task":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for a task.","example":"3858a61a-d337-42e6-993e-e13e1c366d4f"},"name":{"type":"string","example":"BULK CUSTOMER IMPORT TASK"},"status":{"$ref":"#/components/schemas/TaskStatus"},"progress":{"$ref":"#/components/schemas/TaskProgress"},"elapsedSeconds":{"$ref":"#/components/schemas/TaskElapsedSeconds"},"results":{"$ref":"#/components/schemas/TaskResults"},"createdAt":{"$ref":"#/components/schemas/TaskCreatedDateTime"},"updatedAt":{"$ref":"#/components/schemas/TaskUpdateDateTime"}},"required":["id","name","progress","elapsedSeconds","createdAt","updatedAt"]},"CustomerOrganization":{"type":"object","description":"This represents the ID and name of the organizations which the individual are members of.","properties":{"id":{"type":"string","description":"The unique identifier for organization.","example":"123"},"name":{"type":"string","description":"The name of the organization.","example":"Atlassian"}}},"DetailFieldSavedValue":{"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"]},"BulkDetailFieldSavedValue":{"type":"array","description":"The value to set. If the field is a single-value field, then this array should contain only a single value. If the field is a multi-value field, then this array should contain all the values to set. To delete the value, the array should be empty or contain an empty string. Each value has a maximum length of 255.","items":{"type":"string","maxLength":255},"example":["EU"]},"DetailFieldOptions":{"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"]},"DetailFieldType":{"type":"object","description":"Field type.","properties":{"name":{"type":"string","enum":["TEXT","EMAIL","URL","DATE","NUMBER","BOOLEAN","PHONE","SELECT","MULTISELECT"],"example":"SELECT"},"options":{"$ref":"#/components/schemas/DetailFieldOptions"}},"required":["name"]},"DetailFieldValue":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the detail field.","example":"321"},"name":{"type":"string","description":"The name of the detail field. The name must be at least 2 and at most 255 characters and cannot include the special characters `? : ; . = “`.\n","example":"Region"},"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"]}}},"DetailFieldDefinition":{"type":"object","properties":{"name":{"type":"string","description":"The name of the detail field. The name must be at least 2 and at most 255 characters and cannot include the special characters `? : ; . = “`.\n","example":"Region"},"type":{"$ref":"#/components/schemas/DetailFieldType"}},"required":["name","type"]},"DetailFieldWithConfiguration":{"type":"object","properties":{"name":{"type":"string","description":"The name of the detail field. The name must be at least 2 and at most 255 characters and cannot include the special characters `? : ; . = “`.\n","example":"Region"},"type":{"$ref":"#/components/schemas/DetailFieldType"},"configuration":{"$ref":"#/components/schemas/DetailFieldContextConfiguration"}},"required":["name","type","configuration"]},"DetailFieldsWithConfiguration":{"type":"object","properties":{"results":{"type":"array","description":"A list of detail fields","items":{"$ref":"#/components/schemas/DetailFieldWithConfiguration"}}},"required":["results"]},"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":{"type":"string","description":"The unique identifier for the detail field.","example":"321"},"name":{"type":"string","description":"The name of the detail field. The name must be at least 2 and at most 255 characters and cannot include the special characters `? : ; . = “`.\n","example":"Region"},"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"}}},"CreateDetailFieldRequest":{"description":"The structure of the detail field to create","type":"object","properties":{"name":{"type":"string","description":"The name of the detail field. The name must be at least 2 and at most 255 characters and cannot include the special characters `? : ; . = “`. The name cannot be exactly the following reserved keywords (case ignored) - **Name**, **Key**, **Created**, **Updated**, **Label**.\n","example":"Region"},"type":{"$ref":"#/components/schemas/DetailFieldType"}},"required":["name","type"]},"CreateDetailFieldResponse":{"type":"object","description":"Returns the created detail field","$ref":"#/components/schemas/DetailFieldDefinition"},"EditDetailFieldRequest":{"type":"object","description":"The new name of the detail field and, for types SELECT & MULTISELECT only, the new detail field value options.","properties":{"name":{"type":"string","description":"The name of the detail field. The name must be at least 2 and at most 255 characters and cannot include the special characters `? : ; . = “`. The name cannot be exactly the following reserved keywords (case ignored) - **Name**, **Key**, **Created**, **Updated**, **Label**.\n","example":"Region"},"options":{"$ref":"#/components/schemas/DetailFieldOptions"}},"required":["name"]},"EditDetailFieldResponse":{"type":"object","description":"Returns the edited detail field.","$ref":"#/components/schemas/DetailFieldDefinition"},"UpdateDetailFieldRequest":{"type":"object","properties":{"values":{"type":"array","description":"The value to set. If the field is a single-value field, then this array should contain only a single value. If the field is a multi-value field, then this array should contain all the values to set. To delete the value, the array should be empty or contain an empty string.","items":{"type":"string","maxLength":255},"example":["EU"]}}},"UpdateDetailFieldResponse":{"type":"object","description":"Returns the updated field.","$ref":"#/components/schemas/DetailFieldValue"},"UpdateBulkDetailFieldRequest":{"type":"object","description":"The name and value of a single detail field to update in a bulk request. If the field is a single-value field, then the values 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.","minProperties":2,"properties":{"name":{"type":"string","description":"The name of the detail field. The name must be at least 2 and at most 255 characters and cannot include the special characters `? : ; . = “`. The name cannot be exactly the following reserved keywords (case ignored) - **Name**, **Key**, **Created**, **Updated**, **Label**.\n","example":"Region"},"values":{"$ref":"#/components/schemas/BulkDetailFieldSavedValue"}},"required":["name","values"]},"UpdateBulkDetailFieldsRequest":{"type":"array","description":"The list of details to update with their values for this bulk operation","items":{"$ref":"#/components/schemas/UpdateBulkDetailFieldRequest"}},"UpdateCustomerBulkDetailFieldRequest":{"type":"object","description":"Bulk update detail field values a customer","minProperties":2,"properties":{"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"},"details":{"$ref":"#/components/schemas/UpdateBulkDetailFieldsRequest"}},"required":["customerId","details"]},"UpdateEntitlementBulkDetailFieldRequest":{"type":"object","description":"Bulk update detail field values for an entitlement","minProperties":2,"properties":{"entitlementId":{"type":"string","description":"The unique identifier for entitlement, as a UUID.","example":"2a927c94-363f-4977-a0d6-9477d535f329"},"details":{"$ref":"#/components/schemas/UpdateBulkDetailFieldsRequest"}},"required":["entitlementId","details"]},"UpdateOrganizationBulkDetailFieldRequest":{"type":"object","description":"Bulk update detail field values for an organization","minProperties":2,"properties":{"organizationId":{"type":"string","description":"The unique identifier for organization.","example":"123"},"details":{"$ref":"#/components/schemas/UpdateBulkDetailFieldsRequest"}},"required":["organizationId","details"]},"UpdateCustomersBulkDetailFieldRequest":{"type":"object","description":"The request containing customers and their details to update. This request can contain multiple customers and each customer can contain multiple detail fields to update. This api currently only allows one element.","minProperties":1,"properties":{"customers":{"type":"array","items":{"$ref":"#/components/schemas/UpdateCustomerBulkDetailFieldRequest"}}},"required":["customers"]},"UpdateEntitlementsBulkDetailFieldRequest":{"type":"object","description":"The request containing entitlements and their details to update. This request can contain multiple entitlements and each entitlement can contain multiple detail fields to update. This api currently only allows one element.","minProperties":1,"properties":{"entitlements":{"type":"array","items":{"$ref":"#/components/schemas/UpdateEntitlementBulkDetailFieldRequest"}}},"required":["entitlements"]},"UpdateOrganizationsBulkDetailFieldRequest":{"type":"object","description":"The request containing organizations and their details to update. This request can contain multiple organizations and each organization can contain multiple detail fields to update. This api currently only allows one element.","minProperties":1,"properties":{"organizations":{"type":"array","items":{"$ref":"#/components/schemas/UpdateOrganizationBulkDetailFieldRequest"}}},"required":["organizations"]},"CreatedTaskResponse":{"type":"object","properties":{"taskId":{"type":"string","description":"The unique identifier for a task.","example":"123e4567-e89b-12d3-a456-426655440000"},"name":{"type":"string","example":"BULK CUSTOMER IMPORT TASK"},"statusUrl":{"type":"string","format":"uri","description":"The URL of the check status API which you can call to check the progress of this task.","example":"/api/v1/../task/{taskId}/status"}},"required":["taskId","name","statusUrl"]},"ProductRequest":{"type":"object","description":"The name of the product to create.","properties":{"name":{"type":"string","maxLength":200,"description":"The name of the product.","example":"Acme Widget"}},"required":["name"]},"EntitlementRequest":{"type":"object","description":"The product ID of the product associated with the new entitlement, in the form of a UUID.","properties":{"productId":{"type":"string","description":"The unique identifier for product.","example":"3858a61a-d337-42e6-993e-e13e1c366d4f"}},"required":["productId"]},"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":["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:jira-service-management":"Allows the app to read organization information","write:organization:jira-service-management":"Allows the app to create and update organizations","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","delete:organization.detail-field:jira-service-management":"Allows the app to delete detail fields on an organization","read:organization:entitlement:jira-service-management":"Allows the app to read organization entitlements","write:organization:entitlement:jira-service-management":"Allows the app to create organization entitlements","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","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","delete:customer.detail-field:jira-service-management":"Allows the app to delete detail fields on a customer","read:customer:entitlement:jira-service-management":"Allows the app to read customer entitlements","write:customer:entitlement:jira-service-management":"Allows the app to create customer entitlements","read:product:jira-service-management":"Allows the app to read product information","write:product:jira-service-management":"Allows the app to create and update product information","delete:product:jira-service-management":"Allows the app to delete product information","read:entitlement:jira-service-management":"Allows the app to read entitlement information","write:entitlement:jira-service-management":"Allows the app to create and update entitlements","delete:entitlement:jira-service-management":"Allows the app to delete entitlements","read:entitlement.detail:jira-service-management":"Allows the app to read entitlement details","write:entitlement.detail:jira-service-management":"Allows the app to create and update details on an entitlement","read:entitlement.detail-field:jira-service-management":"Allows the app to read entitlement detail fields","write:entitlement.detail-field:jira-service-management":"Allows the app to create and update detail fields on an entitlement","delete:entitlement.detail-field:jira-service-management":"Allows the app to delete entitlement detail fields","read:task:jira-service-management":"Allows the app to read task information"}}}}}},"paths":{"/api/v1/organization/details":{"get":{"summary":"Get organization detail fields","operationId":"get-all-organization-details","tags":["Organization"],"security":[{"OAuth2":["read:organization.detail-field:jira-service-management"]}],"description":"Returns all organization detail fields, including their configuration. You can use the [get organization](https://developer.atlassian.com/cloud/customer-service-management/rest/v1/api-group-organization/#api-api-v1-organization-organizationid-get) API to get details for a particular organization.

\n**Permissions required:** Administer Jira [global permission](https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/).\n","responses":{"200":{"description":"Returns a list of organization detail fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailFieldsWithConfiguration"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"summary":"Create organization detail field","operationId":"create-organization-detail","tags":["Organization"],"security":[{"OAuth2":["write:organization.detail-field:jira-service-management"]}],"description":"Creates an organization detail field. You can create up to 50 detail fields.

\n**Permissions required:** Administer Jira [global permission](https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDetailFieldRequest"}}}},"responses":{"200":{"description":"Returns the created detail field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDetailFieldResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/organization/details/{fieldName}":{"parameters":[{"name":"fieldName","in":"path","description":"The name of the detail field to edit.","required":true,"schema":{"type":"string","description":"The name of the detail field. The name must be at least 2 and at most 255 characters and cannot include the special characters `? : ; . = “`.\n","example":"Region"}}],"put":{"summary":"Edit organization detail field","operationId":"update-field-for-organizations","security":[{"OAuth2":["write:organization.detail-field:jira-service-management"]}],"tags":["Organization"],"description":"Renames an organization detail field and/or changes the available options for SELECT or MULTISELECT fields.

\n**Permissions required:** Administer Jira [global permission](https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditDetailFieldRequest"}}}},"responses":{"200":{"description":"Returns the edited organization detail field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditDetailFieldResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"summary":"Delete organization detail field","operationId":"delete-organization-detail","tags":["Organization"],"security":[{"OAuth2":["delete:organization.detail-field:jira-service-management"]}],"description":"Deletes an organization detail field and all values stored for it for all organizations. You cannot restore a detail field once it has been deleted.

\n**Permissions required:** Administer Jira [global permission](https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/).\n","responses":{"204":{"description":"Returns no response if the organization detail field is deleted."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/organization/{organizationId}":{"parameters":[{"name":"organizationId","description":"Unique identifier of organizations, must be positive integers only.","in":"path","required":true,"schema":{"type":"string","description":"The unique identifier for organization.","example":"123"}}],"get":{"summary":"Get organization","operationId":"get-organization","security":[{"OAuth2":["read:organization:jira-service-management","read:organization.detail:jira-service-management"]}],"tags":["Organization"],"description":"Returns an organization, including its details. You can get entitlements for an organization using the [get organization entitlements](https://developer.atlassian.com/cloud/customer-service-management/rest/v1/api-group-organization/#api-api-v1-organization-organizationid-entitlement-get) API.

\n**Permissions required:** Jira Service Management agent.\n","responses":{"200":{"description":"Returns the requested organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$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":{"type":"string","description":"The unique identifier for organization.","example":"123"}}],"put":{"summary":"Set organization detail","operationId":"update-field-value-for-organizations","security":[{"OAuth2":["write:organization.detail:jira-service-management"]}],"tags":["Organization"],"description":"**Permissions required:** Jira Service Management agent.\n","parameters":[{"name":"fieldName","in":"query","description":"The name of the organization detail field to set the value of.","required":true,"schema":{"type":"string","example":"Region"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDetailFieldRequest"}}}},"responses":{"200":{"description":"Returns the updated field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDetailFieldResponse"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/organization/{organizationId}/entitlement":{"parameters":[{"name":"organizationId","description":"Unique identifier of organizations, must be positive integers only.","in":"path","required":true,"schema":{"type":"string","description":"The unique identifier for organization.","example":"123"}}],"get":{"summary":"Get organization entitlements","operationId":"get-organization-entitlements","security":[{"OAuth2":["read:organization:entitlement:jira-service-management"]}],"tags":["Organization"],"description":"Returns a list of the organization's entitlements, along with their details.

\n**Permissions required:** Jira Service Management agent.\n","parameters":[{"name":"product","in":"query","description":"A product ID to optionally filter the entitlements to just entitlements of that product.","required":false,"schema":{"type":"string","description":"The unique identifier for product, as a UUID.","example":"3858a61a-d337-42e6-993e-e13e1c366d4f"}}],"responses":{"200":{"description":"Returns a list of entitlements.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Entitlement"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"summary":"Create organization entitlement","operationId":"create-organization-entitlement","security":[{"OAuth2":["write:organization:entitlement:jira-service-management"]}],"tags":["Organization"],"description":"**Permissions required:** Jira Service Management agent.\n","requestBody":{"description":"The ID of the associated product, as a UUID.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitlementRequest"}}}},"responses":{"200":{"description":"Returns the created entitlement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entitlement"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/customer/details":{"get":{"summary":"Get customer detail fields","operationId":"get-all-customer-details","tags":["Customer"],"security":[{"OAuth2":["read:customer.detail-field:jira-service-management"]}],"description":"Returns all customer detail fields, including their configuration. You can use the [get customer](https://developer.atlassian.com/cloud/customer-service-management/rest/v1/api-group-customer/#api-api-v1-customer-customerid-get) \nAPI to get details for a particular customer.

\n**Permissions required:** Administer Jira [global permission](https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/).\n","responses":{"200":{"description":"Returns list of detail fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailFieldsWithConfiguration"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"summary":"Create customer detail field","operationId":"create-customer-detail","tags":["Customer"],"security":[{"OAuth2":["write:customer.detail-field:jira-service-management"]}],"description":"Creates a customer detail field. You can create up to 50 detail fields.

\n**Permissions required:** Administer Jira [global permission](https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/).\n","requestBody":{"description":"The structure of the detail field to create.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDetailFieldRequest"}}}},"responses":{"200":{"description":"Returns the newly created detail field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDetailFieldResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/customer/details/{fieldName}":{"parameters":[{"name":"fieldName","in":"path","description":"The name of the detail field to edit.","required":true,"schema":{"type":"string","description":"The name of the detail field. The name must be at least 2 and at most 255 characters and cannot include the special characters `? : ; . = “`.\n","example":"Region"}}],"put":{"summary":"Edit customer detail field","operationId":"update-field-for-customers","security":[{"OAuth2":["write:customer.detail-field:jira-service-management"]}],"tags":["Customer"],"description":"Renames a customer detail field and/or changes the available options for SELECT or MULTISELECT fields.

\n**Permissions required:** Administer Jira [global permission](https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditDetailFieldRequest"}}}},"responses":{"200":{"description":"Returns the edited customer detail field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditDetailFieldResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"summary":"Delete customer detail field","operationId":"delete-customer-detail","tags":["Customer"],"security":[{"OAuth2":["delete:customer.detail-field:jira-service-management"]}],"description":"Deletes a customer detail field and all values stored for it for all customers. You cannot restore a detail field once it has been deleted.

\n**Permissions required:** Administer Jira [global permission](https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/).\n","responses":{"204":{"description":"Returns no response if the customer detail field is deleted."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/customer/{customerId}":{"parameters":[{"name":"customerId","in":"path","required":true,"schema":{"type":"string","description":"The unique identifier for the customer, in the form of an Atlassian Account Identifier (AAID).","example":"2a927c94-363f-4977-a0d6-9477d535f329"}}],"get":{"summary":"Get customer","operationId":"get-customer","security":[{"OAuth2":["read:customer:jira-service-management","read:customer.detail:jira-service-management"]}],"tags":["Customer"],"description":"Returns a customer, including their details. You can get entitlements for a customer using the [get customer entitlements](https://developer.atlassian.com/cloud/customer-service-management/rest/v1/api-group-customer/#api-api-v1-customer-customerid-entitlement-get) API.

\n**Permissions required:** Jira Service Management agent.\n","responses":{"200":{"description":"Returns the requested customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/customer/{customerId}/details":{"parameters":[{"name":"customerId","in":"path","required":true,"schema":{"type":"string","description":"The unique identifier for the customer, in the form of an Atlassian Account Identifier (AAID).","example":"2a927c94-363f-4977-a0d6-9477d535f329"}}],"put":{"parameters":[{"name":"fieldName","in":"query","description":"The name of the customer detail field to set the value of.","required":true,"schema":{"type":"string","example":"Region"}}],"summary":"Set customer detail","operationId":"update-field-value-for-customer","security":[{"OAuth2":["write:customer.detail:jira-service-management"]}],"tags":["Customer"],"description":"**Permissions required:** Jira Service Management agent.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDetailFieldRequest"}}}},"responses":{"200":{"description":"Returns the updated field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDetailFieldResponse"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/customer/{customerId}/entitlement":{"parameters":[{"name":"customerId","in":"path","required":true,"schema":{"type":"string","description":"The unique identifier for the customer, in the form of an Atlassian Account Identifier (AAID).","example":"2a927c94-363f-4977-a0d6-9477d535f329"}}],"get":{"summary":"Get customer entitlements","operationId":"get-customer-entitlements","security":[{"OAuth2":["read:customer:entitlement:jira-service-management"]}],"tags":["Customer"],"description":"Returns a list of the customer's entitlements, including entitlements inherited by any organizations the customer is in, along with their details.

\n**Permissions required:** Jira Service Management agent.\n","parameters":[{"name":"product","in":"query","description":"A product ID to optionally filter the entitlements to just entitlements of that product.","required":false,"schema":{"type":"string","description":"The unique identifier for product, as a UUID.","example":"3858a61a-d337-42e6-993e-e13e1c366d4f"}}],"responses":{"200":{"description":"Returns a list of entitlements.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Entitlement"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"summary":"Create customer entitlement","operationId":"create-customer-entitlement","security":[{"OAuth2":["write:customer:entitlement:jira-service-management"]}],"tags":["Customer"],"description":"**Permissions required:** Jira Service Management agent.\n","requestBody":{"description":"The ID of the associated product.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitlementRequest"}}}},"responses":{"200":{"description":"Returns the created entitlement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entitlement"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/product":{"get":{"summary":"Get products","operationId":"get-products","security":[{"OAuth2":["read:product:jira-service-management"]}],"description":"**Permissions required:** Jira Service Management agent.\n","tags":["Product"],"parameters":[{"name":"limit","in":"query","description":"The number of products to fetch. Defaults to 100 if not specified or value given is less than 1 or greater than 100.","required":false,"schema":{"type":"integer","default":100,"example":50}},{"name":"cursor","in":"query","description":"The starting point for the page of results to return. Use the value of `nextPageCursor` in one request to get the next page.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns paginated list of products.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedProducts"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"summary":"Create product","operationId":"create-product","security":[{"OAuth2":["write:product:jira-service-management"]}],"description":"**Permissions required:** Jira Service Management agent.\n","tags":["Product"],"requestBody":{"description":"The name of the product.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductRequest"}}}},"responses":{"200":{"description":"Returns the created product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/product/{productId}":{"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string","description":"The unique identifier for product, as a UUID.","example":"3858a61a-d337-42e6-993e-e13e1c366d4f"}}],"get":{"summary":"Get product","operationId":"get-product","security":[{"OAuth2":["read:product:jira-service-management"]}],"description":"**Permissions required:** Jira Service Management agent.\n","tags":["Product"],"responses":{"200":{"description":"Returns the requested product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}},"put":{"summary":"Rename product","operationId":"update-product","security":[{"OAuth2":["write:product:jira-service-management"]}],"description":"**Permissions required:** Jira Service Management agent.\n","tags":["Product"],"requestBody":{"description":"The new name of the product.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductRequest"}}}},"responses":{"200":{"description":"Returns the updated product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"summary":"Delete product","operationId":"delete-product","security":[{"OAuth2":["delete:product:jira-service-management"]}],"tags":["Product"],"description":"Deletes a product and all entitlements associated with it. You cannot restore a detail field once it has been deleted.

\n**Permissions required:** Administer Jira [global permission](https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/).\n","responses":{"204":{"description":"On success, returns no response."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/entitlement/details":{"get":{"summary":"Get entitlement detail fields","operationId":"get-all-entitlement-details","tags":["Entitlement"],"security":[{"OAuth2":["read:entitlement.detail-field:jira-service-management"]}],"description":"Returns all entitlement detail fields, including their configuration. You can use the [get entitlement](https://developer.atlassian.com/cloud/customer-service-management/rest/v1/api-group-entitlement/#api-api-v1-entitlement-entitlementid-get) \nAPI to get details for a particular entitlement.

\n**Permissions required:** Administer Jira [global permission](https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/).\n","responses":{"200":{"description":"Returns a list of detail fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailFieldsWithConfiguration"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}},"post":{"summary":"Create entitlement detail field","operationId":"create-entitlement-detail","tags":["Entitlement"],"security":[{"OAuth2":["write:entitlement.detail-field:jira-service-management"]}],"description":"Creates an entitlement detail field. You can create up to 50 detail fields.

\n**Permissions required:** Administer Jira [global permission](https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDetailFieldRequest"}}}},"responses":{"200":{"description":"Returns the created detail field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDetailFieldResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/entitlement/details/{fieldName}":{"parameters":[{"name":"fieldName","in":"path","description":"The name of the detail field.","required":true,"schema":{"type":"string","description":"The name of the detail field. The name must be at least 2 and at most 255 characters and cannot include the special characters `? : ; . = “`.\n","example":"Region"}}],"put":{"summary":"Edit entitlement detail field","operationId":"update-field-for-entitlements","security":[{"OAuth2":["write:entitlement.detail-field:jira-service-management"]}],"tags":["Entitlement"],"description":"Renames an entitlement detail field and/or changes the available options for SELECT or MULTISELECT fields.

\n**Permissions required:** Administer Jira [global permission](https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditDetailFieldRequest"}}}},"responses":{"200":{"description":"Returns the edited entitlement detail field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditDetailFieldResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"summary":"Delete entitlement detail field","operationId":"delete-entitlement-detail","tags":["Entitlement"],"security":[{"OAuth2":["delete:entitlement.detail-field:jira-service-management"]}],"description":"Deletes an entitlement detail field and all values stored for it for all entitlements. You cannot restore a detail field once it has been deleted.

\n**Permissions required:** Administer Jira [global permission](https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/).\n","responses":{"204":{"description":"Returns no response if the entitlement detail field is deleted."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/entitlement/{entitlementId}":{"parameters":[{"name":"entitlementId","in":"path","required":true,"schema":{"type":"string","description":"The unique identifier for entitlement, as a UUID.","example":"3858a61a-d337-42e6-993e-e13e1c366d4f"}}],"get":{"summary":"Get entitlement","operationId":"get-entitlement","security":[{"OAuth2":["read:entitlement:jira-service-management","read:entitlement.detail:jira-service-management"]}],"tags":["Entitlement"],"description":"Returns an entitlement, including its details. You can get entitlements for a customer using the [get customer entitlements](https://developer.atlassian.com/cloud/customer-service-management/rest/v1/api-group-customer/#api-api-v1-customer-customerid-get) API, \nand get entitlements for an organization using the [get organization entitlements](https://developer.stg.internal.atlassian.com/cloud/customer-service-management/rest/v1/api-group-organization/#api-api-v1-organization-organizationid-get) API.

\n**Permissions required:** Jira Service Management agent.\n","responses":{"200":{"description":"Returns the requested entitlement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entitlement"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}},"delete":{"summary":"Delete entitlement","operationId":"delete-entitlement","security":[{"OAuth2":["delete:entitlement:jira-service-management"]}],"tags":["Entitlement"],"description":"Deletes the specified entitlement along with its detail fields. You cannot restore an entitlement once it has been deleted.

\n**Permissions required:** Administer Jira [global permission](https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/).\n","responses":{"204":{"description":"Returns no response if the entitlement is deleted."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/v1/entitlement/{entitlementId}/details":{"parameters":[{"name":"entitlementId","in":"path","required":true,"schema":{"type":"string","description":"The unique identifier for entitlement, as a UUID.","example":"3858a61a-d337-42e6-993e-e13e1c366d4f"}}],"put":{"summary":"Set entitlement detail","operationId":"update-field-value-for-entitlement","security":[{"OAuth2":["write:entitlement.detail:jira-service-management"]}],"tags":["Entitlement"],"parameters":[{"name":"fieldName","in":"query","description":"The name of the entitlement detail field to set the value of.","required":true,"schema":{"type":"string","example":"Tier"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDetailFieldRequest"}}}},"description":"**Permissions required:** Jira Service Management agent.\n","responses":{"200":{"description":"Returns the updated field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDetailFieldResponse"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}}},"servers":[{"url":"https://api.atlassian.com/jsm/csm/cloudid/{cloudId}"}],"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 the\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 the\n[Basic authentication](https://developer.atlassian.com/cloud/jira/service-desk/jira-rest-api-basic-authentication/) method.\n\n### Authentication for Atlassian Forge Apps\nYou can access the API from a Forge app using product authentication. Use the `requestJira()` method of the [product fetch API](https://developer.atlassian.com/platform/forge/runtime-reference/product-fetch-api/#requestjira) to have authentication applied automatically. Forge apps must declare [OAuth 2.0](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/) scopes to be authorized to access. The scopes required for each operation are listed in the documentation.\n\nThe URIs for Forge app REST API calls have this structure: `/jsm/csm/api/v1/`\n\nFor example, to retrieve an organization with id `123`, the URI would look like: `/jsm/csm/api/v1/organization/123`\n\n### Authentication using OAuth 2.0\nOAuth 2.0 authorization code grants (3LO) for security (3LO scopes are shown as for operations OAuth scopes required). See [OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/) apps for details.\n\n### Authentication for Atlassian Connect apps\nSupport for Atlassian Connect apps to interact with the CSM APIs is currently unavailable.\n"},{"title":"Experimental methods","anchor":"experimental","body":"\nMethods marked as experimental may change without notice.\nTo use experimental methods, you must include the `X-ExperimentalApi: opt-in` header in your requests.\nUse of this header indicates that you are opting into the experimental preview.\nOnce a resource or method moves out of the experimental phase, then the header will no longer be required or checked.\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 also have access to both the Jira platform and Jira Service Management REST APIs.\n\n* [Browse the Jira platform REST APIs](/cloud/jira/platform/rest/)\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 the [Permissions overview](https://support.atlassian.com/jira-service-management-cloud/docs/overview-of-jira-cloud-permissions/)\nand [Setting up service project 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 project Administrator (Project role - Administrators) - assigned to specific service projects and manages those service project's configurations.\n- Agent (Project role - Service Desk Team) - assigned to specific service projects 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 enables you to work with a range of objects from Jira Customer Service Management. The main resources provided are:\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
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.
productThis resource allows you to represent digital entities (products) which Jira admins provide support for to customers. It allows for the retrieval and updating of products.
entitlementThis resource allows you to represent which products customers use, or are entitled to. It allows for the retrieval and updating of entitlements and their detail fields.
\n"},{"title":"Status codes","anchor":"status","body":"- Status 200 Returned if the requested content (GET) is returned or content is updated (PUT).\n- Status 201 Returned if new records are created (PUT).\n- Status 400 Returned if the request was invalid.\n- Status 401 Returned if the user is not logged in. Resolve by logging the user in and reissuing the call.\n- Status 403 Returned if the user does not have the necessary permission to access the resource or run the method.\n- 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.\n- Status 412 Returned if the API is experimental but the `X-ExperimentalApi: opt-in` header was not passed. For more details, see [Experimental methods](#experimental).\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"}]}}