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

<span data-api-safety-label="changes-state"><Badge color="yellow" size="sm" shape="pill">Changes state - verify before retry</Badge></span>
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 `/v1` REST API for the DialNexa voice AI platform.
  version: 1.0.0
servers:
  - url: https://api.dialnexa.com
    description: DialNexa production API
security:
  - bearer: []
tags:
  - name: Agents
  - name: Batch Calls
  - name: Calls
  - name: Knowledge Base
  - name: Languages
  - name: LLMs
  - name: Phone Numbers
  - name: Transcribers
  - name: Webhooks
  - name: Voices
  - name: Workflows
  - name: Workflow Leads
paths:
  /v1/organization-phone-numbers/sip-trunks:
    post:
      tags:
        - Phone Numbers
      summary: Link SIP Trunk
      description: >-
        Registers a bring-your-own number with SIP trunk credentials for
        workspace routing.
      operationId: linkSipTrunk
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkSipTrunkRequest'
            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: SIP trunk registration failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 502 Bad Gateway
                  value:
                    statusCode: 502
                    message: SIP trunk registration failed
                    error: Bad Gateway
      security:
        - bearer: []
components:
  schemas:
    LinkSipTrunkRequest:
      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.
        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
      type: http

````