openapi: 3.2.0 info: description: Public REST API for Jira Service Management termsOfService: https://www.atlassian.com/legal/customer-agreement title: Service Management Public REST Organization API version: 1001.0.0-SNAPSHOT-82b018affa468e58f284fbe4df33536469d757df servers: - url: https://your-domain.atlassian.net tags: - name: Organization paths: /rest/servicedeskapi/organization: get: deprecated: false description: 'This method returns a list of organizations in the Jira Service Management instance. Use this method when you want to present a list of organizations or want to locate an organization by name. **Permissions required**: Any. However, to fetch organizations based on `accountId` the user must have a Service Desk agent license. **Response limitations**: If the user is a customer, only those organizations of which the customer is a member are listed.' operationId: getOrganizations parameters: - description: 'The starting index of the returned objects. Base index: 0. See the [Pagination](#pagination) section for more details.' in: query name: start schema: format: int32 type: integer - description: 'The maximum number of organizations to return per page. Default: 50. See the [Pagination](#pagination) section for more details.' in: query name: limit schema: format: int32 type: integer - description: The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*. in: query name: accountId schema: type: string responses: '200': content: application/json: example: '{"_expands":[],"size":1,"start":1,"limit":1,"isLastPage":false,"_links":{"base":"https://your-domain.atlassian.net/rest/servicedeskapi","context":"context","next":"https://your-domain.atlassian.net/rest/servicedeskapi/organization?start=2&limit=1","prev":"https://your-domain.atlassian.net/rest/servicedeskapi/organization?start=0&limit=1"},"values":[{"_links":{"self":"https://your-domain.atlassian.net/rest/servicedeskapi/organization/1"},"id":"1","name":"Charlie Cakes Franchises","scimManaged":false}]}' schema: $ref: '#/components/schemas/PagedDTOOrganizationDTO' description: Returns paginated list of organizations. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user is not logged in. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user does not have the necessary permission. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user is not found. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error. security: - OAuth2: - manage:servicedesk-customer summary: Get organizations tags: - Organization x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-oauth2-scopes: - scheme: OAuth2 scopes: - manage:servicedesk-customer state: Current - scheme: OAuth2 scopes: - read:organization:jira-service-management state: Beta x-atlassian-connect-scope: READ post: deprecated: false description: 'This method creates an organization by passing the name of the organization. **Permissions required**: Service desk administrator or agent. Note: Permission to create organizations can be switched to users with the Jira administrator permission, using the **Organization management** feature.' operationId: createOrganization requestBody: content: application/json: example: name: Charlie Cakes Franchises schema: $ref: '#/components/schemas/OrganizationCreateDTO' required: true responses: '201': content: application/json: example: '{"_links":{"self":"https://your-domain.atlassian.net/rest/servicedeskapi/organization/1"},"id":"1","name":"Charlie Cakes Franchises","scimManaged":false}' schema: $ref: '#/components/schemas/OrganizationDTO' description: Returns the created organization or the existing organization if name already exists. '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the HTTP request is invalid. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user is not logged in. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user does not have permission to complete this request. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error. security: - OAuth2: - manage:servicedesk-customer summary: Create organization tags: - Organization x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-oauth2-scopes: - scheme: OAuth2 scopes: - manage:servicedesk-customer state: Current - scheme: OAuth2 scopes: - read:organization:jira-service-management - write:organization:jira-service-management state: Beta x-atlassian-connect-scope: ADMIN /rest/servicedeskapi/organization/{organizationId}: delete: deprecated: false description: 'This method deletes an organization. Note that the organization is deleted regardless of other associations it may have. For example, associations with service desks. **Permissions required**: Jira administrator.' operationId: deleteOrganization parameters: - description: The ID of the organization. in: path name: organizationId required: true schema: format: int32 type: integer responses: '204': description: Returned if the organization was deleted. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user is not logged in. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user does not have permission to complete this request. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the organization does not exist. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error. security: - OAuth2: - manage:servicedesk-customer summary: Delete organization tags: - Organization x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-oauth2-scopes: - scheme: OAuth2 scopes: - manage:servicedesk-customer state: Current - scheme: OAuth2 scopes: - read:organization:jira-service-management - delete:organization:jira-service-management state: Beta x-atlassian-connect-scope: DELETE get: deprecated: false description: 'This method returns details of an organization. Use this method to get organization details whenever your application component is passed an organization ID but needs to display other organization details. To get organization detail field values which are visible in Jira Service Management, see the Customer Service Management REST API. **Permissions required**: Any **Response limitations**: Customers can only retrieve organization of which they are members.' operationId: getOrganization parameters: - description: The ID of the organization. in: path name: organizationId required: true schema: format: int32 type: integer responses: '200': content: application/json: example: '{"_links":{"self":"https://your-domain.atlassian.net/rest/servicedeskapi/organization/1"},"id":"1","name":"Charlie Cakes Franchises","scimManaged":false}' schema: $ref: '#/components/schemas/OrganizationDTO' description: Returns the requested organization. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user is not logged in. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user does not have permission to complete this request. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the organization does not exist. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error. security: - OAuth2: - manage:servicedesk-customer summary: Get organization tags: - Organization x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-oauth2-scopes: - scheme: OAuth2 scopes: - manage:servicedesk-customer state: Current - scheme: OAuth2 scopes: - read:organization:jira-service-management state: Beta x-atlassian-connect-scope: READ /rest/servicedeskapi/organization/{organizationId}/property: get: deprecated: false description: 'Returns the keys of all organization properties. Organization properties are a type of entity property which are available to the API only, and not shown in Jira Service Management. Learn more. To get organization detail field values which are visible in Jira Service Management, see the Customer Service Management REST API. **Permissions required**: Any **Response limitations**: Customers can only access properties of organizations of which they are members.' operationId: getPropertiesKeys parameters: - description: The ID of the organization from which keys will be returned. in: path name: organizationId required: true schema: type: string responses: '200': content: application/json: example: '{"entityPropertyKeyBeans":[{"key":"organization.attributes","self":"/rest/servicedeskapi/organization/1/property/propertyKey"}]}' schema: $ref: '#/components/schemas/PropertyKeys' description: Returned if the organization was found. '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the organization ID is invalid. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user is not logged in. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user does not have permission to complete this request. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the organization does not exist. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error. security: - OAuth2: - manage:servicedesk-customer summary: Get properties keys tags: - Organization x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-oauth2-scopes: - scheme: OAuth2 scopes: - manage:servicedesk-customer state: Current - scheme: OAuth2 scopes: - read:organization.property:jira-service-management state: Beta x-atlassian-connect-scope: INACCESSIBLE /rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}: delete: deprecated: false description: 'Removes an organization property. Organization properties are a type of entity property which are available to the API only, and not shown in Jira Service Management. Learn more. For operations relating to organization detail field values which are visible in Jira Service Management, see the Customer Service Management REST API. **Permissions required**: Service Desk Administrator or Agent. Note: Permission to manage organizations can be switched to users with the Jira administrator permission, using the **Organization management** feature.' operationId: deleteProperty parameters: - description: The ID of the organization from which the property will be removed. in: path name: organizationId required: true schema: type: string - description: The key of the property to remove. in: path name: propertyKey required: true schema: type: string responses: '204': description: Returned if the organization property was removed. '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the organization ID is invalid. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user is not logged in. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user does not have permission to complete this request. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the organization or property do not exist. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error. security: - OAuth2: - manage:servicedesk-customer summary: Delete property tags: - Organization x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-oauth2-scopes: - scheme: OAuth2 scopes: - manage:servicedesk-customer state: Current - scheme: OAuth2 scopes: - read:organization.property:jira-service-management - delete:organization.property:jira-service-management state: Beta x-atlassian-connect-scope: INACCESSIBLE get: deprecated: false description: 'Returns the value of an organization property. Use this method to obtain the JSON content for an organization''s property. Organization properties are a type of entity property which are available to the API only, and not shown in Jira Service Management. Learn more. To get organization detail field values which are visible in Jira Service Management, see the Customer Service Management REST API. **Permissions required**: Any **Response limitations**: Customers can only access properties of organizations of which they are members.' operationId: getProperty parameters: - description: The ID of the organization from which the property will be returned. in: path name: organizationId required: true schema: type: string - description: The key of the property to return. in: path name: propertyKey required: true schema: type: string responses: '200': content: application/json: example: '{"key":"organization.attributes","value":{"mail":"charlie@example.com","phone":"0800-1233456789"}}' schema: $ref: '#/components/schemas/EntityProperty' description: Returns the organization's property. '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the organization ID is invalid. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user is not logged in. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user does not have permission to complete this request. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the organization or property do not exist. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error. security: - OAuth2: - manage:servicedesk-customer summary: Get property tags: - Organization x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-oauth2-scopes: - scheme: OAuth2 scopes: - manage:servicedesk-customer state: Current - scheme: OAuth2 scopes: - read:organization.property:jira-service-management state: Beta x-atlassian-connect-scope: INACCESSIBLE put: deprecated: false description: 'Sets the value of an organization property. Use this resource to store custom data against an organization. Organization properties are a type of entity property which are available to the API only, and not shown in Jira Service Management. Learn more. To store organization detail field values which are visible in Jira Service Management, see the Customer Service Management REST API. **Permissions required**: Service Desk Administrator or Agent. Note: Permission to manage organizations can be switched to users with the Jira administrator permission, using the **Organization management** feature.' operationId: setProperty parameters: - description: The ID of the organization on which the property will be set. in: path name: organizationId required: true schema: type: string - description: The key of the organization's property. The maximum length of the key is 255 bytes. in: path name: propertyKey required: true schema: type: string requestBody: content: application/json: example: mail: charlie@example.com phone: 0800-1233456789 schema: {} description: The value of the property. The value has to be a valid, non-empty [JSON](https://tools.ietf.org/html/rfc4627) value. The maximum length of the property value is 32768 bytes. required: true responses: '200': content: application/json: schema: {} description: Returned if the organization property was updated. '201': content: application/json: schema: {} description: Returned if the organization property was created. '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the organization ID is invalid. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user is not logged in. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user does not have permission to complete this request. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the organization does not exist. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error. security: - OAuth2: - manage:servicedesk-customer summary: Set property tags: - Organization x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-oauth2-scopes: - scheme: OAuth2 scopes: - manage:servicedesk-customer state: Current - scheme: OAuth2 scopes: - read:organization.property:jira-service-management - write:organization.property:jira-service-management state: Beta x-atlassian-connect-scope: INACCESSIBLE /rest/servicedeskapi/organization/{organizationId}/user: delete: deprecated: false description: 'This method removes users from an organization. **Permissions required**: Service desk administrator or agent. Note: Permission to delete users from an organization can be switched to users with the Jira administrator permission, using the **Organization management** feature.' operationId: removeUsersFromOrganization parameters: - description: The ID of the organization. in: path name: organizationId required: true schema: format: int32 type: integer requestBody: content: application/json: example: accountIds: - qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b - qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd usernames: [] schema: $ref: '#/components/schemas/UsersOrganizationUpdateDTO' required: true responses: '204': description: The request completed successfully. No additional content will be sent in the response. '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if one or more user names are invalid. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user is not logged in. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user does not have permission to complete this request. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the organization does not exist. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error. security: - OAuth2: - manage:servicedesk-customer summary: Remove users from organization tags: - Organization x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-oauth2-scopes: - scheme: OAuth2 scopes: - manage:servicedesk-customer state: Current - scheme: OAuth2 scopes: - read:organization.user:jira-service-management - delete:organization.user:jira-service-management - read:user:jira state: Beta x-atlassian-connect-scope: DELETE get: deprecated: false description: 'This method returns all the users associated with an organization. Use this method where you want to provide a list of users for an organization or determine if a user is associated with an organization. **Permissions required**: Service desk administrator or agent.' operationId: getUsersInOrganization parameters: - description: The ID of the organization. in: path name: organizationId required: true schema: format: int32 type: integer - description: 'The starting index of the returned objects. Base index: 0. See the [Pagination](#pagination) section for more details.' in: query name: start schema: format: int32 type: integer - description: 'The maximum number of users to return per page. Default: 50. See the [Pagination](#pagination) section for more details.' in: query name: limit schema: format: int32 type: integer responses: '200': content: application/json: example: '{"_expands":[],"size":1,"start":1,"limit":1,"isLastPage":false,"_links":{"base":"https://your-domain.atlassian.net/rest/servicedeskapi","context":"context","next":"https://your-domain.atlassian.net/rest/servicedeskapi/organization/1/user?start=2&limit=1","prev":"https://your-domain.atlassian.net/rest/servicedeskapi/organization/1/user?start=0&limit=1"},"values":[{"accountId":"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b","name":"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b","key":"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b","emailAddress":"fred@example.com","displayName":"Fred F. User","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b","avatarUrls":{"16x16":"https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue","24x24":"https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue","32x32":"https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue","48x48":"https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue"},"self":"https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b"}},{"accountId":"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd","name":"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd","key":"qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd","emailAddress":"bob@example.com","displayName":"Bob D. Builder","active":true,"timeZone":"Australia/Sydney","_links":{"jiraRest":"https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd","avatarUrls":{"16x16":"https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%26noRedirect%3Dtrue","24x24":"https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=24&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D24%26noRedirect%3Dtrue","32x32":"https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=32&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D32%26noRedirect%3Dtrue","48x48":"https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%26noRedirect%3Dtrue"},"self":"https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd"}}]}' schema: $ref: '#/components/schemas/PagedDTOUserDTO' description: Returns a paged list of users associated with the organization, ordered by their accountId. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user is not logged in. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user does not have permission to complete this request. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the organization does not exist. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error. security: - OAuth2: - manage:servicedesk-customer summary: Get users in organization tags: - Organization x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-oauth2-scopes: - scheme: OAuth2 scopes: - manage:servicedesk-customer state: Current - scheme: OAuth2 scopes: - read:organization.user:jira-service-management - read:user:jira state: Beta x-atlassian-connect-scope: READ post: deprecated: false description: 'This method adds users to an organization. **Permissions required**: Service desk administrator or agent. Note: Permission to add users to an organization can be switched to users with the Jira administrator permission, using the **Organization management** feature.' operationId: addUsersToOrganization parameters: - description: The ID of the organization. in: path name: organizationId required: true schema: format: int32 type: integer requestBody: content: application/json: example: accountIds: - qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b - qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd usernames: [] schema: $ref: '#/components/schemas/UsersOrganizationUpdateDTO' required: true responses: '204': description: Returned if all the users were valid and added to the organization, no response payload is provided. '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if one or more usernames are unknown. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user is not logged in. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user does not have permission to complete this request. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the organization does not exist. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error. security: - OAuth2: - manage:servicedesk-customer summary: Add users to organization tags: - Organization x-atlassian-data-security-policy: - app-access-rule-exempt: true x-atlassian-oauth2-scopes: - scheme: OAuth2 scopes: - manage:servicedesk-customer state: Current - scheme: OAuth2 scopes: - read:organization.user:jira-service-management - write:organization.user:jira-service-management - read:user:jira state: Beta x-atlassian-connect-scope: ADMIN /rest/servicedeskapi/servicedesk/{serviceDeskId}/organization: delete: deprecated: false description: 'This method removes an organization from a service desk. If the organization ID does not match an organization associated with the service desk, no change is made and the resource returns a 204 success code. **Permissions required**: Service desk''s agent.' operationId: removeOrganization parameters: - description: The ID of the service desk from which the organization will be removed. This can alternatively be a [project identifier.](#project-identifiers) in: path name: serviceDeskId required: true schema: type: string requestBody: content: application/json: example: organizationId: 1 schema: $ref: '#/components/schemas/OrganizationServiceDeskUpdateDTO' required: true responses: '204': description: Returned if the organization was removed from the service desk or no such organization was associated with the service desk. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user is not logged in. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user does not have permission to complete this request. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the service desk or organization do not exist. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error. security: - OAuth2: - manage:servicedesk-customer summary: Remove organization tags: - Organization x-atlassian-data-security-policy: - app-access-rule-exempt: false x-atlassian-oauth2-scopes: - scheme: OAuth2 scopes: - manage:servicedesk-customer state: Current - scheme: OAuth2 scopes: - read:servicedesk.organization:jira-service-management - delete:servicedesk.organization:jira-service-management state: Beta x-atlassian-connect-scope: DELETE get: deprecated: false description: 'This method returns a list of all organizations associated with a service desk. **Permissions required**: Service desk''s agent.' operationId: getRestServicedeskapiServicedeskByServiceDeskIdOrganization parameters: - description: The ID of the service desk from which the organization list will be returned. This can alternatively be a [project identifier.](#project-identifiers) in: path name: serviceDeskId required: true schema: type: string - description: 'The starting index of the returned objects. Base index: 0. See the [Pagination](#pagination) section for more details.' in: query name: start schema: format: int32 type: integer - description: 'The maximum number of items to return per page. Default: 50. See the [Pagination](#pagination) section for more details.' in: query name: limit schema: format: int32 type: integer - description: The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*. in: query name: accountId schema: type: string responses: '200': content: application/json: example: '{"_expands":[],"size":3,"start":3,"limit":3,"isLastPage":false,"_links":{"base":"https://your-domain.atlassian.net/rest/servicedeskapi","context":"context","next":"https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/10001/organization?start=6&limit=3","prev":"https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/10001/organization?start=0&limit=3"},"values":[{"_links":{"self":"https://your-domain.atlassian.net/rest/servicedeskapi/organization/1"},"id":"1","name":"Charlie Cakes Franchises","scimManaged":false},{"_links":{"self":"https://your-domain.atlassian.net/rest/servicedeskapi/organization/2"},"id":"2","name":"Atlas Coffee Co","scimManaged":false},{"_links":{"self":"https://your-domain.atlassian.net/rest/servicedeskapi/organization/3"},"id":"3","name":"The Adjustment Bureau","scimManaged":false}]}' schema: $ref: '#/components/schemas/PagedDTOOrganizationDTO' description: Returns the requested organizations list. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user is not logged in. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if user does not have the necessary permission. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the service desk does not exist or the user is not found. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error. security: - OAuth2: - manage:servicedesk-customer summary: Get organizations tags: - Organization x-atlassian-data-security-policy: - app-access-rule-exempt: false x-atlassian-oauth2-scopes: - scheme: OAuth2 scopes: - manage:servicedesk-customer state: Current - scheme: OAuth2 scopes: - read:servicedesk.organization:jira-service-management state: Beta x-atlassian-connect-scope: READ x-operation-id-source: normalized x-operation-id-original: getOrganizations post: deprecated: false description: 'This method adds an organization to a service desk. If the organization ID is already associated with the service desk, no change is made and the resource returns a 204 success code. **Permissions required**: Service desk''s agent.' operationId: addOrganization parameters: - description: The ID of the service desk to which the organization will be added. This can alternatively be a [project identifier.](#project-identifiers) in: path name: serviceDeskId required: true schema: type: string requestBody: content: application/json: example: organizationId: 1 schema: $ref: '#/components/schemas/OrganizationServiceDeskUpdateDTO' required: true responses: '204': description: Returned if the organization was added or the organization was already associated with the service desk. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user is not logged in. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the user does not have permission to complete this request. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Returned if the service desk or organization do not exist. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error. security: - OAuth2: - manage:servicedesk-customer summary: Add organization tags: - Organization x-atlassian-data-security-policy: - app-access-rule-exempt: false x-atlassian-oauth2-scopes: - scheme: OAuth2 scopes: - manage:servicedesk-customer state: Current - scheme: OAuth2 scopes: - read:servicedesk.organization:jira-service-management - write:servicedesk.organization:jira-service-management state: Beta x-atlassian-connect-scope: WRITE components: schemas: EntityProperty: additionalProperties: false description: An entity property, for more information see [Entity properties](https://developer.atlassian.com/cloud/jira/platform/jira-entity-properties/). properties: key: description: The key of the property. Required on create and update. type: string value: description: The value of the property. Required on create and update. type: object OrganizationServiceDeskUpdateDTO: additionalProperties: true properties: organizationId: description: List of organizations, specified by 'ID' field values, to add to or remove from the service desk. format: int32 type: integer serviceDeskId: description: Service desk Id for which, organization needs to be updated type: string required: - organizationId type: object SelfLinkDTO: additionalProperties: false properties: self: format: uri type: string type: object OrganizationDTO: additionalProperties: false properties: _links: allOf: - $ref: '#/components/schemas/SelfLinkDTO' description: REST API URL to the organization. created: allOf: - $ref: '#/components/schemas/DateDTO' description: Date the organization was created. This field may not be present in some older organizations. id: description: A unique system generated ID for the organization. type: string name: description: Name of the organization. type: string scimManaged: description: Returns if an organization is managed by scim. This field may not be present in some older organizations type: boolean uuid: description: A unique system generated ID for the organization. This is identity from the group directory id type: string type: object OrganizationCreateDTO: additionalProperties: false properties: name: description: Name of the organization. Must contain 1-200 characters. type: string required: - name type: object UserLinkDTO: additionalProperties: false properties: avatarUrls: additionalProperties: type: string description: Links to the various sizes of the customer's avatar. Note that this property is deprecated, and will be removed in future versions. type: object jiraRest: description: REST API URL for the customer. format: uri type: string self: format: uri type: string type: object PropertyKey: additionalProperties: false description: Property key details. properties: key: description: The key of the property. readOnly: true type: string self: description: The URL of the property. readOnly: true type: string type: object UserDTO: additionalProperties: false properties: _links: allOf: - $ref: '#/components/schemas/UserLinkDTO' description: URLs for the customer record and related items. accountId: description: The accountId of the user, which uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*. type: string active: description: Indicates if the customer is active (true) or inactive (false) type: boolean displayName: description: Customer's name for display in a UI. Depending on the customer’s privacy settings, this may return an alternative value. type: string emailAddress: description: Customer's email address. Depending on the customer’s privacy settings, this may be returned as null. type: string key: description: This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. type: string name: description: This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. type: string timeZone: description: Customer time zone. Depending on the customer’s privacy settings, this may be returned as null. type: string type: object PagedDTOUserDTO: additionalProperties: false properties: _expands: items: type: string type: array _links: allOf: - $ref: '#/components/schemas/PagedLinkDTO' description: List of the links relating to the page. isLastPage: description: Indicates if this is the last page of records (true) or not (false). type: boolean limit: description: Number of items to be returned per page, up to the maximum set for these objects in the current implementation. format: int32 type: integer size: description: Number of items returned in the page. format: int32 type: integer start: description: Index of the first item returned in the page. format: int32 type: integer values: description: Details of the items included in the page. items: $ref: '#/components/schemas/UserDTO' type: array type: object PropertyKeys: additionalProperties: false description: List of property keys. properties: keys: description: Property key details. items: $ref: '#/components/schemas/PropertyKey' readOnly: true type: array type: object UsersOrganizationUpdateDTO: additionalProperties: true properties: accountIds: description: List of customers, specific by account IDs, to add to or remove from the organization. items: type: string type: array organizationId: description: The organizationId in which users need to be added format: int32 type: integer usernames: description: This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. Use `accountIds` instead. items: type: string type: array type: object ErrorResponse: additionalProperties: false properties: errorMessage: type: string i18nErrorMessage: $ref: '#/components/schemas/I18nErrorMessage' type: object I18nErrorMessage: additionalProperties: false properties: i18nKey: type: string parameters: items: type: string type: array type: object PagedLinkDTO: additionalProperties: false properties: base: description: Base URL for the REST API calls. format: uri type: string context: type: string next: description: REST API URL for the next page, if there is one. format: uri type: string prev: description: REST API URL for the previous page, if there is one. format: uri type: string self: description: REST API URL for the current page. format: uri type: string type: object DateDTO: additionalProperties: false properties: epochMillis: description: Date as the number of milliseconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), 1 January 1970. format: int64 type: integer friendly: description: Date in a user-friendly text format. type: string iso8601: description: Date in ISO8601 format. type: string jira: description: Date in the format used in the Jira REST APIs, which is ISO8601 format but extended with milliseconds. For example, 2016-09-28T23:08:32.097+1000. type: string type: object PagedDTOOrganizationDTO: additionalProperties: false properties: _expands: items: type: string type: array _links: allOf: - $ref: '#/components/schemas/PagedLinkDTO' description: List of the links relating to the page. isLastPage: description: Indicates if this is the last page of records (true) or not (false). type: boolean limit: description: Number of items to be returned per page, up to the maximum set for these objects in the current implementation. format: int32 type: integer size: description: Number of items returned in the page. format: int32 type: integer start: description: Index of the first item returned in the page. format: int32 type: integer values: description: Details of the items included in the page. items: $ref: '#/components/schemas/OrganizationDTO' type: array type: object securitySchemes: OAuth2: description: OAuth2 scopes for Jira flows: authorizationCode: authorizationUrl: https://auth.atlassian.com/authorize scopes: delete:organization.property:jira-service-management: Allows the app to delete organisation entity properties delete:organization.user:jira-service-management: Allows the app to remove members from organisations delete:organization:jira-service-management: Allows the app to delete organisations delete:request.feedback:jira-service-management: Allows the app to remove feedback data from requests delete:request.notification:jira-service-management: Allows the app to remove the subscription status of the user from requests delete:request.participant:jira-service-management: Allows the app to remove participants (user) data from requests delete:requesttype.property:jira-service-management: Allows the app to delete request type entity properties delete:servicedesk.customer:jira-service-management: Allows the app the delete customers from service desks delete:servicedesk.organization:jira-service-management: Allows the app the delete organisations from service desks delete:servicedesk.property:jira-service-management: Allows the app to delete service desk entity properties manage:jira-configuration: Configure Jira settings that require the Jira administrators permission, for example, create projects and custom fields, view workflows, manage issue link types. manage:jira-project: Create and edit project settings and create new project-level objects, for example, versions, components. manage:jira-webhook: Manage Jira webhooks. Enables an OAuth app to register and unregister dynamic webhooks in Jira. It also provides for fetching of registered webhooks. manage:servicedesk-customer: Manage Jira Service Management customers and organizations | Create, manage and delete customers and organizations.
Add and remove customers and organizations from service desks. read:customer:jira-service-management: Allows the app to read customer accounts information read:jira-user: View user information in Jira that you have access to, including usernames, email addresses, and avatars. read:jira-work: Read project and issue data. Search for issues and objects associated with issues (such as attachments and worklogs). read:knowledgebase:jira-service-management: Allows the app to search and list KB articles read:mail-logs.connectivity:jira-service-management: Allows the app to read email connectivity logs read:mail-logs.processing:jira-service-management: Allows the app to read incoming email processing logs read:organization.property:jira-service-management: Allows the app to read organisation entity properties read:organization.user:jira-service-management: Allows the app to read organisation membership information read:organization:jira-service-management: Allows the app to read organisation information read:queue:jira-service-management: Allows the app to list queues read:request.action:jira-service-management: Allows the app to read which actions can be performed on requests read:request.approval:jira-service-management: Allows the app to read approval data from requests read:request.attachment:jira-service-management: Allows the app to read attachment data from requests read:request.comment:jira-service-management: Allows the app to read comment data from requests read:request.feedback:jira-service-management: Allows the app to read feedback data from requests read:request.notification:jira-service-management: Allows the app to read the subscription status of the user for requests read:request.participant:jira-service-management: Allows the app to read participant (user) data from requests read:request.sla:jira-service-management: Allows the app to read SLA data from requests read:request.status:jira-service-management: Allows the app to read status/transition data from requests read:request:jira-service-management: Allows the app to list & search requests read:requesttype.property:jira-service-management: Allows the app to read request type desk entity properties read:requesttype:jira-service-management: Allows the app to list & search request types read:servicedesk-request: Read customer request data, including approvals, attachments, comments, request participants, and status/transitions.
Read service desk and request types, including searching for request types and reading request type fields, properties and groups. read:servicedesk.customer:jira-service-management: Allows the app the list customers of service desks read:servicedesk.organization:jira-service-management: Allows the app to list organisations to service desks read:servicedesk.property:jira-service-management: Allows the app to read service desk entity properties read:servicedesk:jira-service-management: Allows the app to list & search service desks write:customer:jira-service-management: Allows the app to create customer accounts (user) write:jira-work: Create and edit issues in Jira, post comments, create worklogs, and delete issues. write:organization.property:jira-service-management: Allows the app to write organisation entity properties write:organization.user:jira-service-management: Allows the app to add members to organisations write:organization:jira-service-management: Allows the app to create organisations write:request.approval:jira-service-management: Allows the app to act on approvals of requests (e.g approve, deny, …) write:request.attachment:jira-service-management: Allows the app to add attachments to requests write:request.comment:jira-service-management: Allows the app to add comments to requests write:request.feedback:jira-service-management: Allows the app to write feedback data on requests write:request.notification:jira-service-management: Allows the app to change the subscription status of the user for requests write:request.participant:jira-service-management: Allows the app to add participants (user) data from requests write:request.status:jira-service-management: Allows the app to execute transitions on requests write:request:jira-service-management: Allows the app to create requests write:requesttype.property:jira-service-management: Allows the app to write request type entity properties write:requesttype:jira-service-management: Allows the app to create or modify request types write:servicedesk-request: Create and manage Jira Service Management requests | Create and edit customer requests, including add comments and attachments, approve, share (add request participants), subscribe, and transition. write:servicedesk.customer:jira-service-management: Allows the app the add customers to service desks write:servicedesk.organization:jira-service-management: Allows the app the add organisations to service desks write:servicedesk.property:jira-service-management: Allows the app to write service desk entity properties write:servicedesk:jira-service-management: Allows the app the add organisations, customers and request types to service desks tokenUrl: https://auth.atlassian.com/oauth/token type: oauth2 basicAuth: description: You can access this resource via basic auth. scheme: basic type: http x-atlassian-narrative: documents: - anchor: about body: 'The REST APIs are for developers who want to integrate Jira Service Management with other applications or administrators who want to automate their workflows and processes. ' title: About - anchor: jira-cloud-platform-apis body: "Jira Service Management is built upon the Jira platform. As such, in Jira Service Management you have access to the Jira platform REST APIs.\n\n * [Browse the Jira platform REST APIs](/cloud/jira/platform/rest/)\n" title: Jira Cloud Platform APIs - anchor: permissions body: 'Permissions control the level of a user''s access to the Jira Service Management instance, while roles are how the permissions are assigned to individual users. For detailed information on roles and permissions, see [Permissions overview](https://support.atlassian.com/jira-service-management-cloud/docs/overview-of-jira-cloud-permissions/) and [Setting up service management users](https://support.atlassian.com/jira-service-management-cloud/docs/set-up-service-desk-users-to-work-on-requests/). ' title: Permissions and roles - anchor: authentication body: 'The Jira Service Management REST API uses the same authentication methods as Jira Cloud platform. ### Forge apps Forge apps use [REST API scopes](https://developer.atlassian.com/cloud/jira/service-desk/scopes-for-oauth-2-3LO-and-forge-apps/) when authenticating with Jira Service Management Cloud. For details see [Add scopes to call an Atlassian REST API](https://developer.atlassian.com/platform/forge/add-scopes-to-call-an-atlassian-rest-api/). The URIs for Forge app REST API calls have this structure: `https:///rest/servicedeskapi/` For example, `https:///rest/servicedeskapi/request/DEMO-1` ### Connect apps For Connect apps, authentication (JWT-based) is built into the Connect libraries. Authorization is implemented using either scopes (shown as App scope required for operations on this page) or user impersonation. For details, see [Security for Connect apps](https://developer.atlassian.com/cloud/jira/service-desk/security-for-connect-apps/). The URIs for Connect app REST API calls have this structure: `https:///rest/servicedeskapi/` For example, `https:///rest/servicedeskapi/request/DEMO-1` ### Other integrations For integrations that are not Forge or Connect apps, use OAuth 2.0 authorization code grants (3LO) for security (3LO scopes are shown as for operations OAuth scopes required). For details, see [OAuth 2.0 (3LO) apps](https://developer.atlassian.com/cloud/jira/service-desk/oauth-2-authorization-code-grants-3lo-for-apps/). The URIs for OAuth 2.0 (3LO) app REST API calls have this structure: `https://api.atlassian.com/ex/jira//rest/servicedeskapi/` For example, `https://api.atlassian.com/ex/jira/35273b54-3f06-40d2-880f-dd28cf8daafa/rest/servicedeskapi/request/DEMO-1` ### Ad-hoc API calls For personal scripts, bots, and ad-hoc execution of the REST APIs use basic authentication. For details, see [Basic auth for REST APIs](https://developer.atlassian.com/cloud/jira/service-desk/basic-auth-for-rest-apis/). The URIs for basic authentication REST API calls have this structure: `https:///rest/servicedeskapi/` For example, `https://your-domain.atlassian.net/rest/servicedeskapi/request/DEMO-1` ' title: Authentication and authorization - anchor: scopes body: 'Your app can request access to the Jira Service Management REST APIs by using the correct scopes. * [Scopes for Forge and 3LO apps](https://developer.atlassian.com/cloud/jira/service-desk/scopes-for-oauth-2-3LO-and-forge-apps/) * [Scopes for Connect apps](https://developer.atlassian.com/cloud/jira/service-desk/scopes-for-connect-apps/). ' title: Scopes - anchor: desks body: "It is also worth noting that the ability of Customers to raise Requests depends on the service desk type, which can be:\n\n - Public (sign up): Anyone who has the service desk URL can submit requests, and a user (customer) is created for them when a request is submitted.\n - Open: Any user in the system can submit requests, they don’t need to be associated with the service desk.\n - Closed: Only users associated with the service desk can submit requests.\n\nFor more details, see [How to manage access to your Jira Service Management Cloud](https://confluence.atlassian.com/jirakb/how-to-manage-access-to-your-jira-service-desk-cloud-967872675.html) in the Jira Service Management Cloud documentation.\n\n" title: Service desk types - anchor: status body: "\n - 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 204 Returned where the request may or may not have been actioned, but the outcome is as expected. For example, the request was to remove a customer from an organization, but the customer was not associated with the organization.\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\nResources will return a response body in addition to the error status codes. The returned entity for errors is as follows:\n\n```json\n{\n \"errorMessage\": \"Here is an error message\",\n \"i18nErrorMessage\": {\n \"i18nKey\": \"some.error.key\",\n \"parameters\": []\n }\n}\n```\n" title: Status codes and responses - anchor: experimental body: '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. Feedback on the experimental APIs is welcome and can be provided by submitting a feature request or suggestion through the [Atlassian Ecosystem Help Center](https://ecosystem.atlassian.net/servicedesk/customer/portals) or the [Jira Service Management Ecosystem](https://ecosystem.atlassian.net/browse/JSDECO). ' title: Experimental methods - anchor: expansion body: "The Jira Service Management REST API uses resource expansion, which means that some parts of a resource are not returned unless specified in the request. This simplifies responses and minimizes network traffic.\n\nUse the `expand` query parameter to specify the list of entities that you want to be expanded, identifying each of them by name. For example, appending `?expand=serviceDesk&expand=requestType` to a request’s URI results in the inclusion of the service desk and request type details in the response. The following URL would be used to get that information for the request with the ID JSD-1:\n```\nhttp://host:port/context/rest/servicedeskapi/request/JSD-1?expand=serviceDesk&expand=requestType\n```\n\nAlternatively, you can pass the list of entities you want to be expanded as a single comma-separated parameter, as in:\n\n```\nhttp://host:port/context/rest/servicedeskapi/request/JSD-1?expand=serviceDesk,requestType\n```\n\nTo discover the expansion identifiers for each entity, look at the `_expands` property in the parent object. In the JSON example below, the resource declares `participant`, `status`, `sla`, `requestType`, and `serviceDesk` as expandable.\n\n```json\n{\n \"_expands\": [\n \"participant\",\n \"status\",\n \"sla\",\n \"requestType\",\n \"serviceDesk\"\n ],\n \"issueId\": \"107001\",\n \"issueKey\": \"HELPDESK-1\",\n \"requestTypeId\": \"11001\",\n \"serviceDeskId\": \"10001\",\n ...\n```\n\n" title: Expansion - anchor: pagination body: "The Jira Service Management REST API uses pagination to improve performance. Pagination is enforced for operations that could return a large collection of items. When you make a request to a paginated resource, the response wraps the returned array of values in a JSON object with paging metadata as follows:\n**Request**\n\n```\nhttp://host:port/context/rest/api-name/resource-name?start=0&limit=10\n```\n\n**Response**\n\n```json\n{\n \"start\" : 0,\n \"limit\" : 10,\n \"size\" : 7,\n \"isLastPage\" : true,\n \"values\": [\n { /* result 0 */ },\n { /* result 1 */ },\n { /* result 2 */ }\n { /* result 3 */ }\n { /* result 4 */ }\n { /* result 5 */ }\n { /* result 6 */ }\n ]\n}\n```\n\nWhere:\n\n - `start` is the index of the first item returned in the page of results.\n - `limit` is the total number of items that could be returned per page, subject to the maximum server enforced limit for the resource’s method. If `limit` isn’t specified the default value of the resource is used.\n - `size` is the number of items returned on this page.\n - `isLastPage` indicates whether the page is the last page of results.\n\nClients can use the `start`, `limit`, and `size` parameters to retrieve the desired number of results. Each resource or method has a unique limit on the maximum number of items returned, which cannot be exceeded. If you request `size` which is larger than the limit, the number of items returned will be capped at the limit for that resource’s method. This behavior can be identified when the first page shows `size` is less than `limit` and `isLastPage` is `false`.\n\nThe limits set for each resource’s method is an implementation detail and may be changed.\n" title: Pagination - anchor: request-language body: "By default, responses are translated based on the requesting user's language preference, or the Jira site default \nlanguage if anonymous.\n\nUse the `requestLanguage` query parameter to have responses translated in a specific language, providing an \n[IETF BCP 47](https://tools.ietf.org/html/bcp47) language tag in the form `(language code)-(country code)` as the value. \nE.g. `?requestLanguage=en-US` for English (United States). Both static text (e.g. error messages) and dynamic \nuser-entered text (e.g. workflow status names) will be translated, if available.\n\nThe languages available are based on the installed languages in Jira. If the language tag specified does not match one \nof Jira's languages, then the query parameter will have no effect.\n\nDynamic user-entered translations can be edited in Jira administration for global objects (e.g. priority names) and \nin **Language support** under project administration for Service Desk projects (e.g. request type names)." title: Request language - anchor: special-headers body: "The following request and response headers define important metadata for the Jira Service Management REST API resources.\n\n - **X-Atlassian-Token** (request): Operations that accept multipart/form-data must include the `X-Atlassian-Token: no-check` header in requests.\nOtherwise the request will be blocked by XSRF protection.\n - **X-ExperimentalApi** (request): Experimental operations must include the `X-ExperimentalApi: opt-in` header in requests.\n Otherwise the request will not be processed. See [Experimental methods](#experimental) for more details.\n- **X-AACCOUNTID** (response): This response header contains the Atlassian account ID of the authenticated user.\n" title: Special headers - anchor: project-identifiers body: "For convenience, any of the resources that require a `{serviceDeskId}` path parameter also accept other identifiers.\n\nFor example, if a `ServiceDesk(id: 15)` corresponds to a `Project(id: 10012, key: ABC)`, then issuing a request to any of:\n\n /rest/servicedeskapi/servicedesk/ABC\n\n /rest/servicedeskapi/servicedesk/projectKey:ABC\n\n /rest/servicedeskapi/servicedesk/projectId:10012\n\n /rest/servicedeskapi/servicedesk/serviceDeskId:15\n\nis equivalent to issuing a request to:\n\n /rest/servicedeskapi/servicedesk/15\n" title: Using project identifiers - anchor: fieldformats body: '**Summary** - _A single line of text._ ```json "summary": "An explanation is one line of text." ``` **Description** - _Multiple lines of text._ ```json "description": "A description is multiples lines of text\n separated by\n line feeds.", ``` **Components** - _Multiple values addressed by ''name''._ ```json "components" : [ { "name": "Active Directory"} , { "name": "Network Switch" } ] ``` **Due date** - _A date in ''YYYY-MM-DD'' format._ ```json "duedate" : "2015-11-18" ``` **Labels** - _An array of string values._ ```json "labels" : ["examplelabelnumber1", "examplelabelnumber2"] ``` **Checkbox custom field** - _A custom UI field that enables multiple values to be selected from a defined list of values, with values addressed by ''value'' or `id`._ ```json "customfield_11440" : [{ "value" : "option1"}, {"value" : "option2"}] or "customfield_11440" : [{ "id" : 10112}, {"id" : 10115}] ``` **Date picker custom field** - _A custom UI field that enables a date in ''YYYY-MM-DD'' format to be picked._ ```json "customfield_11441" : "2015-11-18" ``` **Date time picker custom field** - _A custom UI field enables a datetime in ISO 8601 (''YYYY-MM-DDThh:mm:ss.sTZD'') format to be picked._ ```json "customfield_11442" : "2015-11-18T14:39:00.000+1100" ``` **Labels custom field** - _A custom UI field that is an array of strings._ ```json "customfield_11443" : [ "rest_label1", "rest_label2" ] ``` **Number custom field** - _A custom UI field that enables a number to be entered._ ```json "customfield_11444" : 666 ``` **Radio button custom field** - _A custom UI field that enables a single value to be selected from a defined list of values, with values addressed by `value` or `id`._ ```json "customfield_11445" : { "value": "option2" } or "customfield_11445" : { "id": 10112 } ``` **Cascading select custom field** - _A custom UI field that enables a single parent value and then a related child value to be selected, with values addressed by `value` or `id`._ ```json "customfield_11447" : { "value": "parent_option1", "child": { "value" : "p1_child1"} } or "customfield_11447" : { "id": 10112, "child": { "id" : 10115 } } ``` **Multi-select custom field** - _A custom UI field that enables multiple values to be selected from a defined list of values, with values addressed by `value` or `id`._ ```json "customfield_11448" : [ { "value": "option1" }, { "value": "option2" } ] or "customfield_11448" : [ { "id": 10112 }, { "id": 10115 } ] ``` **Single-select custom field** - _A custom UI field that enables a single value to be selected from a defined list of values, with values address by `value` or `id`._ ```json "customfield_11449" : { "value": "option3" } or "customfield_11449" : { "id": 10112 } ``` **Multi-line text custom field** - _A custom UI field that enables multiple lines of text to be entered._ ```json "customfield_11450": "Multiples lines of text\n separated by\n line feeds" ``` **Text custom field** - _A custom UI field that enables a single line of text to be entered._ ```json "customfield_11450": "A single line of text." ``` **URL custom field** - _A custom UI field that enables a URL to be entered._ ```json "customfield_11452" : "http://www.atlassian.com", ``` **Single-user picker custom field** - _A custom UI field that enables a single user to be selected._ ```json "customfield_11453" : { "name":"tommytomtomahawk" }, ``` **Multi-user picker custom field** - _A custom UI field that enables multiple users to be selected._ ```json "customfield_11458" : [ { "name":"inigomontoya" }, { "name":"tommytomtomahawk" }] ``` **Attachment** - _Attachments, using IDs of temporary attachments as provided by the /attachTemporaryFile API._ ````json "attachment" : ["4786e3a5-52be-4d5b-bf3d-5f53e54f4559", "1187b2b7-8a75-4eac-88b2-b6e43129ef5c"] ````' title: Field input formats - anchor: overshort body: 'The Jira Service Management REST API enable you to work with a range of objects from Jira Service Management. The main resources provided are: | Resource | Description | |---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | customer | This resource represents customers within your Jira instance. Use it to create new customers. | | info | This resource provides details of the Jira Service Management software version, builds, and related links. | | organization | This resource enables you to group Jira Service Management customers together. Use it to create and delete organizations, and add and remove customers from them. | | request | This resource represents the customer requests in your service desks. Use it to create new requests and update request details, such as attachments and comments as well as take actions to update request status or review SLA performance. | | requesttype | This resource enables a list of customer request types, a way to categorize requests in a service desk, to be obtained. | | servicedesk | This resource represents a service desk. Use it to retrieve the service desks in your Jira instance, managed the requests service desks can handle, manage the associated customers and organizations, and retrieve details of request queues. | ' title: Resource summary