Skip to main content

Team

aka Office, Region, Department, etc.

📄️ List Teams

Lists the teams visible to the authenticated user in their company, with each team's place in the org tree: its parent (`parentId`) and all ancestors (`parentTeamIds`), its direct children (`childTeamIds`), whether it is a leaf (`isLeaf`), and its `level` with the company's name for that level (`levelName`). Users with company-wide team access see every team; others see only their downline or visibility-restricted teams, and under impersonation the impersonated user's. Children and leaves are computed from the teams the caller can see, so a team whose child teams are all hidden from the caller is a leaf for that caller. Archived teams are excluded unless `showArchived` is set. Set `leaves` to list only leaf teams, the bottom of the org chart, and `underTeamId` to list only the teams below one team (combine them for the leaves under a team). To report on the lowest teams a user sees, find the user (for example with `/search`), make the request as that user (impersonating them needs `user:login`), list with `leaves`, then report on a returned `teamId`. Use `/team/get` for a single team's members and child teams, or `/team/downline` to list the users under a team.

📄️ Get Team Details

Retrieves a single team by `teamId`, along with its active members (with their team roles) and its direct child teams. The team carries the same org-tree fields as `/team/list` (`childTeamIds`, `isLeaf`, `levelName`), computed from the teams the caller can list. `childTeams` lists every direct child of the team, so it can include children that `childTeamIds` leaves out because the caller cannot list them. Requires the `team:list` permission on the team. Use `/team/list` to discover team IDs, or `/team/downline` to get every user on the team and all of its sub-teams.

📄️ Update Team

Updates an existing team's properties, such as its name, description, parent team, office address, or meeting times. Omitted fields are unchanged. Set `officeAddress` or `officeLocation` to `null` to clear it; an empty `officeAddress` leaves the saved address unchanged. Requires the `team:update` permission on the team; changing `restrictVisibility` also requires `company:update`. Fields listed in the company's `lockedTeamFields` preference can be changed only by callers with `user:manage` on the team. Locking `officeAddress` also locks `officeLocation`. A request from anyone else that changes a locked field is rejected and nothing is saved. Locking `avatar` instead withholds `uploadAvatarUrl` from `/team/get` from anyone without `user:manage` on the team. A team cannot be moved under one of its own sub-teams. To change who is on the team, use the `/team/member/*` endpoints instead.