Rate this page:
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.
Connect app scope required: READ
manage:servicedesk-customerread:organization:jira-service-managementinteger
integer
string
Returns paginated list of organizations.
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'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"
}
}
]
}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.
Connect app scope required: ADMIN
manage:servicedesk-customerread:organization:jira-service-management, write:organization:jira-service-managementstring
RequiredReturns the created organization or the existing organization if name already exists.
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"
}'1
2
3
4
5
6
7
{
"id": "1",
"name": "Charlie Cakes Franchises",
"_links": {
"self": "https://your-domain.atlassian.net/rest/servicedeskapi/organization/1"
}
}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.
Permissions required: Any
Response limitations: Customers can only retrieve organization of which they are members.
Connect app scope required: READ
manage:servicedesk-customerread:organization:jira-service-managementinteger
RequiredReturns the requested organization.
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'1
2
3
4
5
6
7
{
"id": "1",
"name": "Charlie Cakes Franchises",
"_links": {
"self": "https://your-domain.atlassian.net/rest/servicedeskapi/organization/1"
}
}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.
Connect app scope required: DELETE
manage:servicedesk-customerread:organization:jira-service-management, delete:organization:jira-service-managementinteger
RequiredReturned if the organization was deleted.
1
2
3
curl --request DELETE \
--url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}' \
--header 'Authorization: Bearer <access_token>'Returns the keys of all properties for an organization. Use this resource when you need to find out what additional properties items have been added to an organization.
Permissions required: Any
Response limitations: Customers can only access properties of organizations of which they are members.
Connect apps cannot access this REST resource.
manage:servicedesk-customerread:organization.property:jira-service-managementstring
RequiredReturned if the organization was found.
List of property keys.
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'1
2
3
4
5
6
7
8
{
"keys": [
{
"self": "/rest/servicedeskapi/organization/1/property/propertyKey",
"key": "organization.attributes"
}
]
}Returns the value of a property from an organization. Use this method to obtain the JSON content for an organization's property.
Permissions required: Any
Response limitations: Customers can only access properties of organizations of which they are members.
Connect apps cannot access this REST resource.
manage:servicedesk-customerread:organization.property:jira-service-managementstring
Requiredstring
RequiredReturns the organization's property.
An entity property, for more information see Entity properties.
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'1
2
3
4
5
6
7
{
"key": "organization.attributes",
"value": {
"phone": "0800-1233456789",
"mail": "charlie@example.com"
}
}Sets the value of a property for an organization. Use this resource to store custom data against an organization.
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.
Connect apps cannot access this REST resource.
manage:servicedesk-customerread:organization.property:jira-service-management, write:organization.property:jira-service-managementstring
Requiredstring
RequiredReturned if the organization property was updated.
any
1
2
3
4
curl --request PUT \
--url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'Removes a property from an organization.
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.
Connect apps cannot access this REST resource.
manage:servicedesk-customerread:organization.property:jira-service-management, delete:organization.property:jira-service-managementstring
Requiredstring
RequiredReturned if the organization property was removed.
1
2
3
curl --request DELETE \
--url 'https://your-domain.atlassian.net/rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}' \
--header 'Authorization: Bearer <access_token>'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.
Connect app scope required: READ
manage:servicedesk-customerread:organization.user:jira-service-management, read:user:jirainteger
Requiredinteger
integer
Returns a paged list of users associated with the organization, ordered by their accountId.
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'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": {
"48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%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",
"16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%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"
},
"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": {
"48x48": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=48&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D48%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",
"16x16": "https://avatar-cdn.atlassian.com/9bc3b5bcb0db050c6d7660b28a5b86c9?s=16&d=https%3A%2F%2Fsecure.gravatar.com%2Favatar%2F9bc3b5bcb0db050c6d7660b28a5b86c9%3Fd%3Dmm%26s%3D16%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"
},
"self": "https://your-domain.atlassian.net/rest/api/2/user?username=qm:a713c8ea-1075-4e30-9d96-891a7d181739:5ad6d3a01db05e2a66fa80bd"
}
}
]
}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.
Connect app scope required: ADMIN
manage:servicedesk-customerread:organization.user:jira-service-management, write:organization.user:jira-service-management, read:user:jirainteger
Requiredarray<string>
array<string>
Returned if all the users were valid and added to the organization, no response payload is provided.
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": []
}'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.
Connect app scope required: DELETE
manage:servicedesk-customerread:organization.user:jira-service-management, delete:organization.user:jira-service-management, read:user:jirainteger
Requiredarray<string>
array<string>
The request completed successfully. No additional content will be sent in the response.
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": []
}'This method returns a list of all organizations associated with a service desk.
Permissions required: Service desk's agent.
Connect app scope required: READ
manage:servicedesk-customerread:servicedesk.organization:jira-service-managementstring
Requiredinteger
integer
string
Returns the requested organizations list.
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'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"
}
}
]
}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.
Connect app scope required: WRITE
manage:servicedesk-customerread:servicedesk.organization:jira-service-management, write:servicedesk.organization:jira-service-managementstring
Requiredinteger
RequiredReturned if the organization was added or the organization was already associated with the service desk.