Link SIP Trunk
Link a BYOC number with SIP username and password or IP-based authentication.
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.
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.
Related endpoints
- SIP Trunking: configure BYOC routing in the dashboard.
- Buy Phone Number: purchase a provider number instead.
- Delete Phone Number: remove the SIP trunk number and routing credentials.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Phone number in E.164 form with the leading plus, for example +14155552671. It must be a valid number for its country.
32"+14155552671"
SIP termination host[:port]; must not use a sip: URI prefix
2048"31974861099010243.zt.plivo.com:5060"
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.
userpass, ip SIP authentication username. Required for authMode=userpass, forbidden for ip.
512SIP authentication password stored encrypted. Required for authMode=userpass and forbidden for authMode=ip.
512Display nickname for this trunk
255