> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Link SIP Trunk
> Link a BYOC number with SIP trunk credentials.
Changes state - verify before retry
**Recommended.** This endpoint is part of the public `/v1` API reference and is the supported path for new integrations. See the [migration guide](/docs/api-reference/v1/migrating-to-v1) for versioning guidance.
Links a bring-your-own phone number to SIP trunk credentials 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](/docs/api-reference/v1/phone-numbers/buy) 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 [Errors](/docs/api-reference/errors) for the standard error format.
## Related endpoints
* [SIP Trunking](/docs/calls/sip-trunking): configure BYOC routing in the dashboard.
* [Buy Phone Number](/docs/api-reference/v1/phone-numbers/buy): purchase a provider number instead.
* [Delete Phone Number](/docs/api-reference/v1/phone-numbers/delete): remove the SIP trunk number and routing credentials.
## OpenAPI
````yaml POST /v1/organization-phone-numbers/sip-trunks
openapi: 3.0.0
info:
title: DialNexa API
description: >-
Public REST API for the DialNexa voice AI platform. Versioned endpoints are
under /v1; unversioned endpoints are legacy and deprecated.
version: 1.0.0
servers:
- url: https://api.dialnexa.com
description: DialNexa production API
security:
- bearer: []
tags:
- name: API Keys
- name: Agent Functions
- name: Agents V1
- name: Agents2
- name: Batch Calls
- name: Batch Calls V1
- name: Call Logs
- name: Calls
- name: Calls V1
- name: Campaign Leads
- name: Campaigns
- name: External Webhooks
- name: Knowledge Base
- name: Knowledge Base V1
- name: LLMs
- name: LLMs V1
- name: Languages
- name: Languages V1
- name: Organization Phone Numbers
- name: Organization Phone Numbers V1
- name: Phone Number Pricing
- name: Phone Number Pricing V1
- name: Transcribers
- name: Transcribers V1
- name: User Webhooks
- name: User Webhooks V1
- name: V1
- name: Voices
- name: Voices V1
- name: Webcall
- name: Workflow Leads
- name: Workflow Leads V1
- name: Workflows
- name: Workflows V1
paths:
/v1/organization-phone-numbers/sip-trunks:
post:
tags:
- Organization Phone Numbers
- Organization Phone Numbers V1
- V1
summary: Link SIP Trunk
description: >-
Registers a bring-your-own number with SIP trunk credentials for
workspace routing.
operationId: OrganizationPhoneNumbersV1Controller_linkSipTrunkV1
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LinkSipTrunkDto'
examples:
request:
summary: Link a SIP trunk
value:
phoneNumber: '+14155552671'
terminationUri: 31974861099010243.zt.plivo.com:5060
nickname: US BYOC Line
responses:
'201':
description: SIP trunk linked successfully.
content:
application/json:
examples:
success:
summary: Successful response
value:
id: phn_abc123
phone_number: '+14155552671'
provider: plivo
status: active
country_code: US
nickname: US BYOC Line
'400':
description: Invalid input or missing configuration
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 400 Bad Request
value:
statusCode: 400
message: country_iso is required
error: Bad Request
'401':
description: Unauthorized - missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 401 Unauthorized
value:
statusCode: 401
message: API key is missing or invalid
error: Unauthorized
'403':
description: Forbidden - API key does not have access to this organization.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 403 Forbidden
value:
statusCode: 403
message: You do not have permission to access this resource
error: Forbidden
'409':
description: Phone number already registered
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 409 Conflict
value:
statusCode: 409
message: Phone number already registered
error: Conflict
'502':
description: Media server trunk registration failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 502 Bad Gateway
value:
statusCode: 502
message: Media server trunk registration failed
error: Bad Gateway
security:
- bearer: []
components:
schemas:
LinkSipTrunkDto:
type: object
properties:
phoneNumber:
type: string
example: '+14155552671'
description: E.164 phone number
terminationUri:
type: string
example: 31974861099010243.zt.plivo.com:5060
description: 'SIP termination host[:port]; must not use a sip: URI prefix'
sipTrunkUserName:
type: string
description: SIP authentication username
sipTrunkPassword:
type: string
description: SIP authentication password (stored encrypted)
nickname:
type: string
description: Display nickname for this trunk
required:
- phoneNumber
- terminationUri
ErrorResponse:
type: object
properties:
statusCode:
type: integer
example: 400
message:
oneOf:
- type: string
- type: array
items:
type: string
example: phone_number must be a valid E.164 phone number
error:
type: string
example: Bad Request
required:
- statusCode
- message
- error
securitySchemes:
bearer:
scheme: bearer
bearerFormat: JWT
type: http
````