Get Team by ID
/v1/teams/{id}org.permission.team.readThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Gets a Team by ID.
Note To retrieve user records of all members within a team, use the results from the members array and make a subsequent call to Get User Multi
Teams
A team is a named group of users, such as "Billing" or "Tier 2". Conversations can be assigned to a team, routing uses teams to decide which queues and capacity rules apply to an agent, and teams can carry role groups that grant their members permissions.
Admins manage teams in Kustomer's user settings, and agents see them wherever work is assigned: a conversation can be assigned to a team as well as to a person. A user can be on any number of teams. Each team stores its members as a list of user IDs, and routing configuration for the team lives separately in team routing settings.
Fields
| Field | Meaning |
|---|---|
name |
Required, up to 256 characters |
displayName |
Optional label, up to 256 characters |
icon |
Optional icon name |
members |
User IDs of the team's members. Each must be a user in your org. |
externalId |
Optional ID from another system, set when creating |
createdAt, importedAt |
Optional on create, for teams migrated from another system |
Membership
There are two ways to change who is on a team. Sending members in PUT or PATCH /v1/teams/{id} replaces the whole list. POST /v1/teams/{id}/members adds the user IDs you send and DELETE /v1/teams/{id}/members removes them, leaving everyone else in place. Use the add and remove endpoints when more than one system manages membership, so one doesn't overwrite another's changes. A request can carry up to 1,000 member IDs, and a change that would push the team over its maximum number of active members fails with 409. To get the members' names and emails, pass the IDs to GET /v1/users/{ids}.
Deleting and role groups
Deleting a team is a soft delete: it's marked deleted rather than removed, so it still appears in lists. Pass deleted=false to GET /v1/teams or GET /v1/users/{id}/teams to return only active teams. Teams can have role groups assigned, which add to their members' permissions. Filter teams by role group with roleGroups, and add include=role-groups when listing a user's teams to get the role groups with them.
Which endpoint to use
| To | Call |
|---|---|
| List teams | GET /v1/teams |
| Find the teams a user is on | GET /v1/users/{id}/teams |
| Read one team and its member IDs | GET /v1/teams/{id} |
| Create a team | POST /v1/teams |
| Add or remove specific members | POST or DELETE /v1/teams/{id}/members |
| Change some of a team's fields | PATCH /v1/teams/{id} |
| Replace a team's fields | PUT /v1/teams/{id} |
| Delete a team | DELETE /v1/teams/{id} |
PUT requires name and clears optional fields you leave out, while PATCH changes only the fields you send, so prefer PATCH for small edits. Reading teams works with agent or admin read roles; changes need a team write role. List endpoints are paginated with page and pageSize (up to 500), and fields limits which attributes are returned.
Path parameters
Team ID
"5f184e74c61792001af42e49"Responses
OK