---
sidebar_position: 5
title: Teams
description: View teams you belong to and list teammates with real-time presence status via the Firetell Agent API.
---

# Teams

View the teams you belong to and list your teammates. These endpoints are scoped — you can only see teams where you are a member.

:::info Data Scoping
Unlike the admin Teams API which returns all teams, the call center Teams API only returns teams where the authenticated agent is a member.
:::

## Endpoints

| Method   | Endpoint                                              | Role Required              | Description                 |
| ------   | ----------------------------------------------------- | -------------------------- | --------------------------- |
| `GET`    | `/call-center/teams`                                  | Any                        | List active workspace teams |
| `GET`    | `/call-center/teams/:id/agents`                       | Any                        | List teammates (if member)  |
| `PUT`    | `/call-center/teams/:id/agents/:agent_id`             | `leader`                   | Assign agent to team        |
| `DELETE` | `/call-center/teams/:id/agents/:agent_id`             | `leader`                   | Remove agent from team      |
| `GET`    | `/call-center/teams/:team_id/call-history`            | `leader`, `supervisor`     | Team call history           |
| `GET`    | `/call-center/teams/:team_id/contacts`                | `leader`                   | Team contacts               |
| `GET`    | `/call-center/teams/:team_id/agents/states`           | `leader`, `supervisor`     | Team agent states           |
| `PUT`    | `/call-center/teams/:team_id/agents/:username/state`  | `leader`, `supervisor`     | Force agent state           |

:::info
Role checks (`leader`, `supervisor`) are based on the agent's **workspace-level role**, not a per-team assignment. Roles are managed by admins via the [Agents API](/docs/rest-api/workspace-api/agents).
:::

## Authentication

All endpoints require `Bearer` JWT with `agent-api` audience. Some endpoints require specific team roles — see [Roles & Permissions](/docs/rest-api/agent-api/roles-permissions).

---

## List Active Workspace Teams

```
GET /call-center/teams
```

Retrieve a paginated list of all active teams in the workspace (useful for choosing target departments for call transfer). Note: To list only the teams you belong to, use `GET /me/teams`.

### Query Parameters

| Parameter | Type   | Default | Description              |
| --------- | ------ | ------- | ------------------------ |
| `page`    | number | `1`     | Page number (min: 1)     |
| `limit`   | number | `10`    | Items per page (max: 100)|

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/teams?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"
```

### Response `200 OK`

```json
{
  "data": [
    {
      "id": "tm_a1b2c3d4e5f6g7h8i9j0k1",
      "workspace_id": "my_workspace",
      "title": "Sales Team",
      "agent_count": 5,
      "created_at": "2026-01-10T10:00:00.000Z",
      "updated_at": "2026-07-01T12:00:00.000Z"
    },
    {
      "id": "tm_x9y8z7w6v5u4t3s2r1q0p9",
      "workspace_id": "my_workspace",
      "title": "Support Team",
      "agent_count": 8,
      "created_at": "2026-02-15T08:00:00.000Z",
      "updated_at": "2026-06-20T09:30:00.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}
```

### Team Object

| Field          | Type   | Description                      |
| -------------- | ------ | -------------------------------- |
| `id`           | string | Team ID                          |
| `workspace_id` | string | Workspace identifier              |
| `title`        | string | Team name                        |
| `agent_count`  | number | Number of agents in the team     |
| `created_at`   | string | ISO 8601 creation timestamp      |
| `updated_at`   | string | ISO 8601 last update timestamp   |

---

## List Teammates

```
GET /call-center/teams/:id/agents
```

List agents in a specific team, excluding yourself. Includes real-time presence state.

### Path Parameters

| Parameter | Type   | Description                          |
| --------- | ------ | ------------------------------------ |
| `id`      | string | Team ID (e.g., `tm_a1b2c3...`)       |

### Query Parameters

| Parameter | Type   | Default | Description              |
| --------- | ------ | ------- | ------------------------ |
| `page`    | number | `1`     | Page number (min: 1)     |
| `limit`   | number | `10`    | Items per page (max: 100)|

### Request

```bash
curl -X GET "https://{workspace_id}.firetell.app/api/v1/call-center/teams/tm_a1b2c3d4e5f6g7h8i9j0k1/agents" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"
```

### Response `200 OK`

```json
{
  "data": [
    {
      "username": "jane.smith",
      "display_name": "Jane Smith",
      "avatar": "https://storage.firetell.app/avatars/jane.jpg",
      "state": "available",
      "role": "leader"
    },
    {
      "username": "bob.nguyen",
      "display_name": "Bob Nguyen",
      "avatar": null,
      "state": "on_call",
      "role": "member"
    },
    {
      "username": "alice.tran",
      "display_name": "Alice Tran",
      "avatar": null,
      "state": "offline",
      "role": "member"
    }
  ],
  "meta": {
    "total": 4,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}
```

### Teammate Object

| Field          | Type         | Description                                              |
| -------------- | ------------ | -------------------------------------------------------- |
| `username`     | string       | Agent username                                           |
| `display_name` | string       | Display name                                             |
| `avatar`       | string\|null | Avatar URL                                               |
| `state`        | string       | Real-time presence: `available`, `incall`, `busy`, `offline` |
| `role`         | string       | Agent's workspace-level role: `agent`, `leader`, or `supervisor` |

:::info
The `role` field is the agent's **account-level role**, not a per-team assignment. Roles are managed globally by workspace admins.
:::

### Error Responses

| Status | Description                         |
| ------ | ----------------------------------- |
| `403`  | You are not a member of this team   |
| `404`  | Agent not found                     |

:::tip
Use the `state` field to show real-time availability indicators in your call center UI. Agents with `available` state are ready to receive calls.
:::

---

## Assign Agent to Team

```
PUT /call-center/teams/:id/agents/:agent_id
```

Add an agent to a team. **Requires `leader` role.**

### Path Parameters

| Parameter  | Type   | Description                             |
| ---------- | ------ | --------------------------------------- |
| `id`       | string | Team ID (e.g., `tm_a1b2c3...`)          |
| `agent_id` | string | Agent ID to assign (e.g., `ag_x1y2...`) |

### Request

```bash
curl -X PUT "https://{workspace_id}.firetell.app/api/v1/call-center/teams/tm_a1b2c3d4e5f6g7h8i9j0k1/agents/ag_x1y2z3w4v5u6t7s8" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"
```

### Response `200 OK`

Returns the created team-agent membership object.

### Error Responses

| Status | Description                        |
| ------ | ---------------------------------- |
| `403`  | Forbidden — requires `leader` role |
| `404`  | Team or agent not found            |

---

## Remove Agent from Team

```
DELETE /call-center/teams/:id/agents/:agent_id
```

Remove an agent from a team. **Requires `leader` role.**

### Path Parameters

| Parameter  | Type   | Description                             |
| ---------- | ------ | --------------------------------------- |
| `id`       | string | Team ID (e.g., `tm_a1b2c3...`)          |
| `agent_id` | string | Agent ID to remove (e.g., `ag_x1y2...`) |

### Request

```bash
curl -X DELETE "https://{workspace_id}.firetell.app/api/v1/call-center/teams/tm_a1b2c3d4e5f6g7h8i9j0k1/agents/ag_x1y2z3w4v5u6t7s8" \
  -H "Authorization: Bearer YOUR_AGENT_JWT"
```

### Response `200 OK`

Returns the removed team-agent membership object.

### Error Responses

| Status | Description                        |
| ------ | ---------------------------------- |
| `403`  | Forbidden — requires `leader` role |
| `404`  | Team-agent membership not found    |