Connect a SIP trunk

A SIP trunk connects your own phone system to Orbit. This guide walks the full lifecycle: decide the direction, create the trunk, validate and test it, wire it to a DID, then keep an eye on registration and route quality. Everything here also exists in the dashboard under Settings → SIP trunks.

Step 1 — Pick the direction

Orbit supports two trunk directions:

Direction	Who originates calls	Use it for
Outgoing	Orbit dials out to your carrier	Keep your own PSTN carrier for outbound dialing — bring-your-own-carrier
Incoming	Your PBX dials into Orbit	Connect an office PBX (Asterisk, FreeSWITCH, 3CX) so phones on the PBX can use Orbit numbers, flows, agents, and queues

Incoming trunks authenticate your PBX on every call, by source IP, digest credentials, or both. Outgoing trunks carry your carrier’s SIP host and the register credentials the carrier issued you. Prerequisites

For outgoing trunks: the SIP host, port, and (if your carrier registered your account) username/password from your carrier. For US outbound traffic, Orbit applies STIR/SHAKEN attestation to the caller ID — see STIR/SHAKEN.
For incoming trunks: your PBX must be able to send SIP INVITEs to a public domain over UDP 5060, TCP 5060, or TLS 5061, and either present a stable source IP or answer digest challenges.
To place calls, own at least one DID — buy one under Numbers → Buy numbers or via the Numbers API.

Step 2 — Create an outgoing trunk

Outgoing trunks are the ones you use for dialing out through your own carrier.

Validate before you save

Probe first — the probe runs a real SIP REGISTER against the carrier host and returns the exact step that failed (DNS resolution, TCP/TLS connect, or the REGISTER itself) so you fix it before persisting anything:

curl -X POST https://api.orbit.devotel.io/api/v1/voice/sip-trunks/probe \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "host": "sip.carrier.example.com",
    "port": 5060,
    "transport": "udp",
    "register_username": "your-carrier-username",
    "register_password": "your-carrier-password"
  }'
# => { "data": { "reachable": true, "status": "registered", ... } }

A reachable: false response names the phase that failed and gives a sanitized operator message — the dashboard’s Add trunk dialog runs this same probe before it lets you save.

Create the trunk

curl -X POST https://api.orbit.devotel.io/api/v1/voice/sip-trunks \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Carrier A",
    "host": "sip.carrier.example.com",
    "port": 5060,
    "transport": "udp",
    "authentication": {
      "username": "your-carrier-username",
      "password": "your-carrier-password"
    },
    "maxConcurrent": 50
  }'
# => 201 { "data": { "id": "sip_abc123", ... } }

Credentials are encrypted at rest. Optional fields: codecs, maxConcurrent (per-trunk concurrent-call cap, 1–2000), failoverTrunkId (another trunk Orbit falls over to when this one drops registration), and enabled (default true). If you ran the probe first, pass its verdict as probe_status (registered | unregistered | unknown) so the row starts with an accurate badge instead of a guessed one — the dashboard does this automatically.

Step 3 — Create an incoming trunk and capture the secret

Incoming trunks let your PBX originate calls into Orbit.

curl -X POST https://api.orbit.devotel.io/api/v1/voice/sip-trunks/incoming \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HQ PBX",
    "authMode": "both",
    "allowedIps": ["203.0.113.10", "203.0.113.11"]
  }'
# => 201 { "data": { "id": "sip_def456", "digestUsername": "trunk_a1b2c3",
#                     "digestPassword": "ONE-TIME SECRET",
#                     "credentials_revealed_once": true, ... } }

authMode is one of:

digest — the PBX answers digest challenges with the issued username/password (handles SBCs with unstable egress IPs).
ip_allowlist — only INVITEs from allowedIps are accepted (no password exists; nothing can be rotated).
both — the PBX must match the allowlist and answer digest.

A few hard guards apply on the allowlist:

Each entry must be a valid IPv4/IPv6 address or CIDR, and at most 50 entries per trunk.
0.0.0.0/0 and ::/0 are rejected — a catch-all would disable the allowlist. Use authMode: "digest" if you don’t want IP filtering.
authMode: "ip_allowlist" or "both" requires at least one entry.

Capture the digest secret — it is shown exactly once

The create response contains the plaintext digestPassword once, with credentials_revealed_once: true. Every read of the trunk afterwards shows the password masked as ***. Save the username and password into your PBX immediately, or rotate later:

