---
sidebar_position: 6
title: Phone Numbers
description: View phone numbers available to your teams — read-only access to workspace phone numbers via the Firetell Agent API.
---

# Phone Numbers

View phone numbers available to the teams you belong to. These endpoints are **read-only** — phone number management (create, update, delete) is only available via the admin Workspace API.

:::info Data Scoping
Agents can only see phone numbers where:
- `shared_teams_id` contains at least one of the agent's teams, **or**
- `shared_teams_id` is empty (available to all agents)

Only phone numbers with `active` status are returned.
:::

## Endpoints

| Method | Endpoint                              | Description                         |
| ------ | ------------------------------------- | ----------------------------------- |
| `GET`  | `/call-center/phone-numbers`          | List phone numbers (scoped)         |
| `GET`  | `/call-center/phone-numbers/:id`      | Get phone number details            |

## Authentication

All endpoints require `Bearer` JWT with `agent-api` audience.

---

## List Phone Numbers

```
GET /call-center/phone-numbers
```

Retrieve a paginated list of phone numbers available to your teams.

### Query Parameters

| Parameter    | Type   | Default | Description              |
| ------------ | ------ | ------- | ------------------------ |
| `page`       | number | `1`     | Page number (min: 1)     |
| `limit`      | number | `20`    | Items per page (max: 100)|
| `sort_order` | string | `desc`  | Sort order: `asc` or `desc` |

### Request

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

### Response `200 OK`

```json
{
  "data": [
    {
      "id": "pn_a1b2c3d4e5f6g7h8i9j0k1",
      "number": "84901234567",
      "country_code": "VN",
      "dial_code": "84",
      "status": "active",
      "capabilities": ["voice"],
      "enable_outbound": true,
      "shared_teams_id": ["tm_x1y2z3w4v5u6t7s8"],
      "created_at": "2026-01-10T10:00:00.000Z"
    },
    {
      "id": "pn_n3w1d2e3f4g5h6i7j8k9l0",
      "number": "84281234567",
      "country_code": "VN",
      "dial_code": "84",
      "status": "active",
      "capabilities": ["voice"],
      "enable_outbound": false,
      "shared_teams_id": [],
      "created_at": "2026-03-15T08:00:00.000Z"
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}
```

### Phone Number Object

| Field              | Type     | Description                                          |
| ------------------ | -------- | ---------------------------------------------------- |
| `id`               | string   | Phone number ID (prefixed `pn_`)                     |
| `number`           | string   | Full phone number (without `+`)                      |
| `country_code`     | string   | ISO 3166-1 alpha-2 country code (e.g., `"VN"`)      |
| `dial_code`        | string   | Country calling code (e.g., `"84"`)                  |
| `status`           | string   | Always `active` for call center endpoints            |
| `capabilities`     | string[] | Supported features (e.g., `["voice"]`)               |
| `enable_outbound`  | boolean  | Whether outbound calls are enabled                   |
| `shared_teams_id`  | string[] | Teams that have access to this number                |
| `created_at`       | string   | ISO 8601 creation timestamp                          |

---

## Get Phone Number Details

```
GET /call-center/phone-numbers/:id
```

Retrieve details of a specific phone number you have access to.

### Path Parameters

| Parameter | Type   | Description                           |
| --------- | ------ | ------------------------------------- |
| `id`      | string | Phone number ID (e.g., `pn_a1b2...`)  |

### Request

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

### Response `200 OK`

Returns the phone number object.

### Error Responses

| Status | Description                                      |
| ------ | ------------------------------------------------ |
| `404`  | Phone number not found or you do not have access |

:::tip
Use the `enable_outbound` field to determine which phone numbers can be used as the caller ID when making outbound calls. Numbers with `enable_outbound: false` can only receive inbound calls.
:::