Add Users to Department - COMPASS API Documentation

Add users to a department

curl --request PUT \
  --url http://localhost:2000/department/add-users/{departmentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "users": [
    "64ef3c29f9a1c27e1b2c3b5e",
    "64ef3c29f9a1c27e1b2c3b5f"
  ],
  "departmentRole": "Manager"
}
'

import requests

url = "http://localhost:2000/department/add-users/{departmentId}"

payload = {
    "users": ["64ef3c29f9a1c27e1b2c3b5e", "64ef3c29f9a1c27e1b2c3b5f"],
    "departmentRole": "Manager"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    users: ['64ef3c29f9a1c27e1b2c3b5e', '64ef3c29f9a1c27e1b2c3b5f'],
    departmentRole: 'Manager'
  })
};

fetch('http://localhost:2000/department/add-users/{departmentId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "2000",
  CURLOPT_URL => "http://localhost:2000/department/add-users/{departmentId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'users' => [
        '64ef3c29f9a1c27e1b2c3b5e',
        '64ef3c29f9a1c27e1b2c3b5f'
    ],
    'departmentRole' => 'Manager'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:2000/department/add-users/{departmentId}"

	payload := strings.NewReader("{\n  \"users\": [\n    \"64ef3c29f9a1c27e1b2c3b5e\",\n    \"64ef3c29f9a1c27e1b2c3b5f\"\n  ],\n  \"departmentRole\": \"Manager\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("http://localhost:2000/department/add-users/{departmentId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"users\": [\n    \"64ef3c29f9a1c27e1b2c3b5e\",\n    \"64ef3c29f9a1c27e1b2c3b5f\"\n  ],\n  \"departmentRole\": \"Manager\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:2000/department/add-users/{departmentId}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"users\": [\n    \"64ef3c29f9a1c27e1b2c3b5e\",\n    \"64ef3c29f9a1c27e1b2c3b5f\"\n  ],\n  \"departmentRole\": \"Manager\"\n}"

response = http.request(request)
puts response.read_body

{
  "message": "Successfully added users to Engineering department",
  "data": {}
}

PUT

department

add-users

{departmentId}

Add users to a department

curl --request PUT \
  --url http://localhost:2000/department/add-users/{departmentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "users": [
    "64ef3c29f9a1c27e1b2c3b5e",
    "64ef3c29f9a1c27e1b2c3b5f"
  ],
  "departmentRole": "Manager"
}
'

import requests

url = "http://localhost:2000/department/add-users/{departmentId}"

payload = {
    "users": ["64ef3c29f9a1c27e1b2c3b5e", "64ef3c29f9a1c27e1b2c3b5f"],
    "departmentRole": "Manager"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    users: ['64ef3c29f9a1c27e1b2c3b5e', '64ef3c29f9a1c27e1b2c3b5f'],
    departmentRole: 'Manager'
  })
};

fetch('http://localhost:2000/department/add-users/{departmentId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "2000",
  CURLOPT_URL => "http://localhost:2000/department/add-users/{departmentId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'users' => [
        '64ef3c29f9a1c27e1b2c3b5e',
        '64ef3c29f9a1c27e1b2c3b5f'
    ],
    'departmentRole' => 'Manager'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:2000/department/add-users/{departmentId}"

	payload := strings.NewReader("{\n  \"users\": [\n    \"64ef3c29f9a1c27e1b2c3b5e\",\n    \"64ef3c29f9a1c27e1b2c3b5f\"\n  ],\n  \"departmentRole\": \"Manager\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("http://localhost:2000/department/add-users/{departmentId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"users\": [\n    \"64ef3c29f9a1c27e1b2c3b5e\",\n    \"64ef3c29f9a1c27e1b2c3b5f\"\n  ],\n  \"departmentRole\": \"Manager\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:2000/department/add-users/{departmentId}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"users\": [\n    \"64ef3c29f9a1c27e1b2c3b5e\",\n    \"64ef3c29f9a1c27e1b2c3b5f\"\n  ],\n  \"departmentRole\": \"Manager\"\n}"

response = http.request(request)
puts response.read_body

{
  "message": "Successfully added users to Engineering department",
  "data": {}
}

Admin-only endpoint to add multiple users to a department with a specific role.

Request

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer token
Content-Type	string	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
departmentId	string	Yes	Department ID to add users to

Request Body

{
  "userIds": [
    "64b7f1a2e4b0a5d3f9c12345",
    "64b7f2b3e4b0a5d3f9c54321",
    "64b7f3c4e4b0a5d3f9c98765"
  ],
  "role": "agent"
}

Request Body Schema

Field	Type	Required	Description
userIds	array	Yes	List of user IDs to add to department
role	string	Yes	Role to assign to users in department

Field Details

userIds: Array of valid MongoDB ObjectIds
role: Department role (e.g., “manager”, “supervisor”, “agent”, “admin”)

Response

200 OK - Successfully added users to department

{
  "message": "Successfully added users to Engineering department",
  "data": {
    "addedUsers": [
      {
        "userId": "64b7f1a2e4b0a5d3f9c12345",
        "name": "John Doe",
        "role": "agent"
      },
      {
        "userId": "64b7f2b3e4b0a5d3f9c54321",
        "name": "Jane Smith",
        "role": "agent"
      }
    ],
    "departmentId": "64ef3c29f9a1c27e1b2c3a4d"
  }
}

400 Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Department not found or invalid user IDs"
  }
}

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid token or insufficient permissions"
  }
}

