Skip to main content
POST
Link SIP Trunk
Changes state - verify before retry Links a bring-your-own phone number with username and password or IP-based SIP authentication and registers it for DialNexa routing. Use this path for SIP or BYOC numbers that were not purchased through DialNexa.

When to use this

  • Keeping an existing number: your business number already lives with another carrier and you want DialNexa agents to answer or dial from it.
  • Regulatory or cost constraints: your carrier relationship must stay in place, so purchasing through Buy Phone Number is not an option.
  • Migrating call infrastructure: route existing SIP trunks through DialNexa without renumbering.
Calls on SIP trunk routes skip the Telephony Config destination checks that apply to provider numbers, since routing is governed by your trunk. A 400 Bad Request means the trunk credentials or number failed validation; see API errors for the standard error format.

Authentication Modes

Use a termination host and optional port without a sip: prefix. After the request succeeds, place a controlled inbound and outbound test, then confirm routing, audio, recording, and Call History evidence. Do not retry after an uncertain timeout until List Phone Numbers confirms whether the number was created.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
phoneNumber
string
required

E.164 phone number

Example:

"+14155552671"

terminationUri
string
required

SIP termination host[:port]; must not use a sip: URI prefix

Example:

"31974861099010243.zt.plivo.com:5060"

authMode
enum<string>
default:userpass

How the SIP provider authorizes the trunk. userpass requires sipTrunkUserName and sipTrunkPassword. ip requires both credentials to be omitted and the provider to allowlist the DialNexa signaling IP.

Available options:
userpass,
ip
sipTrunkUserName
string

SIP authentication username. Required for authMode=userpass and forbidden for authMode=ip.

sipTrunkPassword
string

SIP authentication password stored encrypted. Required for authMode=userpass and forbidden for authMode=ip.

nickname
string

Display nickname for this trunk

Response

SIP trunk linked successfully.

success
enum<boolean>
required
Available options:
true
error
enum<boolean>
required
Available options:
false
statusCode
integer
required
Example:

201

message
string
required
Example:

"Success"

data
any
required
timestamp
string<date-time>
required