> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenia.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Team Management

> Organize users into teams for easier assignment and collaboration

## Overview

Teams allow you to group users together for easier task assignment, scheduling, and collaboration. Instead of assigning tasks to individuals, you can assign them to entire teams.

## Why Use Teams?

<CardGroup cols={2}>
  <Card title="Simplified Assignment" icon="check">
    Assign tasks to a team instead of selecting individuals
  </Card>

  <Card title="Flexible Coverage" icon="rotate">
    Any team member can complete assigned work
  </Card>

  <Card title="Easier Management" icon="users-gear">
    Add or remove members without updating individual assignments
  </Card>

  <Card title="Department Organization" icon="building">
    Mirror your organizational structure
  </Card>
</CardGroup>

***

## List Teams

Retrieve all teams in your workspace.

**Endpoint:** `GET /api/v1/mgt/workspaces/{workspaceId}/teams`

```bash theme={null}
curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/teams" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID"
```

**Response:**

```json theme={null}
{
  "status": true,
  "statusCode": 200,
  "data": [
    {
      "id": "team-uuid-1",
      "name": "Morning Shift",
      "description": "Staff working 6 AM - 2 PM",
      "memberCount": 8,
      "createdAt": "2024-01-15T10:00:00Z",
      "members": [
        {
          "id": "user-uuid-1",
          "firstName": "John",
          "lastName": "Doe",
          "emailId": "john.doe@example.com"
        },
        {
          "id": "user-uuid-2",
          "firstName": "Jane",
          "lastName": "Smith",
          "emailId": "jane.smith@example.com"
        }
      ]
    },
    {
      "id": "team-uuid-2",
      "name": "Maintenance Crew",
      "description": "Facility maintenance team",
      "memberCount": 4,
      "createdAt": "2024-01-20T14:30:00Z",
      "members": []
    }
  ]
}
```

***

## Get Team by ID

Retrieve details for a specific team including all members.

**Endpoint:** `GET /api/v1/mgt/workspaces/{workspaceId}/teams/{teamId}`

```bash theme={null}
curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/teams/{teamId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID"
```

**Response:**

```json theme={null}
{
  "status": true,
  "statusCode": 200,
  "data": {
    "id": "team-uuid",
    "name": "Morning Shift",
    "description": "Staff working 6 AM - 2 PM",
    "memberCount": 8,
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-02-01T08:00:00Z",
    "members": [
      {
        "id": "user-uuid-1",
        "firstName": "John",
        "lastName": "Doe",
        "fullName": "John Doe",
        "emailId": "john.doe@example.com",
        "role": {
          "id": "role-uuid",
          "title": "Full User"
        }
      },
      {
        "id": "user-uuid-2",
        "firstName": "Jane",
        "lastName": "Smith",
        "fullName": "Jane Smith",
        "emailId": "jane.smith@example.com",
        "role": {
          "id": "role-uuid",
          "title": "Full User"
        }
      }
    ]
  }
}
```

***

## Create Team

Create a new team in your workspace.

**Endpoint:** `POST /api/v1/mgt/workspaces/{workspaceId}/teams`

```bash theme={null}
curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/teams" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Evening Shift",
    "description": "Staff working 2 PM - 10 PM",
    "memberIds": [
      "user-uuid-1",
      "user-uuid-2",
      "user-uuid-3"
    ]
  }'
```

**Request Body:**

| Field         | Type   | Required | Description                             |
| ------------- | ------ | -------- | --------------------------------------- |
| `name`        | string | Yes      | Team name (must be unique in workspace) |
| `description` | string | No       | Team description                        |
| `memberIds`   | array  | No       | User IDs to add as initial members      |

**Response:**

```json theme={null}
{
  "status": true,
  "statusCode": 201,
  "message": "Team created successfully",
  "data": {
    "id": "new-team-uuid",
    "name": "Evening Shift",
    "description": "Staff working 2 PM - 10 PM",
    "memberCount": 3,
    "members": [
      {
        "id": "user-uuid-1",
        "firstName": "Alice",
        "lastName": "Johnson"
      },
      {
        "id": "user-uuid-2",
        "firstName": "Bob",
        "lastName": "Williams"
      },
      {
        "id": "user-uuid-3",
        "firstName": "Carol",
        "lastName": "Brown"
      }
    ]
  }
}
```

<Note>
  Team creation may be limited based on your subscription plan. Contact your account manager if you need to create more teams.
</Note>

***

## Update Team

Modify a team's name, description, or members.

**Endpoint:** `PUT /api/v1/mgt/workspaces/{workspaceId}/teams/{teamId}`

```bash theme={null}
curl -X PUT "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/teams/{teamId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Evening Shift - Extended",
    "description": "Staff working 2 PM - 11 PM",
    "memberIds": [
      "user-uuid-1",
      "user-uuid-2",
      "user-uuid-3",
      "user-uuid-4"
    ]
  }'
```

