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.

Authentication

All endpoints require Bearer JWT with agent-api audience. Some endpoints require specific team roles — see 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

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

{
  "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

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

{
  "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

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

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