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

authMode is userpass (the default) or ip. With userpass, both sipTrunkUserName and sipTrunkPassword are required; with ip, neither may be sent. Either mistake returns 400. A number that is already registered in the workspace returns 409 Conflict, and a registration that DialNexa’s SIP routing rejects returns 502 Bad Gateway, and nothing is saved. Send phoneNumber in E.164 form with the leading plus (for example +14155552671); a number that is not valid for its country returns 400. Use a termination host and optional port without a sip: prefix. A 201 Created response carries the new number’s id, country_iso (the calling code, such as 1), phone_number (the national digits as a JSON number, such as 4155552671), termination_uri, sip_trunk_enabled, nickname, auth_mode and sip_username (null for ip); the password is never returned. 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

Phone number in E.164 form with the leading plus, for example +14155552671. It must be a valid number for its country.

Maximum string length: 32
Example:

"+14155552671"

terminationUri
string
required

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

Maximum string length: 2048
Example:

"31974861099010243.zt.plivo.com:5060"

authMode
enum<string>
default:userpass

How the provider authorizes this trunk. 'userpass' requires sipTrunkUserName and sipTrunkPassword; 'ip' requires both to be omitted and expects the provider to have whitelisted our signaling IP.

Available options:
userpass,
ip
sipTrunkUserName
string

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

Maximum string length: 512
sipTrunkPassword
string

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

Maximum string length: 512
nickname
string

Display nickname for this trunk

Maximum string length: 255

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
object
required
timestamp
string<date-time>
required