Customer
Info
Insight
Knowledgebase
Organization
Request
Requesttype
Servicedesk

Rate this page:

Organization

Get organizations

GET /rest/servicedeskapi/organization

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

OAuth scopes required: read:organization:jira-service-management
DEPRECATED OAuth scopes: manage:servicedesk-customer
Learn more about deprecated scopes

Request

Query parameters
start

integer

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

Format: int32
limit

integer

The maximum number of organizations to return per page. Default: 50. See the Pagination section for more details.

Format: int32
accountId

string

The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.

Example

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'

Responses

Returns paginated list of organizations.

Content typeValue
application/json

PagedDTOOrganizationDTO

Example response (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"
      }
    }
  ]
}

Create organization

POST /rest/servicedeskapi/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.

Connect app scope required: ADMIN

OAuth scopes required: read:organization:jira-service-management, write:organization:jira-service-management
DEPRECATED OAuth scopes: manage:servicedesk-customer
Learn more about deprecated scopes

Request

Body parameters
name Required

string

Name of the organization.

Example

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"
}'

Responses

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

Content typeValue
application/json

OrganizationDTO

Example response (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"
  }
}

Get organization

GET /rest/servicedeskapi/organization/{organizationId}

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

OAuth scopes required: read:organization:jira-service-management
DEPRECATED OAuth scopes: manage:servicedesk-customer
Learn more about deprecated scopes

Request

Path parameters
organizationId Required

integer

The ID of the organization.

Format: int32

Example

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'

Responses

Returns the requested organization.

Content typeValue
application/json

OrganizationDTO

Example response (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"
  }
}

Delete organization

DELETE /rest/servicedeskapi/organization/{organizationId}

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

OAuth scopes required: read:organization:jira-service-management, delete:organization:jira-service-management
DEPRECATED OAuth scopes: manage:servicedesk-customer
Learn more about deprecated scopes

Request

Path parameters
organizationId Required

integer

The ID of the organization.

Format: int32

Example

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

Responses

Returned if the organization was deleted.

Get properties keys

GET /rest/servicedeskapi/organization/{organizationId}/property

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.

OAuth scopes required: read:organization.property:jira-service-management
DEPRECATED OAuth scopes: manage:servicedesk-customer
Learn more about deprecated scopes

Request

Path parameters
organizationId Required

string

The ID of the organization from which keys will be returned.

Example

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'

Responses

Returned if the organization was found.

Content typeValue
application/json

PropertyKeys

Example response (application/json)

1
2
3
4
5
6
7
8
{
  "keys": [
    {
      "self": "/rest/servicedeskapi/organization/1/property/propertyKey",
      "key": "organization.attributes"
    }
  ]
}

Get property

GET /rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}

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.

OAuth scopes required: read:organization.property:jira-service-management
DEPRECATED OAuth scopes: manage:servicedesk-customer
Learn more about deprecated scopes

Request

Path parameters
organizationId Required

string

The ID of the organization from which the property will be returned.

propertyKey Required

string

The key of the property to return.

Example

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'

Responses

Returns the organization's property.

Content typeValue
application/json

EntityProperty

Example response (application/json)

1
2
3
4
5
6
7
{
  "key": "organization.attributes",
  "value": {
    "phone": "0800-1233456789",
    "mail": "charlie@example.com"
  }
}

Set property

PUT /rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}

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.

OAuth scopes required: read:organization.property:jira-service-management, write:organization.property:jira-service-management
DEPRECATED OAuth scopes: manage:servicedesk-customer
Learn more about deprecated scopes

Request

Path parameters
organizationId Required

string

The ID of the organization on which the property will be set.

propertyKey Required

string

The key of the organization's property. The maximum length of the key is 255 bytes.

Example

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'

Responses

Returned if the organization property was updated.

Content typeValue
application/json

anything

Delete property

DELETE /rest/servicedeskapi/organization/{organizationId}/property/{propertyKey}

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.

OAuth scopes required: read:organization.property:jira-service-management, delete:organization.property:jira-service-management
DEPRECATED OAuth scopes: manage:servicedesk-customer
Learn more about deprecated scopes

Request

Path parameters
organizationId Required

string

The ID of the organization from which the property will be removed.

propertyKey Required

string

The key of the property to remove.

Example

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

Responses

Returned if the organization property was removed.

Get users in organization

GET /rest/servicedeskapi/organization/{organizationId}/user

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