# 1. Rotate — the response carries a single-use reveal token, no plaintext
curl -X POST https://api.orbit.devotel.io/api/v1/voice/sip-trunks/sip_def456/credentials/rotate \
  -H "X-API-Key: dv_live_sk_..."
# => { "data": { "reveal_token": "...", "reveal_url": "...", "reveal_expires_at": "..." } }

# 2. Reveal once — read-and-consume; a second fetch returns 410 GONE
curl "https://api.orbit.devotel.io/api/v1/voice/sip-trunks/sip_def456/credentials/reveal?token=REVEAL_TOKEN" \
  -H "X-API-Key: dv_live_sk_..."
# => { "data": { "digestUsername": "trunk_a1b2c3", "digestPassword": "new-plaintext", ... } }

The reveal token is single-use and expires after five minutes — a replay returns 410 GONE, and rotation only applies to incoming trunks with digest auth. Calls already established under the old password keep running; the new password applies from the next INVITE — update your PBX before then to avoid a 401 burst.

Verify go-live readiness before routing traffic

Before you point calls at the trunk, run the readiness check. It is a configuration verdict, not a network probe — incoming trunks never send a REGISTER (your PBX initiates INVITEs toward Orbit, so “registered” does not apply the way it does to outgoing trunks). The check confirms every auth gate your authMode requires is satisfiable:

acl_configured — every allowedIps entry parses as a valid IP or CIDR (required when the auth mode is ip_allowlist or both).
credentials_present — digest username and password exist (required when the auth mode is digest or both).
auth_path_ready — all required gates pass together.

curl -X POST https://api.orbit.devotel.io/api/v1/voice/sip-trunks/sip_def456/onboarding/verify \
  -H "X-API-Key: dv_live_sk_..."
# Ready:
#   { "data": { "trunk_id": "sip_def456", "status": "verified",
#               "onboarded_at": "2026-08-25T12:00:00.000Z",
#               "checklist": ["acl_configured", "credentials_present",
#                             "auth_path_ready"],
#               "issues": [], "verified_at": "..." } }
# Blocked:
#   { "data": { "trunk_id": "sip_def456", "status": "not_ready",
#               "onboarded_at": null,
#               "checklist": ["acl_configured"],
#               "issues": ["Digest auth is enabled but credentials are
#                           missing — rotate credentials to regenerate them"],
#               "verified_at": "..." } }

On the first clean pass the trunk is stamped onboarded_at — the go-live marker the dashboard onboarding wizard closes on. A blocked run returns HTTP 200 with status: "not_ready" and the exact gates still failing in issues, and that blocker is written onto the trunk so the dashboard health surfaces show it until you re-verify. Two rules keep the stamp honest:

Every later trunk edit clears onboarded_at — changed the allowlist or credentials after onboarding? Re-verify; the stamp can never describe a stale configuration.
Reset restarts the wizard — POST /api/v1/voice/sip-trunks/{id}/onboarding/reset clears the stamp and checklist without touching your auth config, for when you want to re-run the flow after changing the ACL outside the wizard.

Both endpoints apply to incoming trunks only; on an outgoing trunk they return 422. Readiness past go-live (auth failures, rejected INVITEs) is covered by the registration polling and health snapshot in step 8 — verify only gates whether the configuration is complete enough to carry traffic.

Step 4 — TLS and SRTP posture

Your carrier-facing config and your softphone-facing config have two different security baselines:

Surface	Signalling	Media	Where you set it
Trunk (Orbit ↔ your carrier/PBX)	UDP/TCP 5060 or TLS 5061, per trunk `transport`	RTP through the media edge	`transport: "tls"` on the outgoing trunk body
SIP credential (your softphone ↔ Orbit)	TLS on port 5061 is the recommended transport (TCP/UDP 5060 as fallback)	SRTP is mandatory	The returned `sip_transport_recommended` and `sip_srtp` fields

Prefer tls on trunks when your carrier offers it — the create handler’s pre-save probe runs against the transport you pick, so a TLS path that cannot complete the handshake fails the probe and never becomes a broken saved row. On the credential side, every issued credential reports sip_srtp: "Mandatory" in its connection details; a softphone that advertises RTP-only media will not establish audio.

Step 5 — Point your PBX at Orbit

Configure your PBX with the digest digestUsername and password from the step above and the SIP edge host shown in Settings → SIP trunks in the dashboard. For authMode: "ip_allowlist" or "both", list every IP your SBC can originate from — a burst of unauthorized attempts shows up in the auth-failures ledger (step 8).

Step 5 — Wire routing to a DID

