> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a SIP Trunk

## Inbound authentication

A trunk may use **one** inbound authentication scheme, or none. The two schemes are mutually exclusive, and are set through the `inbound` object.

| Scheme | Configure with | How callers authenticate |
| - | - | - |
| SIP digest | `inbound.sip_auth = { username, password }` | PolyAI issues a standard SIP digest challenge to the first `INVITE`. |
| SIP token | `inbound.sip_token_auth = { token }` | The caller sends the token in an `X-PolyAI-SIP-Trunk-Token` header. |

See [Connecting to PolyAI Telephony](/api-reference/sip-trunking/connecting#authenticating-your-calls) for how callers present these on inbound calls.

## Default route

A trunk's **default route** is the agent that receives inbound calls whose dialed number has no extension on the trunk. Use it when many numbers on a trunk should reach the same agent, rather than creating an extension for each one.

* An extension always takes precedence: a number with its own extension goes to that extension's agent.
* Without a default route, a call to a number with no extension is rejected.
* The default route applies only to its own trunk.

Set it with the optional `inbound.default_route`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"inbound": {
  "default_route": { "agent": { "agent_id": "my-agent", "client_env": "live" } }
}
```

To change or remove it later, see [Update a SIP Trunk](/api-reference/sip-trunking/endpoint/update-a-sip-trunk#default-route).


## OpenAPI

````yaml POST /v1/accounts/{account_id}/telephony/sip-trunks
openapi: 3.0.3
info:
  title: PolyAI SIP Trunking API
  version: 1.0.0
  description: Management API for PolyAI SIP Trunks and their Extensions.
servers:
  - url: https://api.us.poly.ai
    description: US region
  - url: https://api.eu.poly.ai
    description: EU region
  - url: https://api.uk.poly.ai
    description: UK region
security:
  - polyApiKey: []
tags:
  - name: SIP Trunks
    description: >-
      A SIP Trunk is a virtual connection between your telephony platform and
      PolyAI. It authenticates callers, accepts inbound calls, and holds the
      list of Extensions that map a dialed number to a PolyAI agent.
  - name: SIP Trunk Extensions
    description: >-
      An Extension binds a dialed number on a trunk to a PolyAI agent. When a
      call reaches a trunk, the dialed user part is matched against that trunk's
      extensions to pick the agent.
  - name: Outbound Calls
    description: Place and query outbound calls that route over a SIP Trunk.
paths:
  /v1/accounts/{account_id}/telephony/sip-trunks:
    post:
      tags:
        - SIP Trunks
      summary: Create a SIP Trunk
      operationId: createSipTrunk
      parameters:
        - name: account_id
          in: path
          required: true
          description: ID of the account that owns the SIP Trunk.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSipTrunkRequest'
      responses:
        '201':
          description: The created SIP Trunk.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SipTrunk'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
components:
  schemas:
    CreateSipTrunkRequest:
      type: object
      additionalProperties: false
      description: The owning account is taken from the URL path, not the body.
      properties:
        sip_cidr:
          type: array
          description: The IPv4 CIDR blocks of your SIP servers.
          minItems: 1
          maxItems: 10
          items:
            type: string
            maxLength: 43
        rtp_cidr:
          type: array
          description: The IPv4 CIDR blocks of your RTP / media servers.
          minItems: 1
          maxItems: 10
          items:
            type: string
            maxLength: 43
        name:
          type: string
          description: A friendly name to help identify your SIP Trunk.
          minLength: 1
          maxLength: 255
          pattern: \S
        encrypted:
          type: boolean
          description: >-
            Whether this SIP Trunk will handle encrypted (true; SIP over
            TCP/TLS, media over UDP/SRTP) or unencrypted (false; SIP over UDP,
            media over UDP/RTP) calls. Defaults to true when omitted.
        inbound:
          $ref: '#/components/schemas/CreateSipTrunkInbound'
        outbound:
          $ref: '#/components/schemas/CreateSipTrunkOutbound'
      required:
        - name
        - sip_cidr
        - rtp_cidr
    SipTrunk:
      type: object
      description: A SIP Trunk.
      properties:
        id:
          type: string
          description: PolyAI-generated SIP Trunk ID, e.g. `tr-0123456789abcdefghijklmn`.
        account_id:
          type: string
          description: The PolyAI account that owns the SIP Trunk.
        sip_cidr:
          type: array
          description: The IPv4 CIDR blocks of your SIP servers.
          items:
            type: string
        rtp_cidr:
          type: array
          description: The IPv4 CIDR blocks of your RTP / media servers.
          items:
            type: string
        name:
          type: string
          description: A friendly name to help identify your SIP Trunk.
        encrypted:
          type: boolean
          description: >-
            Whether this SIP Trunk will handle encrypted (true; SIP over
            TCP/TLS, media over UDP/SRTP) or unencrypted (false; SIP over UDP,
            media over UDP/RTP) calls.
        inbound:
          $ref: '#/components/schemas/SipTrunkInbound'
        outbound:
          $ref: '#/components/schemas/SipTrunkOutbound'
        created_at:
          type: string
          format: date-time
          description: RFC 3339 timestamp of when the SIP Trunk was created.
        updated_at:
          type: string
          format: date-time
          description: RFC 3339 timestamp of when the SIP Trunk was last updated.
      required:
        - id
        - account_id
        - sip_cidr
        - rtp_cidr
        - name
        - encrypted
        - inbound
        - created_at
        - updated_at
    CreateSipTrunkInbound:
      type: object
      additionalProperties: false
      description: >-
        Configuration for inbound calls. sip_auth and sip_token_auth are
        mutually exclusive.
      properties:
        sip_auth:
          $ref: '#/components/schemas/CreateSipAuthConfig'
        sip_token_auth:
          $ref: '#/components/schemas/CreateTokenAuthConfig'
        default_route:
          $ref: '#/components/schemas/DefaultRouteRequest'
    CreateSipTrunkOutbound:
      type: object
      additionalProperties: false
      description: Configuration for outbound calls leaving PolyAI.
      properties:
        sip_addresses:
          type: array
          description: >-
            The SIP addresses of your SIP servers to send outbound calls to.
            Each must be a `sip:` or `sips:` URI, optionally with a port and a
            transport parameter, and must not include a user part.
          maxItems: 4
          example:
            - sip:my-sbc.example.com:5060
            - sip:my-sbc.example.com:5061;transport=tls
          items:
            type: string
            maxLength: 255
        default_caller_id:
          type: string
          description: Default caller ID to use on outbound calls.
          maxLength: 128
    SipTrunkInbound:
      type: object
      description: Configuration for inbound calls.
      properties:
        hostname:
          type: string
          description: Hostname that uniquely identifies this SIP Trunk.
        sip_auth:
          $ref: '#/components/schemas/SipAuth'
        sip_token_auth:
          $ref: '#/components/schemas/SipTokenAuth'
        default_route:
          $ref: '#/components/schemas/DefaultRoute'
      required:
        - hostname
        - sip_auth
        - sip_token_auth
    SipTrunkOutbound:
      type: object
      description: Configuration for outbound calls leaving PolyAI.
      properties:
        sip_addresses:
          type: array
          description: The SIP addresses of your SIP servers to send outbound calls to.
          example:
            - sip:my-sbc.example.com:5060
            - sip:my-sbc.example.com:5061;transport=tls
          items:
            type: string
        default_caller_id:
          type: string
          description: Default caller ID to use on outbound calls.
    Error:
      type: object
      description: Error response body.
      properties:
        success:
          type: boolean
        error:
          type: string
        message:
          type: string
      required:
        - success
        - error
        - message
    CreateSipAuthConfig:
      type: object
      additionalProperties: false
      description: >-
        SIP digest credentials. Mutually exclusive with sip_token_auth. SIP
        digest passwords are never returned on reads — keep your own record of
        anything you set.
      properties:
        username:
          type: string
          description: SIP digest auth username.
          maxLength: 255
        password:
          type: string
          description: SIP digest auth password.
          maxLength: 255
    CreateTokenAuthConfig:
      type: object
      additionalProperties: false
      description: >-
        SIP token credentials. Mutually exclusive with sip_auth. SIP tokens are
        never returned on reads — keep your own record of anything you set.
      properties:
        token:
          type: string
          description: SIP token.
          maxLength: 1024
    DefaultRouteRequest:
      type: object
      additionalProperties: false
      description: >-
        The agent to receive inbound calls whose dialed number has no extension
        on the trunk. An extension always takes precedence over the default
        route.
      properties:
        agent:
          $ref: '#/components/schemas/AgentRequest'
      required:
        - agent
    SipAuth:
      type: object
      description: SIP digest auth state.
      properties:
        enabled:
          type: boolean
          description: Whether SIP digest auth is enabled for this SIP Trunk.
        username:
          type: string
          description: SIP digest auth username. Present when enabled.
        realm:
          type: string
          description: SIP digest auth realm. Present when enabled.
      required:
        - enabled
    SipTokenAuth:
      type: object
      description: SIP token auth state.
      properties:
        enabled:
          type: boolean
          description: Whether SIP token auth is enabled for this SIP Trunk.
      required:
        - enabled
    DefaultRoute:
      type: object
      description: >-
        The agent that receives inbound calls whose dialed number has no
        extension on the trunk. Omitted when the trunk has no default route, in
        which case such calls are rejected.
      properties:
        agent:
          $ref: '#/components/schemas/Agent'
      required:
        - agent
    AgentRequest:
      type: object
      additionalProperties: false
      description: The PolyAI agent to bind an extension to.
      properties:
        agent_id:
          type: string
          description: PolyAI Agent / Project ID to route to.
          minLength: 1
          maxLength: 255
          pattern: \S
        client_env:
          type: string
          description: One of sandbox, pre-release, live.
          enum:
            - sandbox
            - pre-release
            - live
        variant_id:
          type: string
          description: Agent variant to route to.
          maxLength: 255
      required:
        - agent_id
        - client_env
    Agent:
      type: object
      description: The PolyAI agent an extension routes calls to.
      properties:
        agent_id:
          type: string
          description: PolyAI Agent / Project ID to route to.
        client_env:
          type: string
          description: One of sandbox, pre-release, live.
          enum:
            - sandbox
            - pre-release
            - live
        variant_id:
          type: string
          description: Agent variant to route to.
      required:
        - agent_id
        - client_env
        - variant_id
  responses:
    BadRequest:
      description: Validation error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid credential.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Caller is not a telephony admin on the account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Conflict with the current state of the resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    polyApiKey:
      type: apiKey
      in: header
      name: X-API-Key

````