• Assets
  • Customer
  • Info
  • Knowledgebase
  • Organization
  • Request
  • Requesttype
  • Servicedesk
Cloud
Jira Service Management Cloud / Reference / REST API

Organization

Postman Collection
OpenAPI
GET

Get organizations

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:manage:servicedesk-customer
Granular:read:organization:jira-service-management

Request

Query parameters

start

integer

limit

integer

accountId

string

Responses

Returns paginated list of organizations.

application/json

PagedDTOOrganizationDTO
GET/rest/servicedeskapi/organization
1 2 3 4 curl --request GET \ --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 { "_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": [ { "id": "1", "name": "Charlie Cakes Franchises", "_links": { "self": "https://your-domain.atlassian.net/rest/servicedeskapi/organization/1" } } ] }
POST

Create organization

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredADMIN

ClassicRECOMMENDED:manage:servicedesk-customer
Granular:read:organization:jira-service-management, write:organization:jira-service-management

Request

Request bodyapplication/json

name

string

Required

Responses

Returns the created organization or the existing organization if name already exists.

application/json

OrganizationDTO
POST/rest/servicedeskapi/organization
1 2 3 4 5 6 7 8 curl --request POST \ --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "name": "Charlie Cakes Franchises" }'
201Response
1 2 3 4 5 6 7 { "id": "1", "name": "Charlie Cakes Franchises", "_links": { "self": "https://your-domain.atlassian.net/rest/servicedeskapi/organization/1" } }
GET

Get organization

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:manage:servicedesk-customer
Granular:read:organization:jira-service-management

Request

Path parameters

organizationId

integer

Required

Responses

Returns the requested organization.

application/json

OrganizationDTO
GET/rest/servicedeskapi/organization/{organizationId}
1 2 3 4 curl --request GET \ --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 { "id": "1", "name": "Charlie Cakes Franchises", "_links": { "self": "https://your-domain.atlassian.net/rest/servicedeskapi/organization/1" } }
DEL

Delete organization

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredDELETE

ClassicRECOMMENDED:manage:servicedesk-customer
Granular:read:organization:jira-service-management, delete:organization:jira-service-management

Request

Path parameters

organizationId

integer

Required

Responses

Returned if the organization was deleted.

DEL/rest/servicedeskapi/organization/{organizationId}
1 2 3 curl --request DELETE \ --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}' \ --header 'Authorization: Bearer <access_token>'
GET

Get properties keys

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect apps cannot access this REST resource.

ClassicRECOMMENDED:manage:servicedesk-customer
Granular:read:organization.property:jira-service-management

Request

Path parameters

organizationId

string

Required

Responses

Returned if the organization was found.

application/json

PropertyKeys

List of property keys.

GET/rest/servicedeskapi/organization/{organizationId}/property
1 2 3 4 curl --request GET \ --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}/property' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 8 { "entityPropertyKeyBeans": [ { "key": "organization.attributes", "self": "/rest/servicedeskapi/organization/1/property/propertyKey" } ] }
GET

Get property

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect apps cannot access this REST resource.

ClassicRECOMMENDED:manage:servicedesk-customer
Granular:read:organization.property:jira-service-management

Request

Path parameters

organizationId

string

Required
propertyKey

string

Required

Responses

Returns the organization's property.

application/json

EntityProperty

An entity property, for more information see Entity properties.

GET/rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}
1 2 3 4 curl --request GET \ --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 { "key": "organization.attributes", "value": { "mail": "charlie@example.com", "phone": "0800-1233456789" } }
PUT

Set property

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect apps cannot access this REST resource.

ClassicRECOMMENDED:manage:servicedesk-customer
Granular:read:organization.property:jira-service-management, write:organization.property:jira-service-management

Request

Path parameters

organizationId

string

Required
propertyKey

string

Required

Request bodyapplication/json

The value of the property. The value has to be a valid, non-empty JSON value. The maximum length of the property value is 32768 bytes.

any

Responses

Returned if the organization property was updated.

application/json

any

PUT/rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}
1 2 3 4 5 6 7 8 9 curl --request PUT \ --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "mail": "charlie@example.com", "phone": "0800-1233456789" }'
DEL

