SIP Trunks

SIP Trunks allow you to connect your existing IP PBX or telephony infrastructure to Firetell's cloud communications network for inbound and outbound voice traffic.

SIP Trunking in Firetell consists of two primary resources:

1. Inbound IP Access Control Lists (ACLs): Whitelist IP addresses or CIDR blocks allowed to send inbound SIP calls into Firetell.
2. Outbound Gateways: Configure outbound carrier SIP trunks, origination target URIs, protocols, and SIP authentication credentials.

---

Resource Endpoints

Inbound IP Access Control Lists (ACLs)

Method	Endpoint	Description
GET	/sip-trunks/acls	List all Inbound ACLs
GET	/sip-trunks/acls/:id	Get Inbound ACL details
POST	/sip-trunks/acls	Create an Inbound ACL
PATCH	/sip-trunks/acls/:id	Update an Inbound ACL
DELETE	/sip-trunks/acls/:id	Delete an Inbound ACL

Outbound Gateways

Method	Endpoint	Description
GET	/sip-trunks/gateways	List all Outbound Gateways
GET	/sip-trunks/gateways/:id	Get Outbound Gateway details
POST	/sip-trunks/gateways	Create an Outbound Gateway
PATCH	/sip-trunks/gateways/:id	Update an Outbound Gateway
DELETE	/sip-trunks/gateways/:id	Delete an Outbound Gateway

---

Part 1: Inbound IP Access Control Lists (ACLs)

Inbound ACLs control which remote IP addresses or subnets are authorized to send inbound SIP traffic into your Firetell workspace.

The ACL Object

Field	Type	Description
id	string	Unique ACL identifier (prefixed with acl_)
workspace_id	string	Workspace identifier
title	string	Descriptive label for this ACL
mode	string	Filter mode (ip or domain)
allowed_ips	array	List of authorized IPv4/IPv6 addresses or CIDR blocks (max: 5)
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp

---

List Inbound ACLs

GET /sip-trunks/acls

Query Parameters

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

Response 200 OK

{
  "data": [
    {
      "id": "acl_123456789",
      "workspace_id": "ws_company",
      "title": "Primary PBX Server",
      "mode": "ip",
      "allowed_ips": ["118.69.123.45", "203.162.0.0/24"],
      "created_at": "2026-07-21T15:00:00.000Z",
      "updated_at": "2026-07-21T15:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}

---

Create Inbound ACL

POST /sip-trunks/acls

Request Body

{
  "title": "Backup Data Center PBX",
  "mode": "ip",
  "allowed_ips": ["14.225.10.12/32"]
}

Response 201 Created

{
  "id": "acl_987654321",
  "workspace_id": "ws_company",
  "title": "Backup Data Center PBX",
  "mode": "ip",
  "allowed_ips": ["14.225.10.12/32"],
  "created_at": "2026-07-21T15:15:00.000Z",
  "updated_at": "2026-07-21T15:15:00.000Z"
}

---

Update Inbound ACL

PATCH /sip-trunks/acls/:id

Request Body

{
  "title": "HQ Asterisk PBX",
  "allowed_ips": ["118.69.123.45", "118.69.123.46"]
}

Response 200 OK

{
  "id": "acl_123456789",
  "workspace_id": "ws_company",
  "title": "HQ Asterisk PBX",
  "mode": "ip",
  "allowed_ips": ["118.69.123.45", "118.69.123.46"],
  "updated_at": "2026-07-21T15:20:00.000Z"
}

---

Delete Inbound ACL

DELETE /sip-trunks/acls/:id

Response 200 OK

{
  "id": "acl_123456789",
  "workspace_id": "ws_company",
  "title": "HQ Asterisk PBX"
}

---

Part 2: Outbound Gateways

Outbound Gateways define carrier trunks and remote SIP endpoints for routing outbound calls from Firetell to external telco networks or private PBX systems.

The Gateway Object

Field	Type	Description
id	string	Unique gateway identifier (prefixed with gw_)
workspace_id	string	Workspace identifier
title	string	Descriptive label for this gateway
outbound_caller_id	string	Default caller ID number to present when placing calls via this trunk
outbound_uris	array	Array of target SIP destination URIs (1 to 10 targets)
outbound_uris[].uri	string	Destination IP or FQDN host (e.g. sip.telco.com or 1.2.3.4)
outbound_uris[].port	number	SIP port (1 to 65535, default 5060)
outbound_uris[].protocol	string	Transport protocol (udp, tcp, tls)
outbound_uris[].priority	number	Routing priority order (1 highest to 10)
credential	object	SIP Digest authentication credentials (if required by trunk provider)
credential.username	string	SIP auth username
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp

---

List Outbound Gateways

GET /sip-trunks/gateways

Response 200 OK

{
  "data": [
    {
      "id": "gw_abc123456",
      "workspace_id": "ws_company",
      "title": "Viettel Carrier Trunk",
      "outbound_caller_id": "842471001234",
      "outbound_uris": [
        {
          "uri": "10.0.1.50",
          "port": 5060,
          "protocol": "udp",
          "priority": 1
        }
      ],
      "credential": {
        "username": "vt_trunk_user"
      },
      "created_at": "2026-07-21T15:05:00.000Z",
      "updated_at": "2026-07-21T15:05:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}

---

Create Outbound Gateway

POST /sip-trunks/gateways

Request Body

{
  "title": "FPT Telecom Trunk",
  "outbound_caller_id": "842873009999",
  "outbound_uris": [
    {
      "uri": "sip.fpttelecom.vn",
      "port": 5060,
      "protocol": "udp",
      "priority": 1
    }
  ],
  "credential": {
    "username": "fpt_user",
    "password": "SecretPassword123"
  }
}

Response 201 Created

{
  "id": "gw_xyz789012",
  "workspace_id": "ws_company",
  "title": "FPT Telecom Trunk",
  "outbound_caller_id": "842873009999",
  "outbound_uris": [
    {
      "uri": "sip.fpttelecom.vn",
      "port": 5060,
      "protocol": "udp",
      "priority": 1
    }
  ],
  "created_at": "2026-07-21T15:25:00.000Z",
  "updated_at": "2026-07-21T15:25:00.000Z"
}

---

Update Outbound Gateway

PATCH /sip-trunks/gateways/:id

Request Body

{
  "title": "FPT Telecom Primary Trunk",
  "outbound_uris": [
    {
      "uri": "sip.fpttelecom.vn",
      "port": 5061,
      "protocol": "tls",
      "priority": 1
    }
  ]
}

Response 200 OK

{
  "id": "gw_xyz789012",
  "workspace_id": "ws_company",
  "title": "FPT Telecom Primary Trunk",
  "outbound_uris": [
    {
      "uri": "sip.fpttelecom.vn",
      "port": 5061,
      "protocol": "tls",
      "priority": 1
    }
  ],
  "updated_at": "2026-07-21T15:30:00.000Z"
}

---

Delete Outbound Gateway

DELETE /sip-trunks/gateways/:id

Response 200 OK

{
  "id": "gw_xyz789012",
  "workspace_id": "ws_company",
  "title": "FPT Telecom Primary Trunk"
}