---
sidebar_position: 4
title: Extensions
description: Manage internal extensions for call routing within your workspace via the Firetell REST API.
---

# 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`

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

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

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

### Response `201 Created`

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

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

### Response `200 OK`

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

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