API Reference

SIP Trunks API

Create and manage tenant-owned SIP trunks. Use /sip-trunks/onboard for the standard outbound SIP setup: it provisions the outbound trunk, registers the caller ID numbers, and can set the trunk as the tenant default in one all-or-nothing operation.

Base URL: https://api.aethexai.com/api/v1
Endpoints: 7
Scopes: sip_trunks:readsip_trunks:writephone_numbers:write

POST/sip-trunks/onboard

One-shot outbound SIP setup.

Onboard SIP Trunk

Creates an outbound SIP trunk and registers its E.164 caller ID numbers in one request. This is the happy path for BYO-carrier outbound SIP and requires both sip_trunks:write and phone_numbers:write. If set_as_tenant_default is true, Aethex uses this trunk when a call does not resolve to a more specific trunk from the from_number registration. If any step fails, Aethex rolls back the trunk and no partial phone-number registration is committed.

Request body

namestringrequired
Display name for the trunk, 1-255 plain-text characters.
outbound_addressstringrequired
Carrier SIP host or host:port that Aethex sends INVITEs to.
numbersstring[]required
One to 100 caller ID numbers to register to this trunk, in E.164 (+14155557654) or as bare digits (14155557654) for carriers that reject a leading plus. The carrier sees the value exactly as given.
auth_modestringoptional
digest (default), ip_acl, or digest_plus_ip_acl.
auth_usernamestringoptional
Digest username. Required when auth_mode includes digest.
auth_passwordstringoptional
Digest password. Required when auth_mode includes digest; never returned.
transportstringoptional
udp (default), tcp, or tls.
media_encryptionstringoptional
allow (default), disable, or require for SRTP negotiation.
outbound_dial_formatstringoptional
How outbound destinations are dialed to the carrier. e164 (default) keeps +E.164; digits strips the leading +; national renders the destination country's national dialing format (+15551234567 -> 05551234567, required by some national-only carriers). Use national only on single-calling-code trunks: a destination outside your trunk's own numbers' calling code is refused rather than dialed.
agent_idstringoptional
Agent UUID for inbound calls to the registered numbers.
inboundobjectoptional
Initial fallback routing rules for the registered numbers.
outbound_enabledbooleanoptional
Whether the registered numbers can be used as outbound from_number values. Default true.
destination_allowlistobjectoptional
{ "mode": "allowlist" | "blocklist", "entries": ["+1800"] } outbound dial guard.
max_concurrent_callsintegeroptional
Per-trunk concurrency cap. Default 10. Values above the platform ceiling are clamped.
calls_per_hour_limitintegeroptional
Optional hourly cap on outbound calls through this trunk. Leave it out for no hourly cap, the default. Values above the platform ceiling are clamped.
set_as_tenant_defaultbooleanoptional
Set this trunk as the tenant default outbound trunk. Default false.

Errors

400Invalid outbound auth contract

auth_mode, auth_username, auth_password, and outbound_address are inconsistent.

For digest, send both username and password. For ip_acl, omit both. For both controls, use digest_plus_ip_acl.

404Agent not found

The supplied agent_id does not belong to the account.

Check the agent ID with GET /agents, or omit agent_id.

409Number already registered

One of the requested numbers is already active on an account.

Use a different number or release the existing phone-number registration first.

422Validation error

A number is not E.164, the outbound address is invalid, or a field violates the schema.

Use + followed by 1-15 digits for numbers and a carrier host or host:port for outbound_address.

502SIP provisioning failed

The SIP trunk could not be provisioned.

Retry after checking SIP service health. A failed onboard rolls back partial state.

Request

json

{
  "name": "Production carrier",
  "outbound_address": "sip.carrier.example.com:5060",
  "numbers": ["+14155551234"],
  "auth_mode": "digest",
  "auth_username": "aethex_outbound",
  "auth_password": "REDACTED",
  "transport": "udp",
  "media_encryption": "allow",
  "outbound_enabled": true,
  "set_as_tenant_default": true
}

201 Response

json