Delete property

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect apps cannot access this REST resource.

ClassicRECOMMENDED:manage:servicedesk-customer
Granular:read:organization.property:jira-service-management, delete:organization.property:jira-service-management

Request

Path parameters

organizationId

string

Required
propertyKey

string

Required

Responses

Returned if the organization property was removed.

DEL/rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}
1 2 3 curl --request DELETE \ --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}' \ --header 'Authorization: Bearer <access_token>'
GET

Get users in organization

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:manage:servicedesk-customer
Granular:read:organization.user:jira-service-management, read:user:jira

Request

Path parameters

organizationId

integer

Required

Query parameters

start

integer

limit

integer

Responses

Returns a paged list of users associated with the organization, ordered by their accountId.

application/json

PagedDTOUserDTO
GET/rest/servicedeskapi/organization/{organizationId}/user
1 2 3 4 curl --request GET \ --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}/user' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 { "_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" } } ] }
POST

Add users to organization

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredADMIN

ClassicRECOMMENDED:manage:servicedesk-customer
Granular:read:organization.user:jira-service-management, write:organization.user:jira-service-management, read:user:jira

Request

Path parameters

organizationId

integer

Required

Request bodyapplication/json

accountIds

array<string>

organizationId

integer

usernames

array<string>

Additional Properties

any

Responses

Returned if all the users were valid and added to the organization, no response payload is provided.

POST/rest/servicedeskapi/organization/{organizationId}/user
1 2 3 4 5 6 7 8 9 10 11 curl --request POST \ --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}/user' \ --header 'Authorization: Bearer <access_token>' \ --header 'Content-Type: application/json' \ --data '{ "accountIds": [ "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b", "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd" ], "usernames": [] }'
DEL

Remove users from organization

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.

Data Security Policy: Exempt from app access rules
Scopes

Connect app scope requiredDELETE

ClassicRECOMMENDED:manage:servicedesk-customer
Granular:read:organization.user:jira-service-management, delete:organization.user:jira-service-management, read:user:jira

Request

Path parameters

organizationId

integer

Required

Request bodyapplication/json

accountIds

array<string>

organizationId

integer

usernames

array<string>

Additional Properties

any

Responses

The request completed successfully. No additional content will be sent in the response.

DEL/rest/servicedeskapi/organization/{organizationId}/user
1 2 3 4 5 6 7 8 9 10 11 curl --request DELETE \ --url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}/user' \ --header 'Authorization: Bearer <access_token>' \ --header 'Content-Type: application/json' \ --data '{ "accountIds": [ "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3581db05e2a66fa80b", "qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd" ], "usernames": [] }'
GET

Get organizations

This method returns a list of all organizations associated with a service desk.

Permissions required: Service desk's agent.

Data Security Policy: Not exempt from app access rules
Scopes

Connect app scope requiredREAD

ClassicRECOMMENDED:manage:servicedesk-customer
Granular:read:servicedesk.organization:jira-service-management

Request

Path parameters

serviceDeskId

string

Required

Query parameters

start

integer

limit

integer

accountId

string

Responses

Returns the requested organizations list.

application/json

PagedDTOOrganizationDTO
GET/rest/servicedeskapi/servicedesk/{serviceDeskId}/organization
1 2 3 4 curl --request GET \ --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/organization' \ --header 'Authorization: Bearer <access_token>' \ --header 'Accept: application/json'
200Response
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 { "_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": [ { "id": "1", "name": "Charlie Cakes Franchises", "_links": { "self": "https://your-domain.atlassian.net/rest/servicedeskapi/organization/1" } }, { "id": "2", "name": "Atlas Coffee Co", "_links": { "self": "https://your-domain.atlassian.net/rest/servicedeskapi/organization/2" } }, { "id": "3", "name": "The Adjustment Bureau", "_links": { "self": "https://your-domain.atlassian.net/rest/servicedeskapi/organization/3" } } ] }
POST

Add organization

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.

Data Security Policy: Not exempt from app access rules
Scopes

Connect app scope requiredWRITE

ClassicRECOMMENDED: