Managing Existing Departments and User Assignments via API

This article explains how to retrieve and update existing departments, review user-department relationships and appoint department managers through the AMS public API.

For instructions on initially creating departments and assigning users, see Creating and Managing AMS via API.

Before you start

Required API permissions

• read_departments - read department information.

• write_departments - update departments.

• read_user_department - retrieve user-department relationships.

• write_user_department - assign departments to users.

• appoint_as_manager - appoint or remove department managers.

• delete_departments - delete departments.

If you receive a 403 Forbidden response, check that the API account has the permission required for the operation.

Setup order

1. Step 1 - Retrieve the department structure

2. Step 2 - Review users in departments

3. Step 3 - Update an existing department

4. Step 4 - Update a user's departmental assignments

5. Step 5 - Appoint or remove department managers

Step 1 - Retrieve the department structure

Endpoint: GET /v2/admin/departments

Permission required: read_departments

This returns the department hierarchy.

• Departments with no parent are top-level departments.

• Child departments are linked through their parent.

• Multiple levels of departmental hierarchy are supported.

• The response includes a users_count value representing the number of non-deleted users.

To retrieve an individual department:

Endpoint: GET /v2/admin/departments/{departmentId}

The response includes the relevant hierarchy and directly associated department managers.

Step 2 - Review users in departments

To retrieve all departments with their linked users:

Endpoint: GET /v2/admin/departments/users

Permission required: read_user_department

• Users associated with several departments can appear under each department.

• Users without a department association are not included.

To retrieve users from a specific department:

Endpoint: GET /v2/admin/departments/{departmentId}/users

By default, the response includes users associated with the specified department and its child departments.

To return only users directly linked to the specified department, use:

GET /v2/admin/departments/{departmentId}/users?direct_only=true

Step 3 - Update an existing department

Endpoint: PATCH /v2/admin/departments/{departmentId}

Permission required: write_departments

Example request body

{
  "name": "Control Room",
  "parent_id": 42
}

• The parent_id must reference an existing department.

• A department cannot be its own parent or the child of one of its descendants.

• To retrieve the department after updating it, use the GET endpoint.

Department deletion

Endpoint: DELETE /v2/admin/departments/{departmentId}

Permission required: delete_departments

Deletion may be prevented if the department still has child departments or is referenced by tasks or themes.

Common errors

• department.002 - department not found.

• department.003 - department has children.

• department.004 - department is referenced by tasks.

• department.005 - department is referenced by themes.

• department.006 - invalid circular hierarchy.

Important: Changing or deleting a department can affect its relationship with existing AMS information. Review the implications before making structural changes.

Step 4 - Update a user's departmental assignments

Endpoint: GET /v2/admin/users/{userId}/department

This returns the departments currently linked to a user.

To submit departmental assignments:

Endpoint: POST /v2/admin/users/{userId}/department

Permission required: write_user_department

Example request body

{
  "departments": [1, 2, 3]
}

• The user must already exist.

• All referenced departments must already exist.

• A user may be associated with multiple departments.

Step 5 - Appoint or remove department managers

Appoint a manager

Endpoint: POST /v2/admin/departments/{departmentId}/users/{userId}/set

Permission required: appoint_as_manager

This appoints a user as a manager of the specified department.

• A department can have multiple managers.

• A user can manage multiple departments.

• Attempting to appoint an existing department manager may return manager.department.003.

Remove a manager

Endpoint: POST /v2/admin/departments/{departmentId}/users/{userId}/remove

Permission required: appoint_as_manager

This removes the specified department manager appointment.

Verify the changes

Retrieve the department:

GET /v2/admin/departments/{departmentId}

Or retrieve the user's departments:

GET /v2/admin/users/{userId}/department