Departments

Departments are the original name of Teams: the same named groups of users, with the same ids. This group holds the four v2 endpoints: one flat list that embeds the members of every department, and three admin-only writes that answer a boolean. Prefer the v3 Teams endpoints for new work; use this list when you want every department with its members in one request.

Workflow (what the portal does)#

1. List: GET /v2/departments takes no parameters and answers a plain array, not a page, with every department of the account: id, name and users, the members as user_id, user_name and user_email.
2. Create (account admin): POST /v2/departments/store with name (required, at most 20 characters) answers 201 with id, name and an empty users. Members are added afterwards through Teams, or with user.departments on PUT /v3/users/{user} (see Users).
3. Rename (account admin): PUT /v2/departments/{department}/update with name answers the JSON boolean true. The name is the only thing this endpoint changes.
4. Delete (account admin): DELETE /v2/departments/{department}/delete answers true.

An unknown {department}, or one of another account, answers 404 from rename and delete. Each create, rename and delete is recorded in the account's change log as User group <name> has been added, renamed to <new name> or deleted.

Departments, users and extensions#

• A department is a set of users: a user may belong to several departments, and a department may be empty. Membership is the only relation a department has.
• Extensions follow their users. A user has at most one extension per account (see Extensions), so "the extensions of a department" means the extensions of its members. That is how the availability report GET /v2/extension-activity applies its departmentId filter, and how an AI call recap addressed to a department reaches the members whose extension was on the call.
• Departments carry no numbers, queues or permissions. What they gate — call tag visibility, conversation assignment, report filters and recap recipients — is listed under What a team does in Teams.

Roles and access#

• The list is open to any authenticated user. Create, rename and delete require an account admin; anyone else gets 403 "Forbidden".

Pitfalls#

• The paths carry the verb: POST …/store, PUT …/{department}/update, DELETE …/{department}/delete. There is no GET /v2/departments/{department}; read one department from the list, or from GET /v3/teams/{teamId}.
• Create answers 201 with the department; rename and delete answer a bare true, not the department.
• The list is unpaginated and always embeds the members. users carries no status, so a suspended member looks like an active one; check user_active in Users.
• name is limited to 20 characters and is not unique: two departments can share a name.
• name is the only field the writes accept; anything else in the body is ignored, so members cannot be set here.
• Validation errors answer 422 as {"errors": {...}}; a missing department answers 404 with {"message": "Resource not found!"}.