{
  "trunk": {
    "id": "11111111-1111-4111-8111-111111111111",
    "tenant_id": "tenant-uuid",
    "name": "Production carrier",
    "type": "outbound",
    "aethex_sip_trunk_id": "st_a1b2c3d4e5f6",
    "aethex_sip_dispatch_rule_id": null,
    "numbers": ["+14155551234"],
    "allowed_addresses": [],
    "auth_mode": "digest",
    "auth_username": "aethex_outbound",
    "outbound_address": "sip.carrier.example.com:5060",
    "transport": "udp",
    "media_encryption": "allow",
    "destination_allowlist": { "mode": "blocklist", "entries": [] },
    "max_concurrent_calls": 10,
    "calls_per_hour_limit": null,
    "status": "active",
    "suspended": false,
    "created_at": "2026-06-25T08:00:00Z"
  },
  "phone_numbers": [
    {
      "id": "pn-uuid",
      "phone_number": "+14155551234",
      "friendly_name": "Production carrier",
      "provider": "sip",
      "trunk_id": "11111111-1111-4111-8111-111111111111",
      "agent_id": null,
      "routing_rules": null,
      "outbound_enabled": true,
      "status": "active",
      "created_at": "2026-06-25T08:00:00Z"
    }
  ],
  "tenant_default_set": true
}

POST/sip-trunks

Lower-level trunk creation.

Create SIP Trunk

Creates an inbound or outbound SIP trunk without the one-shot phone-number registration performed by /sip-trunks/onboard. For outbound trunks, create phone-number records separately with POST /phone-numbers/sip/register. For inbound trunks, Aethex also creates a routing rule scoped to the trunk so matching inbound calls can reach the agent mapped to the called number.

Request body

namestringrequired
Display name for the trunk.
typestringrequired
inbound or outbound.
numbersstring[]optional
Numbers associated with the trunk, in E.164 (+14155557654) or as bare digits (14155557654). These are wire formats: an outbound trunk presents numbers[0] to the carrier verbatim as the caller ID, and an inbound trunk matches the called number exactly as the carrier sends it — list both spellings if unsure.
allowed_addressesstring[]optional
Carrier source IPs that authenticate inbound calls. Each entry must be a public IPv4 address or CIDR block between /24 and /32 (no private, catch-all, or reserved ranges).
auth_modestringoptional
digest (default), ip_acl, digest_plus_ip_acl, or register (register-style carriers; inbound trunks only).
outbound_authstringoptional
register trunks only: how the outbound companion trunk authenticates towards your carrier. proxy (the default) dials through the edge registrar, which answers the carrier's challenge — required when the carrier binds calls to the registered source IP. direct dials the carrier itself carrying the trunk's digest credentials, which is what carriers whose SBCs answer a same-dialog retry with 482 Request Merged need. Ignored for other auth modes.
outbound_from_userstringoptional
register trunks only: what outbound calls carry as the SIP From user. number (default) sends the caller ID number, which carriers expect. username sends the login name and carries the number in P-Asserted-Identity; a phone system such as 3CX needs it to match the call to its user. Set when the trunk is created; it cannot be changed later.
auth_usernamestringoptional
Digest username.
auth_passwordstringoptional
Digest password. Never returned. For register trunks it is stored encrypted for the registrar; for the others it lives only in the SIP server.
outbound_addressstringoptional
Required for outbound trunks; carrier host or host:port. For register trunks this is the carrier's registrar address.
realmstringoptional
Register trunks only: the carrier SIP domain (auth realm). Defaults to the outbound_address host.
register_expiresintegeroptional
Register trunks only: REGISTER refresh interval in seconds (default 120, range 30–3600).
transportstringoptional
udp, tcp, or tls.
media_encryptionstringoptional
allow, disable, or require.
outbound_dial_formatstringoptional
How outbound destinations are dialed to the carrier. e164 (default) keeps +E.164; digits strips the leading +; national renders the destination country's national dialing format (+15551234567 -> 05551234567, required by some national-only carriers). Use national only on single-calling-code trunks: a destination outside your trunk's own numbers' calling code is refused rather than dialed.
destination_allowlistobjectoptional
Outbound dial guard.
max_concurrent_callsintegeroptional
Per-trunk concurrency cap. Values above the platform ceiling are clamped.
calls_per_hour_limitintegeroptional
Optional hourly cap on outbound calls through this trunk. Leave it out for no hourly cap, the default. Values above the platform ceiling are clamped.