500 Internal Server Error

{
  "error": {
    "code": "SERVER_ERROR",
    "message": "Internal server error"
  }
}

Example

curl -X PUT 'http://localhost:2000/department/add-users/64ef3c29f9a1c27e1b2c3a4d' \
  -H 'Authorization: Bearer your-jwt-token' \
  -H 'Content-Type: application/json' \
  -d '{
    "userIds": [
      "64b7f1a2e4b0a5d3f9c12345",
      "64b7f2b3e4b0a5d3f9c54321"
    ],
    "role": "agent"
  }'

Notes

This is an admin-only endpoint - requires administrative privileges
Department ID must be a valid MongoDB ObjectId
All user IDs must be valid MongoDB ObjectIds
Users can only be added to one department at a time
If users are already in a department, they will be moved
The role applies to all users being added
Users receive department-based permissions based on their role

Role Definitions

Role	Description	Permissions
manager	Department manager	Full department access
supervisor	Team supervisor	Team management access
agent	Regular department member	Standard department access
admin	Department administrator	Administrative access

Use Cases

Onboarding: Add new employees to their department
Team Transfers: Move users between departments
Bulk Assignment: Add multiple users efficiently
Role Changes: Assign specific roles to new members

Best Practices

Verify Users: Ensure all user IDs exist before adding
Role Assignment: Choose appropriate roles for users
Communication: Notify users of department changes
Permissions: Review role permissions before assignment
Audit: Track department membership changes

Error Handling

Invalid User IDs: Users that don’t exist are skipped
Already Assigned: Users are moved from current department
Invalid Role: Returns validation error
Department Not Found: Returns 404 error

Impact on Users

Users gain access to department resources
Previous department assignments are replaced
Role-based permissions are applied immediately
Users may see new teams and projects in their dashboard

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

departmentId

string

required

Unique identifier of the department

Body

application/json

users

string[]

required

List of user IDs to add to the department

Example:

[
  "64ef3c29f9a1c27e1b2c3b5e",
  "64ef3c29f9a1c27e1b2c3b5f"
]

departmentRole

string

required

Role to assign to the users in the department

Example:

"Manager"

Response

Successfully added users to department

message

string

Example:

"Successfully added users to Engineering department"

data

object

Delete Department Assign Department Manager

​Request

​Headers

​Path Parameters

​Request Body

​Request Body Schema

​Field Details

​Response

​200 OK - Successfully added users to department

​400 Bad Request

​401 Unauthorized

​500 Internal Server Error

​Example

​Notes

​Role Definitions

​Use Cases

​Best Practices

​Error Handling

​Impact on Users

Authorizations

Path Parameters

Body

Response

Request

Headers

Path Parameters

Request Body

Request Body Schema

Field Details

Response

200 OK - Successfully added users to department

400 Bad Request

401 Unauthorized

500 Internal Server Error

Example

Notes

Role Definitions

Use Cases

Best Practices

Error Handling

Impact on Users