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 for whitelisting inbound SIP traffic
`outbound_gateway_id`	string	ID of the assigned Outbound Gateway 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

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

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`

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

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

curl -X GET "https://{workspace_id}.firetell.app/api/v1/phone-numbers/pn_a1b2c3d4e5f6g7h8i9j0k1" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Response `200 OK`

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

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 for whitelisting inbound SIP traffic
`enable_outbound`	boolean	✅	Enable outbound calling
`outbound_gateway_id`	string	Optional	Outbound Gateway ID for trunk routing (required if `enable_outbound` is `true`)

Example Request

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`

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

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 for whitelisting inbound SIP traffic
`enable_outbound`	boolean	Enable/disable outbound calling
`outbound_gateway_id`	string	Outbound Gateway ID 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

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.

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

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

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.

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

Endpoints​

Phone Number Object​

List Phone Numbers​

Authentication​

Query Parameters​

Example Request​

Response 200 OK​

Get Phone Number Details​

Authentication​

Path Parameters​

Example Request​

Response 200 OK​

Error Responses​

Connect a Phone Number​

Authentication​

Request Body​

Example Request​

Response 201 Created​

Error Responses​

Update a Phone Number​

Authentication​

Path Parameters​

Request Body​

Example Request​

Response 200 OK​

Error Responses​

Delete a Phone Number​

Authentication​

Path Parameters​

Example Request​

Response 200 OK​

Error Responses​

Endpoints

Phone Number Object

List Phone Numbers

Authentication

Query Parameters

Example Request

Response `200 OK`

Get Phone Number Details

Authentication

Path Parameters

Example Request

Response `200 OK`

Error Responses

Connect a Phone Number

Authentication

Request Body

Example Request

Response `201 Created`

Error Responses

Update a Phone Number

Authentication

Path Parameters

Request Body

Example Request

Response `200 OK`

Error Responses

Delete a Phone Number

Authentication

Path Parameters

Example Request

Response `200 OK`

Error Responses