Calls arriving on an incoming trunk enter Orbit with a dialed number; the DID’s inbound route decides where the call lands. Set it per number:

curl -X PUT "https://api.orbit.devotel.io/api/v1/numbers/+14155550123/routing" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "webhook",
    "config": { "url": "https://your-app.example.com/voice/answer" }
  }'

Pick a route type per DID: webhook (your HTTPS URL returns call instructions), agent (an AI voice agent), sip_forward (send the call to a SIP URI or back through a trunk), queue, ivr, voicemail, softphone_user, or decline. See the inbound routing reference for the full set and config shapes. Two of those route types deserve a second look in a trunk setup:

sip_forward to an external AI voice agent — point the DID at a third-party AI provider’s SIP endpoint (callers.ai, Retell, Vapi, or a self-hosted PBX). Orbit terminates the carrier media and re-INVITEs your provider over TLS, so an inbound-trunk call can land in an AI agent without you running any SIP infrastructure. Full walkthrough: AI voice agents via sip_forward.
Inbound to registered softphones — when the trunk carries calls you want to ring desk phones or softphones directly, bind a SIP credential per device (/api/v1/sip-credentials): each issued credential registers against the SIP edge (sip_server in the response) and is routed on inbound DIDs of type softphone_register. Options on the credential include a per-device source-IP list (allowedIpCidrs), the outbound caller-id mode, a daily spend cap, and busy/no-answer/offline forward targets. That is the full cycle for a device: claim the credential, restrict its source IPs, and feed it inbound calls via routing.

For incoming trunks, optional routingRules on the trunk itself apply before the DID route — a countryBlocklist or destinationPrefixBlocklist blocks matching destinations, and callerIdRewrites swap the presented caller ID per destination country or prefix. Simulate the fixed evaluation order against any destination before going live:

curl "https://api.orbit.devotel.io/api/v1/voice/sip-trunks/sip_def456/routing-analysis?destination=%2B14155552671" \
  -H "X-API-Key: dv_live_sk_..."
# => { "data": { "trunkId": "sip_def456", "executionOrder": [...], "simulation": { ... } } }

executionOrder lists the routing controls in the order dispatch applies them and which ones you have configured; simulation (when you pass a destination) shows which control wins and which caller-ID rewrite applies. The simulation is read-only — it mirrors dispatch exactly.

Step 6 — Test the trunk

Validate configuration or re-check registration — POST /:id/test. On outgoing trunks this runs the same REGISTER probe as step 2 and records the verdict on the trunk (it also stamps lastRegistrationCheckAt, which the dispatch gate consults). On incoming trunks it validates the saved config (allowlist entries, digest presence) and returns status: "ok" | "misconfigured" with an issues list:

curl -X POST https://api.orbit.devotel.io/api/v1/voice/sip-trunks/sip_abc123/test \
  -H "X-API-Key: dv_live_sk_..."
# => { "data": { "status": "registered", "steps": [...], ... } }

The registration verdict is one of three values:

registered — the last check completed a REGISTER successfully.
unregistered — the check ran and the registrar rejected or timed out; read lastRegistrationError on the trunk for the recorded reason.
unknown — no check has run yet, or the verdict was acknowledged as uncertain at creation.

Place a real call through the trunk — POST /:id/test-call dials a destination over the trunk and records the billable result. The destination must be an E.164 number the org owns or an Orbit platform test number; emergency-shaped dials are rejected with EMERGENCY_CALLING_NOT_SUPPORTED:

curl -X POST https://api.orbit.devotel.io/api/v1/voice/sip-trunks/sip_abc123/test-call \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "to": "+14155550100" }'

Fax over the trunk (T.38)

Inbound fax shares the same inbound edge as voice: a fax sent to a DID arrives as a fax.received event and follows the DID’s fax routing to a webhook, email recipients, or the inbox. If you carry fax on the same trunk, keep the codec list on the trunk compatible — T.38 negotiation is driven by the carrier side, and a mismatched codec set can force unreliable audio fax. See Inbound fax routing for the receive-to-delivery lifecycle and the per-DID routing contract.

Step 7 — Emergency dialing

Orbit voice does not support emergency dialing (911/112/999/…), and every voice surface rejects emergency short codes. For US numbers, still register a dispatchable E911 address per DID — it records the location a regulator expects to find even though Orbit’s posture is block-and-disclaim:

curl -X PUT "https://api.orbit.devotel.io/api/v1/numbers/num_abc123/emergency-address" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "caller_name": "Acme Inc",
    "street_line_1": "1 Market St",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94105",
    "country": "US"
  }'