OAuth scopes required: read:organization.user:jira-service-management, read:user:jira
DEPRECATED OAuth scopes: manage:servicedesk-customer
Learn more about deprecated scopes

Request

Path parameters
organizationId Required

integer

The ID of the organization.

Format: int32
Query parameters
start

integer

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

Format: int32
limit

integer

The maximum number of users to return per page. Default: 50. See the Pagination section for more details.

Format: int32

Example

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'

Responses

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

Content typeValue
application/json

PagedDTOUserDTO

Example response (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"
      }
    }
  ]
}

Add users to organization

POST /rest/servicedeskapi/organization/{organizationId}/user

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

OAuth scopes required: read:organization.user:jira-service-management, write:organization.user:jira-service-management, read:user:jira
DEPRECATED OAuth scopes: manage:servicedesk-customer
Learn more about deprecated scopes

Request

Path parameters
organizationId Required

integer

The ID of the organization.

Format: int32
Body parameters
usernames

Array<string>

This property is no longer available and will be removed from the documentation soon. See the deprecation notice for details. Use accountIds instead.

accountIds

Array<string>

List of customers, specific by account IDs, to add to or remove from the organization.

Example

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": []
}'

Responses

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

Remove users from organization

DELETE /rest/servicedeskapi/organization/{organizationId}/user

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

OAuth scopes required: read:organization.user:jira-service-management, delete:organization.user:jira-service-management, read:user:jira
DEPRECATED OAuth scopes: manage:servicedesk-customer
Learn more about deprecated scopes

Request

Path parameters
organizationId Required

integer

The ID of the organization.

Format: int32
Body parameters
usernames

Array<string>

This property is no longer available and will be removed from the documentation soon. See the deprecation notice for details. Use accountIds instead.

accountIds

Array<string>

List of customers, specific by account IDs, to add to or remove from the organization.

Example

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": []
}'

Responses

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

Get organizations

GET /rest/servicedeskapi/servicedesk/{serviceDeskId}/organization

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

Permissions required: Service desk's agent.

Connect app scope required: READ

OAuth scopes required: read:servicedesk.organization:jira-service-management
DEPRECATED OAuth scopes: manage:servicedesk-customer
Learn more about deprecated scopes

Request

Path parameters
serviceDeskId Required

string

The ID of the service desk from which the organization list will be returned. This can alternatively be a project identifier.

Query parameters
start

integer

The starting index of the returned objects. Base index: 0. See the Pagination section for more details.

Format: int32
limit

integer

The maximum number of items to return per page. Default: 50. See the Pagination section for more details.

Format: int32
accountId

string

The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, 5b10ac8d82e05b22cc7d4ef5.

Example

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'

Responses

Returns the requested organizations list.

Content typeValue
application/json

PagedDTOOrganizationDTO

Example response (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"
      }
    }
  ]
}

Add organization

POST /rest/servicedeskapi/servicedesk/{serviceDeskId}/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.

Connect app scope required: WRITE

OAuth scopes required: read:servicedesk.organization:jira-service-management, write:servicedesk.organization:jira-service-management
DEPRECATED OAuth scopes: manage:servicedesk-customer
Learn more about deprecated scopes

Request

Path parameters
serviceDeskId Required

string

The ID of the service desk to which the organization will be added. This can alternatively be a project identifier.

Body parameters
organizationId Required

integer

List of organizations, specified by 'ID' field values, to add to or remove from the service desk.

Format: int32

Example

1
2
3
4
5
6
7
curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/organization' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "organizationId": 1
}'

Responses

Returned if the organization was added or the organization was already associated with the service desk.

Remove organization

DELETE /rest/servicedeskapi/servicedesk/{serviceDeskId}/organization

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.

Connect app scope required: DELETE

OAuth scopes required: read:servicedesk.organization:jira-service-management, delete:servicedesk.organization:jira-service-management
DEPRECATED OAuth scopes: manage:servicedesk-customer
Learn more about deprecated scopes

Request

Path parameters
serviceDeskId Required

string

The ID of the service desk from which the organization will be removed. This can alternatively be a project identifier.

Body parameters
organizationId Required

integer

List of organizations, specified by 'ID' field values, to add to or remove from the service desk.

Format: int32

Example

1
2
3
4
5
6
7
curl --request DELETE \
  --url 'https://your-domain.atlassian.net/rest/servicedeskapi/servicedesk/{serviceDeskId}/organization' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "organizationId": 1
}'

Responses

Returned if the organization was removed from the service desk or no such organization was associated with the service desk.

Rate this page: