--- sidebar_position: 1 title: Phone Numbers description: Manage virtual phone numbers — list, connect, configure, and release phone numbers via the API. --- # Phone Numbers Manage virtual phone numbers in your workspace. Phone numbers can be used for inbound/outbound calls, assigned to call flows, extensions, or SIP trunks. ## Endpoints | Method | Endpoint | Description | | -------- | ------------------------ | ---------------------------- | | `GET` | `/phone-numbers` | List all phone numbers | | `GET` | `/phone-numbers/:id` | Get phone number details | | `POST` | `/phone-numbers/connect` | Connect a new phone number | | `PATCH` | `/phone-numbers/:id` | Update phone number settings | | `DELETE` | `/phone-numbers/:id` | Release a phone number | ## Phone Number Object | Field | Type | Description | | --------------------- | -------------- | ---------------------------------------------------------------- | | `id` | string | Unique phone number ID (prefixed) | | `title` | string | Display name / label | | `number` | string | Full phone number with country calling code (e.g. `84901234567`) | | `country_code` | string | ISO 3166-1 alpha-2 country code (e.g. `VN`, `US`) | | `dial_code` | string | Country calling code (e.g. `84`, `1`) | | `status` | string | `pending`, `active`, or `inactive` | | `type` | string | `local`, `tollfree`, `mobile`, or `international` | | `capabilities` | string[] | Supported capabilities: `voice`, `sms` | | `provider` | string | Number provider: `firetell` or `sip_trunk` | | `enable_outbound` | boolean | Whether outbound calling is enabled | | `inbound_acl_id` | string | ID of the assigned [Inbound IP ACL](/docs/rest-api/workspace-api/sip-trunks#part-1-inbound-ip-access-control-lists-acls) for whitelisting inbound SIP traffic | | `outbound_gateway_id` | string | ID of the assigned [Outbound Gateway](/docs/rest-api/workspace-api/sip-trunks#part-2-outbound-gateways) for outbound trunk call routing | | `call_flow_id` | string \| null | ID of the assigned call flow (null if not assigned) | | `shared_teams_id` | string[] | IDs of teams this number is shared with | | `record_outbound` | boolean | Whether to record outbound calls | | `fee_per_month` | number | Monthly fee for this number | | `fee_per_mins_call` | number | Per-minute call fee | | `created_at` | string | ISO 8601 creation timestamp | | `updated_at` | string | ISO 8601 last update timestamp | --- ## List Phone Numbers ```bash GET /phone-numbers ``` Retrieves a paginated list of all phone numbers in the workspace. ### Authentication Requires `ApiKey` with any scope. ### Query Parameters | Parameter | Type | Default | Description | | ------------ | ------ | ------- | --------------------------------------- | | `page` | number | `1` | Page number (min: 1) | | `limit` | number | `20` | Items per page (min: 1, max: 100) | | `search` | string | — | Search by title or number (text search) | | `sort_field` | string | — | Sort by field: `created_at`, `title` | | `sort_order` | string | `desc` | Sort order: `asc` or `desc` | ### Example Request ```bash curl -X GET "https://{workspace_id}.firetell.app/api/v1/phone-numbers?page=1&limit=10&search=support" \ -H "Authorization: ApiKey YOUR_API_KEY" ``` ### Response `200 OK` ```json { "data": [ { "id": "pn_a1b2c3d4e5f6g7h8i9j0k1", "title": "Main Number", "number": "84901234567", "country_code": "VN", "dial_code": "84", "status": "active", "type": "local", "capabilities": ["voice"], "provider": "sip_trunk", "enable_outbound": true, "inbound_acl_id": "acl_abc123", "outbound_gateway_id": "gw_def456", "call_flow_id": "cf_ghi789", "shared_teams_id": [], "record_outbound": true, "fee_per_month": 0, "fee_per_mins_call": 0, "created_at": "2026-01-15T08:30:00.000Z", "updated_at": "2026-01-15T08:30:00.000Z" } ], "meta": { "total": 1, "page": 1, "limit": 10, "total_pages": 1 } } ``` --- ## Get Phone Number Details ```bash GET /phone-numbers/:id ``` Retrieve detailed information about a specific phone number, including populated ACL and gateway data. ### Authentication Requires `ApiKey` with `full` scope. ### Path Parameters | Parameter | Type | Description | | --------- | ------ | ------------------------------------- | | `id` | string | Phone number ID (e.g. `pn_a1b2c3...`) | ### Example Request ```bash curl -X GET "https://{workspace_id}.firetell.app/api/v1/phone-numbers/pn_a1b2c3d4e5f6g7h8i9j0k1" \ -H "Authorization: ApiKey YOUR_API_KEY" ``` ### Response `200 OK` ```json { "id": "pn_a1b2c3d4e5f6g7h8i9j0k1", "title": "Main Number", "number": "84901234567", "country_code": "VN", "dial_code": "84", "status": "active", "type": "local", "capabilities": ["voice"], "provider": "sip_trunk", "enable_outbound": true, "inbound_acl_id": "acl_abc123", "outbound_gateway_id": "gw_def456", "call_flow_id": "cf_ghi789", "shared_teams_id": [], "record_outbound": true, "fee_per_month": 0, "fee_per_mins_call": 0, "acl": { "id": "acl_abc123", "name": "SIP Trunk ACL", "workspace_id": "my_workspace" }, "gateway": { "id": "gw_def456", "name": "Primary Gateway", "workspace_id": "my_workspace" }, "created_at": "2026-01-15T08:30:00.000Z", "updated_at": "2026-01-15T08:30:00.000Z" } ``` ### Error Responses | Status | Description | | ------ | ----------------------------------------------------------- | | `404` | Phone number not found or does not belong to this workspace | --- ## Connect a Phone Number ```bash POST /phone-numbers/connect ``` Connect (provision) a new phone number to the workspace. The phone number will be created with `pending` status. The country calling code is automatically prepended to the number based on the `country_code`. ### Authentication Requires `ApiKey` with `full` scope. ### Request Body | Field | Type | Required | Description | | --------------------- | ------- | -------- | ----------------------------------------------------------------------- | | `title` | string | ✅ | Display name (1–36 characters) | | `number` | string | ✅ | Phone number **without** country code, digits only (6–14 chars) | | `country_code` | string | ✅ | ISO 3166-1 alpha-2 code (e.g. `VN`, `US`, `SG`) | | `inbound_acl_id` | string | ✅ | [Inbound ACL ID](/docs/rest-api/workspace-api/sip-trunks#part-1-inbound-ip-access-control-lists-acls) for whitelisting inbound SIP traffic | | `enable_outbound` | boolean | ✅ | Enable outbound calling | | `outbound_gateway_id` | string | Optional | [Outbound Gateway ID](/docs/rest-api/workspace-api/sip-trunks#part-2-outbound-gateways) for trunk routing (required if `enable_outbound` is `true`) | ### Example Request ```bash curl -X POST "https://{workspace_id}.firetell.app/api/v1/phone-numbers/connect" \ -H "Authorization: ApiKey YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Support Line", "number": "901234567", "country_code": "VN", "inbound_acl_id": "acl_abc123", "enable_outbound": true, "outbound_gateway_id": "gw_def456" }' ``` ### Response `201 Created` ```json { "id": "pn_x1y2z3w4v5u6t7s8r9q0p1", "title": "Support Line", "number": "84901234567", "country_code": "VN", "dial_code": "84", "status": "pending", "type": "local", "capabilities": ["voice"], "provider": "sip_trunk", "enable_outbound": true, "inbound_acl_id": "acl_abc123", "outbound_gateway_id": "gw_def456", "call_flow_id": null, "shared_teams_id": [], "record_outbound": true, "workspace_id": "my_workspace", "created_at": "2026-07-13T08:30:00.000Z", "updated_at": "2026-07-13T08:30:00.000Z" } ``` ### Error Responses | Status | Description | | ------ | ------------------------------------------------------- | | `400` | Validation error, invalid ACL ID, or invalid gateway ID | | `403` | Maximum limit of 100 phone numbers reached | | `409` | Phone number already exists in this workspace | :::tip The `number` field should contain **only digits** without the country calling code. For example, for a Vietnamese number `+84 901 234 567`, send `"number": "901234567"` with `"country_code": "VN"`. The system will automatically prepend `84`. ::: --- ## Update a Phone Number ```bash PATCH /phone-numbers/:id ``` Update settings for an existing phone number. All fields are optional — only include the fields you want to change. ### Authentication Requires `ApiKey` with `full` scope. ### Path Parameters | Parameter | Type | Description | | --------- | ------ | --------------- | | `id` | string | Phone number ID | ### Request Body | Field | Type | Description | | --------------------- | -------------- | --------------------------------------------- | | `title` | string | Display name (1–36 characters) | | `inbound_acl_id` | string | [Inbound ACL ID](/docs/rest-api/workspace-api/sip-trunks#part-1-inbound-ip-access-control-lists-acls) for whitelisting inbound SIP traffic | | `enable_outbound` | boolean | Enable/disable outbound calling | | `outbound_gateway_id` | string | [Outbound Gateway ID](/docs/rest-api/workspace-api/sip-trunks#part-2-outbound-gateways) for trunk routing | | `shared_teams_id` | string[] | Team IDs this number is shared with (max 100) | | `record_outbound` | boolean | Enable/disable outbound call recording | | `call_flow_id` | string \| null | Assign a call flow, or `null` to unassign | ### Example Request ```bash curl -X PATCH "https://{workspace_id}.firetell.app/api/v1/phone-numbers/pn_a1b2c3d4e5f6g7h8i9j0k1" \ -H "Authorization: ApiKey YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Support Line", "call_flow_id": "cf_new789", "record_outbound": false }' ``` ### Response `200 OK` Returns the updated phone number object. ```json { "id": "pn_a1b2c3d4e5f6g7h8i9j0k1", "title": "Support Line", "number": "84901234567", "status": "active", "call_flow_id": "cf_new789", "record_outbound": false, "updated_at": "2026-07-13T09:00:00.000Z" } ``` ### Error Responses | Status | Description | | ------ | ---------------------------- | | `400` | Invalid ACL ID or gateway ID | | `404` | Phone number not found | --- ## Delete a Phone Number ```bash DELETE /phone-numbers/:id ``` Release (delete) a phone number from the workspace. This action is permanent and cannot be undone. ### Authentication Requires `ApiKey` with `full` scope. ### Path Parameters | Parameter | Type | Description | | --------- | ------ | --------------- | | `id` | string | Phone number ID | ### Example Request ```bash curl -X DELETE "https://{workspace_id}.firetell.app/api/v1/phone-numbers/pn_a1b2c3d4e5f6g7h8i9j0k1" \ -H "Authorization: ApiKey YOUR_API_KEY" ``` ### Response `200 OK` Returns the deleted phone number object. ```json { "id": "pn_a1b2c3d4e5f6g7h8i9j0k1", "title": "Main Number", "number": "84901234567", "status": "active", "workspace_id": "my_workspace" } ``` ### Error Responses | Status | Description | | ------ | ----------------------------------------------------------- | | `404` | Phone number not found or does not belong to this workspace | :::caution Deleting a phone number is **irreversible**. Any call flows, extensions, or SIP trunks referencing this number will no longer route calls to it. Make sure to update or remove those references before deleting. :::