See Emergency address for field validation rules.

Step 8 — Monitor

Health snapshot

Ranked attention-first, with severity counts — the same numbers the SIP trunks page badges:

curl "https://api.orbit.devotel.io/api/v1/voice/sip-trunks/health" \
  -H "X-API-Key: dv_live_sk_..."
# => { "data": { "trunks": [ { "id": "sip_abc123", "status": "unregistered", ... } ], "counts": { ... } } }

Route quality

ASR/SDR-style scoring plus capacity bands per outgoing trunk over a 24h or 7d window — read this before blaming a carrier: a saturated concurrent-call cap shows up as blocked, not failed:

curl "https://api.orbit.devotel.io/api/v1/voice/sip-trunks/route-quality?window=24h" \
  -H "X-API-Key: dv_live_sk_..."

Usage per trunk

Seven days of daily totals by default, or a 24-hour attempt/accepted/ rejected breakdown with the top rejection reason on incoming trunks:

curl "https://api.orbit.devotel.io/api/v1/voice/sip-trunks/sip_def456/usage?window_hours=24" \
  -H "X-API-Key: dv_live_sk_..."

For incoming trunks, failed digest/allowlist attempts have their own seven-day ledger — the first place to look when calls stop arriving:

curl "https://api.orbit.devotel.io/api/v1/voice/sip-trunks/incoming/sip_def456/auth-failures" \
  -H "X-API-Key: dv_live_sk_..."

What the platform does on its own

Every enabled outgoing trunk is re-registered on a cadence of roughly five minutes: a real REGISTER with the stored credentials, with the verdict persisted back onto the trunk. If a check streak of transient register failures accumulates, the trunk is flagged rather than silently retried forever. Meanwhile a dispatch gate runs on every outbound call: a trunk whose cached registration verdict is anything other than registered (or whose verdict is stale) stops being offered new calls, and the call walks the trunk’s failover chain — the backup trunk you set via failoverTrunkId — landing on the Devotel default outbound path if no healthy failover exists. Your calls keep completing; the trunk row keeps the recorded error until you fix it.

Production checklist

When something breaks

Work through Troubleshooting: SIP trunk down or calls failing — the four most common recorded causes are DNS failing to resolve the host, a firewall blocking the SIP port, digest username/password mismatch, and codec/TLS mismatch on the REGISTER handshake. For a symptom-first checklist see also SIP trunk troubleshooting.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Connect a SIP trunk end to end: register, route, test, monitor

Connect a SIP trunk

Step 1 — Pick the direction

Step 2 — Create an outgoing trunk

Validate before you save

Create the trunk

Step 3 — Create an incoming trunk and capture the secret

Capture the digest secret — it is shown exactly once

Verify go-live readiness before routing traffic

Step 4 — TLS and SRTP posture

Step 5 — Point your PBX at Orbit

Step 5 — Wire routing to a DID

Step 6 — Test the trunk

Fax over the trunk (T.38)

Step 7 — Emergency dialing

Step 8 — Monitor

Health snapshot

Route quality

Usage per trunk

What the platform does on its own

Production checklist

When something breaks

​Connect a SIP trunk

​Step 1 — Pick the direction

​Step 2 — Create an outgoing trunk

​Validate before you save

​Create the trunk

​Step 3 — Create an incoming trunk and capture the secret

​Capture the digest secret — it is shown exactly once

​Verify go-live readiness before routing traffic

​Step 4 — TLS and SRTP posture

​Step 5 — Point your PBX at Orbit

​Step 5 — Wire routing to a DID

​Step 6 — Test the trunk

​Fax over the trunk (T.38)

​Step 7 — Emergency dialing

​Step 8 — Monitor

​Health snapshot

​Route quality

​Usage per trunk

​What the platform does on its own

​Production checklist

​When something breaks

Connect a SIP trunk

Step 1 — Pick the direction

Step 2 — Create an outgoing trunk

Validate before you save

Create the trunk

Step 3 — Create an incoming trunk and capture the secret

Capture the digest secret — it is shown exactly once

Verify go-live readiness before routing traffic

Step 4 — TLS and SRTP posture

Step 5 — Point your PBX at Orbit

Step 5 — Wire routing to a DID

Step 6 — Test the trunk

Fax over the trunk (T.38)

Step 7 — Emergency dialing

Step 8 — Monitor

Health snapshot

Route quality

Usage per trunk

What the platform does on its own

Production checklist

When something breaks