Errors

400Invalid outbound auth contract

Outbound auth fields are incomplete or contradictory.

Match auth_mode to the credentials your carrier expects.

409Number owned by another account

One of the numbers is already registered to a different account and cannot be attached to your trunk.

Use a number your account owns, or release it from the other account first.

422Validation error

The request does not match the closed schema.

Remove unknown fields and match the documented field constraints.

502SIP provisioning failed

The SIP edge rejected trunk or routing-rule creation.

Retry after checking SIP service health.

Request

json

{
  "name": "Carrier outbound",
  "type": "outbound",
  "numbers": ["+14155551234"],
  "auth_mode": "ip_acl",
  "outbound_address": "sip.carrier.example.com:5060",
  "transport": "udp",
  "media_encryption": "allow"
}

201 Response

json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "tenant_id": "tenant-uuid",
  "name": "Carrier outbound",
  "type": "outbound",
  "aethex_sip_trunk_id": "st_a1b2c3d4e5f6",
  "aethex_sip_dispatch_rule_id": null,
  "numbers": ["+14155551234"],
  "allowed_addresses": [],
  "auth_mode": "ip_acl",
  "auth_username": null,
  "outbound_address": "sip.carrier.example.com:5060",
  "transport": "udp",
  "media_encryption": "allow",
  "destination_allowlist": { "mode": "blocklist", "entries": [] },
  "max_concurrent_calls": 10,
  "calls_per_hour_limit": null,
  "status": "active",
    "suspended": false,
  "created_at": "2026-06-25T08:00:00Z"
}

GET/sip-trunks

List tenant-owned SIP trunks.

List SIP Trunks

Returns SIP trunks visible to the calling account, newest first. Disabled trunks are included; deleted trunks are not.

Path & Query

offsetintegeroptional
Number of results to skip. Default 0.
limitintegeroptional
Maximum results per page. Default 50, maximum 200.

Response

json

{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "tenant_id": "tenant-uuid",
      "name": "Carrier outbound",
      "type": "outbound",
      "aethex_sip_trunk_id": "st_a1b2c3d4e5f6",
      "aethex_sip_dispatch_rule_id": null,
      "numbers": ["+14155551234"],
      "allowed_addresses": [],
      "auth_mode": "ip_acl",
      "auth_username": null,
      "outbound_address": "sip.carrier.example.com:5060",
      "transport": "udp",
      "media_encryption": "allow",
      "destination_allowlist": { "mode": "blocklist", "entries": [] },
      "max_concurrent_calls": 10,
      "calls_per_hour_limit": null,
      "status": "active",
    "suspended": false,
      "created_at": "2026-06-25T08:00:00Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50
}

GET/sip-trunks/:trunk_id

Fetch one trunk by ID.

Get SIP Trunk

Returns a single non-deleted SIP trunk owned by the calling account. A disabled trunk is still returned; a deleted one is not.

Path & Query

trunk_idstringrequired
SIP trunk UUID.

Errors

404SIP trunk not found

No non-deleted tenant-owned trunk exists with that ID, or it belongs to another account.

Confirm the trunk_id with GET /sip-trunks for the same API key.

Response

json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "tenant_id": "tenant-uuid",
  "name": "Carrier outbound",
  "type": "outbound",
  "aethex_sip_trunk_id": "st_a1b2c3d4e5f6",
  "aethex_sip_dispatch_rule_id": null,
  "numbers": ["+14155551234"],
  "allowed_addresses": [],
  "auth_mode": "ip_acl",
  "auth_username": null,
  "outbound_address": "sip.carrier.example.com:5060",
  "transport": "udp",
  "media_encryption": "allow",
  "destination_allowlist": { "mode": "blocklist", "entries": [] },
  "max_concurrent_calls": 10,
  "calls_per_hour_limit": null,
  "status": "active",
    "suspended": false,
  "created_at": "2026-06-25T08:00:00Z"
}

