Extensions

Extensions allow you to create 3 to 6-digit internal phone numbers (e.g. 1001, 1002) for agents, teams, SIP accounts, or voice AI agents within your workspace, enabling direct internal calling, IVR transfers, and call routing.

Endpoints

Method	Endpoint	Description
GET	/extensions	List all extensions
GET	/extensions/:id	Get extension details
POST	/extensions	Create an extension
PATCH	/extensions/:id	Update an extension
DELETE	/extensions/:id	Delete an extension

---

The Extension Object

Field	Type	Description
id	string	Unique extension identifier (prefixed with ex_)
workspace_id	string	Workspace identifier
extension_number	string	3 to 6-digit internal extension number (e.g. 1001, 1002)
title	string	Display label/name for the extension
destination	string	Destination target (agent, team, sip-account, voice-agent)
agent_id	string	Assigned agent ID (required if destination: agent)
team_id	string	Assigned team ID (required if destination: team)
sip_account_id	string	Assigned SIP account ID (required if destination: sip-account)
voice_agent_id	string	Assigned voice agent ID (required if destination: voice-agent)
agent	object	Populated agent object (when destination: agent)
team	object	Populated team object (when destination: team)
sip_account	object	Populated SIP account object (when destination: sip-account)
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp

---

List Extensions

GET /extensions

Retrieve a paginated list of extensions in the workspace.

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	10	Items per page (max: 100)
search	string	—	Search by extension title or number
sort_field	string	created_at	Sort field (extension_number, created_at, title)
sort_order	string	desc	Sort direction (asc, desc)

Response 200 OK

{
  "data": [
    {
      "id": "ex_987654321",
      "workspace_id": "ws_company",
      "extension_number": "1001",
      "title": "Sales Support Line",
      "destination": "agent",
      "agent_id": "ag_abc123",
      "agent": {
        "id": "ag_abc123",
        "username": "john_doe",
        "display_name": "John Doe",
        "email": "john@example.com",
        "avatar": "https://cdn.firetell.app/avatars/john.png"
      },
      "created_at": "2026-07-21T14:45:00.000Z",
      "updated_at": "2026-07-21T14:45:00.000Z"
    },
    {
      "id": "ex_123456789",
      "workspace_id": "ws_company",
      "extension_number": "1002",
      "title": "Support Queue",
      "destination": "team",
      "team_id": "team_xyz789",
      "team": {
        "id": "team_xyz789",
        "title": "Customer Support",
        "agent_count": 5
      },
      "created_at": "2026-07-21T14:50:00.000Z",
      "updated_at": "2026-07-21T14:50:00.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}

---

Get Extension Details

GET /extensions/:id

Retrieve details of a single extension by its ID.

Response 200 OK

{
  "id": "ex_987654321",
  "workspace_id": "ws_company",
  "extension_number": "1001",
  "title": "Sales Support Line",
  "destination": "agent",
  "agent_id": "ag_abc123",
  "agent": {
    "id": "ag_abc123",
    "username": "john_doe",
    "display_name": "John Doe",
    "email": "john@example.com"
  },
  "created_at": "2026-07-21T14:45:00.000Z",
  "updated_at": "2026-07-21T14:45:00.000Z"
}

---

Create Extension

POST /extensions

Create a new internal extension and assign its routing destination.

Request Body

{
  "title": "Sales Support Line",
  "extension_number": "1001",
  "destination": "agent",
  "agent_id": "ag_abc123"
}

Response 201 Created

{
  "id": "ex_987654321",
  "workspace_id": "ws_company",
  "extension_number": "1001",
  "title": "Sales Support Line",
  "destination": "agent",
  "agent_id": "ag_abc123",
  "created_at": "2026-07-21T14:45:00.000Z",
  "updated_at": "2026-07-21T14:45:00.000Z"
}

Error Responses

• 400 Bad Request: Invalid payload or missing required agent_id, team_id, or sip_account_id for the selected destination.
• 409 Conflict: The extension_number already exists within this workspace.

---

Update Extension

PATCH /extensions/:id

Update an extension's number, title, or routing destination.

Request Body

{
  "title": "Tier 1 Sales Support",
  "extension_number": "1005",
  "destination": "team",
  "team_id": "team_sales"
}

Response 200 OK

{
  "id": "ex_987654321",
  "workspace_id": "ws_company",
  "extension_number": "1005",
  "title": "Tier 1 Sales Support",
  "destination": "team",
  "team_id": "team_sales",
  "updated_at": "2026-07-21T15:00:00.000Z"
}

---

Delete Extension

DELETE /extensions/:id

Permanently remove an extension.

Response 200 OK

{
  "id": "ex_987654321",
  "workspace_id": "ws_company",
  "extension_number": "1005",
  "title": "Tier 1 Sales Support",
  "destination": "team"
}