**Request Body:**

| Field         | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| `name`        | string | Updated team name                               |
| `description` | string | Updated description                             |
| `memberIds`   | array  | Complete list of member IDs (replaces existing) |

<Warning>
  The `memberIds` array replaces all existing members. Include all users you want in the team, not just new additions.
</Warning>

**Response:**

```json theme={null}
{
  "status": true,
  "statusCode": 200,
  "message": "Team updated successfully",
  "data": {
    "id": "team-uuid",
    "name": "Evening Shift - Extended",
    "description": "Staff working 2 PM - 11 PM",
    "memberCount": 4
  }
}
```

***

## Delete Team

Remove a team from the workspace.

**Endpoint:** `DELETE /api/v1/mgt/workspaces/{workspaceId}/teams/{teamId}`

```bash theme={null}
curl -X DELETE "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/teams/{teamId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID"
```

**Response:**

```json theme={null}
{
  "status": true,
  "statusCode": 200,
  "message": "Team deleted successfully"
}
```

<Warning>
  Deleting a team will unassign it from all tasks and schedules. Make sure to reassign work before deleting a team.
</Warning>

***

## Add Members to Team

To add members to an existing team, use the Update Team endpoint with the complete member list.

### Example: Add a New Member

**Step 1:** Get current team members

```bash theme={null}
curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/teams/{teamId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID"
```

**Step 2:** Update with new member added

```bash theme={null}
curl -X PUT "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/teams/{teamId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "memberIds": [
      "existing-user-1",
      "existing-user-2",
      "existing-user-3",
      "new-user-4"
    ]
  }'
```

***

## Remove Members from Team

Similar to adding members, remove members by updating the team with a filtered member list.

### Example: Remove a Member

```bash theme={null}
curl -X PUT "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/teams/{teamId}" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "memberIds": [
      "user-1",
      "user-2"
    ]
  }'
```

<Tip>
  To remove all members, pass an empty array: `"memberIds": []`
</Tip>

***

## Team Management Workflow Example

### Scenario: Setting Up Shift Teams

#### Step 1: Create Morning Shift Team

```bash theme={null}
curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/teams" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning Shift",
    "description": "6 AM - 2 PM coverage",
    "memberIds": ["user-1", "user-2", "user-3"]
  }'
```

#### Step 2: Create Evening Shift Team

```bash theme={null}
curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/teams" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Evening Shift",
    "description": "2 PM - 10 PM coverage",
    "memberIds": ["user-4", "user-5", "user-6"]
  }'
```

#### Step 3: Create Night Shift Team

```bash theme={null}
curl -X POST "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/teams" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Night Shift",
    "description": "10 PM - 6 AM coverage",
    "memberIds": ["user-7", "user-8"]
  }'
```

#### Step 4: List All Teams to Verify

```bash theme={null}
curl -X GET "https://api.xenia.team/api/v1/mgt/workspaces/{workspaceId}/teams" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "workspace-id: YOUR_WORKSPACE_ID"
```

***

## Common Team Structures

<AccordionGroup>
  <Accordion title="Shift-Based Teams">
    Organize by work shifts:

    * Morning Shift (6 AM - 2 PM)
    * Evening Shift (2 PM - 10 PM)
    * Night Shift (10 PM - 6 AM)
    * Weekend Crew
  </Accordion>

  <Accordion title="Department Teams">
    Organize by function:

    * Kitchen Staff
    * Front of House
    * Maintenance
    * Management
    * Housekeeping
  </Accordion>

  <Accordion title="Location-Based Teams">
    Organize by site:

    * Downtown Store Team
    * Mall Location Team
    * Warehouse Team
  </Accordion>

  <Accordion title="Specialty Teams">
    Organize by expertise:

    * Safety Inspectors
    * Quality Assurance
    * Training Team
    * Emergency Response
  </Accordion>
</AccordionGroup>

***

## Permissions Required

| Action           | Permission Required |
| ---------------- | ------------------- |
| List teams       | Authenticated       |
| Get team details | Authenticated       |
| Create team      | `CAN_MANAGE_TEAMS`  |
| Update team      | `CAN_MANAGE_TEAMS`  |
| Delete team      | `CAN_MANAGE_TEAMS`  |

***

## Using Teams with Tasks

Once you've created teams, you can assign tasks to entire teams instead of individuals. See the [Task Management](/guides/workflows/task-management) guide for details on team-based task assignment.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="User Lifecycle" icon="user" href="/guides/workflows/user-lifecycle">
    Manage user accounts
  </Card>

  <Card title="Role Management" icon="shield" href="/guides/workflows/role-management">
    Create and manage roles
  </Card>
</CardGroup>