PATCH/sip-trunks/:trunk_id

Update mutable trunk policy.

Update SIP Trunk

Updates Aethex-side policy fields. For inbound trunks, numbers and allowed_addresses are also synced to the SIP edge. For outbound trunks, changing numbers or allowed_addresses requires creating a replacement trunk because those fields cannot be updated in place on an outbound trunk. Changing auth_mode also requires a replacement trunk; omit it from PATCH requests.

Path & Query

trunk_idstringrequired
SIP trunk UUID.

Request body

namestringoptional
Updated display name.
numbersstring[]optional
Inbound trunks only; replaces the trunk number list.
allowed_addressesstring[]optional
Inbound trunks only; replaces the carrier source allowlist.
destination_allowlistobjectoptional
Outbound dial guard.
max_concurrent_callsintegeroptional
Per-trunk concurrency cap. Values above the platform ceiling are clamped.
calls_per_hour_limitintegeroptional
Hourly cap on outbound calls through this trunk. Send null to remove the cap. Values above the platform ceiling are clamped.
outbound_dial_formatstringoptional
How outbound destinations are dialed to the carrier. e164 keeps +E.164; digits strips the leading +; national renders the destination country's national dialing format (+15551234567 -> 05551234567, required by some national-only carriers). Use national only on single-calling-code trunks: a destination outside your trunk's own numbers' calling code is refused rather than dialed.
auth_modestringoptional
Change the trunk's auth contract: digest, ip_acl, digest_plus_ip_acl or register. Send the credentials the new mode needs in the same request.
statusstringoptional
active or disabled.

Errors

404SIP trunk not found

No non-deleted tenant-owned trunk exists with that ID, or it belongs to another account.

Confirm the trunk_id with GET /sip-trunks for the same API key.

422Replacement required

The request changes immutable outbound trunk fields or auth_mode.

Create a replacement trunk, migrate numbers/defaults, then delete the old trunk.

502SIP update failed

Inbound trunk field sync to the SIP edge failed.

Retry after checking SIP service health.

Request

json

{
  "destination_allowlist": {
    "mode": "allowlist",
    "entries": ["+1800", "+1415"]
  },
  "max_concurrent_calls": 25
}

200 Response

json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "tenant_id": "tenant-uuid",
  "name": "Carrier outbound",
  "type": "outbound",
  "aethex_sip_trunk_id": "st_a1b2c3d4e5f6",
  "aethex_sip_dispatch_rule_id": null,
  "numbers": ["+14155551234"],
  "allowed_addresses": [],
  "auth_mode": "ip_acl",
  "auth_username": null,
  "outbound_address": "sip.carrier.example.com:5060",
  "transport": "udp",
  "media_encryption": "allow",
  "destination_allowlist": { "mode": "allowlist", "entries": ["+1800", "+1415"] },
  "max_concurrent_calls": 25,
  "calls_per_hour_limit": null,
  "status": "active",
    "suspended": false,
  "created_at": "2026-06-25T08:00:00Z"
}

PATCH/sip-trunks/:trunk_id/set-default-outbound

Set the tenant fallback trunk.

Set Default Outbound Trunk

Marks an active outbound trunk as the tenant default. Aethex uses this trunk when an outbound call does not resolve through a registered from_number mapping.

Path & Query

trunk_idstringrequired
SIP trunk UUID.

Errors

404SIP trunk not found

No non-deleted tenant-owned trunk exists with that ID, or it belongs to another account.

Confirm the trunk_id with GET /sip-trunks for the same API key.

422Not an active outbound trunk

The trunk is inbound or not active.

Choose an active trunk with type: "outbound".

DELETE/sip-trunks/:trunk_id

Soft-delete a tenant trunk.

Delete SIP Trunk

Soft-deletes a tenant-owned trunk. The endpoint is idempotent and returns 204 even when the trunk was already deleted, never existed under this tenant, or belongs to another tenant.

Path & Query

trunk_idstringrequired
SIP trunk UUID.