Skip to content
Shortcut: /, ⌘K or Ctrl+K

SIP trunks

View as Markdown

The SIP trunk object

Attributes

  • idstring (uuid)required

    Identifier for this resource.

  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • namestringrequired

    Human-readable name for this resource.

  • enabledbooleanrequired

    Disabled trunks receive no calls and cannot place calls.

  • directionstringrequired

    Specifies direction for this management platform access sip trunk.

    Allowed valuesinboundoutboundboth
  • outboundobjectrequirednullable

    Specifies outbound for this management platform access sip trunk.

    Show 5 child fields
  • inboundobjectrequirednullable

    Specifies inbound for this management platform access sip trunk.

    Show 5 child fields
  • codecsarray of stringrequired

    Audio codecs offered to your PBX, in preference order.

    Allowed valuesPCMUPCMAopus
  • maxConcurrentCallsintegerrequired

    Most calls the trunk carries at once.

  • revisionintegerrequired

    Changes on every update. Send it as expectedRevision to avoid overwriting another change.

  • createdAtstring (date-time)required

    ISO 8601 timestamp when this resource was created.

  • updatedAtstring (date-time)required

    ISO 8601 timestamp when this resource was last updated.

The SIP trunk object
{
  "id": "00000000-0000-4000-8000-000000000000",
  "projectId": "00000000-0000-4000-8000-000000000000",
  "name": "string",
  "enabled": true,
  "direction": "inbound",
  "outbound": {
    "targetUri": "string",
    "transport": "udp",
    "authUsername": "string",
    "hasPassword": true,
    "fromUser": "string"
  },
  "inbound": {
    "username": "string",
    "realm": "string",
    "session": "string",
    "allowedAddresses": [
      "string"
    ],
    "allowedDestinations": [
      "string"
    ]
  },
  "codecs": [
    "PCMU"
  ],
  "maxConcurrentCalls": 0,
  "revision": 0,
  "createdAt": "2026-09-22T12:00:00Z",
  "updatedAt": "2026-09-22T12:00:00Z"
}

Create SIP trunk

POST/platform/sip-trunksPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Connects a PBX or SIP trunk to WhatsApp calls. An outbound trunk receives the incoming WhatsApp calls of sessions whose call settings route to it. An inbound trunk lets your PBX place WhatsApp calls through a session. For trunks that accept calls from your PBX, the response contains the digest credentials once.

Body

  • projectIdstring (uuid)

    Project that owns the trunk. Required for team keys; project keys use their own project.

  • namestringrequiredlength1–100

    Display name, 1 to 100 characters.

  • enabledboolean

    Defaults to true.

  • directionstringrequired

    Specifies direction for this management platform access create sip trunk request.

    Allowed valuesinboundoutboundboth
  • outboundobject

    Specifies outbound for this management platform access create sip trunk request.

    Show 5 child fields
  • inboundobject

    Specifies inbound for this management platform access create sip trunk request.

    Show 3 child fields
  • codecsarray of stringitems1–3

    Distinct codecs in preference order. Defaults to PCMU, PCMA, opus.

    Allowed valuesPCMUPCMAopus
  • maxConcurrentCallsintegerrange1–500

    1 to 500. Defaults to 30.

Responses

  • 201SIP trunk created. Store `inboundCredentials.password` now; it cannot be retrieved later.
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 2 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 409`sip_trunk_limit`: the project already has 100 trunks.
  • 500Internal server error
  • 503`sip_unavailable`: SIP trunks are not available right now.
POST /platform/sip-trunkscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/sip-trunks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "direction": "inbound"
}'
Response
{
  "success": true,
  "data": {
    "trunk": {
      "id": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "enabled": true,
      "direction": "inbound",
      "outbound": {
        "targetUri": "string",
        "transport": "udp",
        "authUsername": "string",
        "hasPassword": true,
        "fromUser": "string"
      },
      "inbound": {
        "username": "string",
        "realm": "string",
        "session": "string",
        "allowedAddresses": [
          "string"
        ],
        "allowedDestinations": [
          "string"
        ]
      },
      "codecs": [
        "PCMU"
      ],
      "maxConcurrentCalls": 0,
      "revision": 0,
      "createdAt": "2026-09-22T12:00:00Z",
      "updatedAt": "2026-09-22T12:00:00Z"
    }
  }
}

List SIP trunks

GET/platform/sip-trunksPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:read

Lists the SIP trunks of a project. Passwords are never returned.

Query parameters

  • projectIdstring (uuid)

    Identifier of the Polymorfa project that owns this resource.

Responses

  • 200SIP trunks in creation order.
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 12 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
GET /platform/sip-trunkscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/sip-trunks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "enabled": true,
      "direction": "inbound",
      "outbound": {
        "targetUri": "string",
        "transport": "udp",
        "authUsername": "string",
        "hasPassword": true,
        "fromUser": "string"
      },
      "inbound": {
        "username": "string",
        "realm": "string",
        "session": "string",
        "allowedAddresses": [
          "string"
        ],
        "allowedDestinations": [
          "string"
        ]
      },
      "codecs": [
        "PCMU"
      ],
      "maxConcurrentCalls": 0,
      "revision": 0,
      "createdAt": "2026-09-22T12:00:00Z",
      "updatedAt": "2026-09-22T12:00:00Z"
    }
  ]
}

Get SIP endpoint

GET/platform/sip/endpointPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:read

Returns the host and ports your PBX sends SIP to, and the RTP port range to allow for call audio. When this environment does not host SIP, status is sip_not_hosted and no address is returned. The address is the same for every trunk of every project.

Responses

  • 200The SIP address, or `sip_not_hosted`.
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      One of
      • statusstringrequired

        This environment accepts SIP at host.

        Allowed valueshosted
      • hoststringrequiredmin length1

        Host name your PBX sends SIP to. Allow the addresses it resolves to for both SIP and RTP.

      • transportsarray of objectrequiredmin items1

        SIP transports and their ports on host.

        Show 3 child fields
      • rtpobjectrequired

        Specifies rtp for this management platform access sip endpoint hosted.

        Show 3 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
GET /platform/sip/endpointcURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/sip/endpoint" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "status": "hosted",
    "host": "string",
    "transports": [
      {
        "transport": "udp",
        "port": 0,
        "srtp": "required"
      }
    ],
    "rtp": {
      "protocol": "udp",
      "portMin": 0,
      "portMax": 0
    }
  }
}

Get SIP trunk

GET/platform/sip-trunks/{trunkId}Platform API
Base URL
https://api.polymorfa.com
Required permission
sessions:read

Path parameters

  • trunkIdstring (uuid)required

    Identifier for the trunk.

Responses

  • 200The SIP trunk. Passwords are never returned.
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 12 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
GET /platform/sip-trunks/{trunkId}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/sip-trunks/<trunkId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "enabled": true,
    "direction": "inbound",
    "outbound": {
      "targetUri": "string",
      "transport": "udp",
      "authUsername": "string",
      "hasPassword": true,
      "fromUser": "string"
    },
    "inbound": {
      "username": "string",
      "realm": "string",
      "session": "string",
      "allowedAddresses": [
        "string"
      ],
      "allowedDestinations": [
        "string"
      ]
    },
    "codecs": [
      "PCMU"
    ],
    "maxConcurrentCalls": 0,
    "revision": 0,
    "createdAt": "2026-09-22T12:00:00Z",
    "updatedAt": "2026-09-22T12:00:00Z"
  }
}

Update SIP trunk

PATCH/platform/sip-trunks/{trunkId}Platform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Changes the fields you send and keeps the others. Send expectedRevision to refuse the change with 409 sip_trunk_revision_conflict when the trunk changed since you read it. Changes apply to new calls within about a minute; calls in progress continue.

Path parameters

  • trunkIdstring (uuid)required

    Identifier for the trunk.

Body

  • expectedRevisionintegermin1

    Apply the change only if the trunk still has this revision.

  • namestringlength1–100

    Display name, 1 to 100 characters.

  • enabledboolean

    Whether this feature is enabled.

  • directionstring

    Specifies direction for this management platform access update sip trunk request.

    Allowed valuesinboundoutboundboth
  • outboundobject

    Specifies outbound for this management platform access update sip trunk request.

    Show 5 child fields
  • inboundobject

    Specifies inbound for this management platform access update sip trunk request.

    Show 3 child fields
  • codecsarray of stringitems1–3

    Distinct codecs in preference order. Defaults to PCMU, PCMA, opus.

    Allowed valuesPCMUPCMAopus
  • maxConcurrentCallsintegerrange1–500

    1 to 500. Defaults to 30.

Responses

  • 200The updated SIP trunk.
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 12 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 409`sip_trunk_revision_conflict`: the trunk changed after `expectedRevision`.
  • 500Internal server error
  • 503`sip_unavailable`: SIP trunks are not available right now.
PATCH /platform/sip-trunks/{trunkId}cURL
Not available with the Test key. Use a team key or project token.
curl -X PATCH "https://api.polymorfa.com/platform/sip-trunks/<trunkId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedRevision": 1,
  "name": "string",
  "enabled": true,
  "direction": "inbound",
  "outbound": {
    "targetUri": "string",
    "transport": "udp",
    "authUsername": "string",
    "authPassword": "string",
    "fromUser": "string"
  },
  "inbound": {
    "session": "string",
    "allowedAddresses": [
      "string"
    ],
    "allowedDestinations": [
      "string"
    ]
  },
  "codecs": [
    "PCMU"
  ],
  "maxConcurrentCalls": 1
}'
Response
{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "enabled": true,
    "direction": "inbound",
    "outbound": {
      "targetUri": "string",
      "transport": "udp",
      "authUsername": "string",
      "hasPassword": true,
      "fromUser": "string"
    },
    "inbound": {
      "username": "string",
      "realm": "string",
      "session": "string",
      "allowedAddresses": [
        "string"
      ],
      "allowedDestinations": [
        "string"
      ]
    },
    "codecs": [
      "PCMU"
    ],
    "maxConcurrentCalls": 0,
    "revision": 0,
    "createdAt": "2026-09-22T12:00:00Z",
    "updatedAt": "2026-09-22T12:00:00Z"
  }
}

Rotate SIP trunk credentials

POST/platform/sip-trunks/{trunkId}/credentialsPlatform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Replaces the password your PBX uses to place calls. The previous password stops working within about a minute. Returns 409 state_conflict for outbound trunks.

Path parameters

  • trunkIdstring (uuid)required

    Identifier for the trunk.

Responses

  • 200New credentials. The password is shown only in this response.
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 3 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 409`state_conflict`: the trunk does not accept calls from a PBX.
  • 500Internal server error
  • 503`sip_unavailable`: SIP trunks are not available right now.
POST /platform/sip-trunks/{trunkId}/credentialscURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/platform/sip-trunks/<trunkId>/credentials" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "username": "string",
    "password": "string",
    "realm": "string"
  }
}

Delete SIP trunk

DELETE/platform/sip-trunks/{trunkId}Platform API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Deletes the trunk and its credentials. Returns 409 sip_trunk_in_use while a session's call settings route incoming calls to it.

Path parameters

  • trunkIdstring (uuid)required

    Identifier for the trunk.

Responses

  • 200SIP trunk deleted.
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 2 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 409`sip_trunk_in_use`: a session's call settings route incoming calls to the trunk.
  • 500Internal server error
DELETE /platform/sip-trunks/{trunkId}cURL
Not available with the Test key. Use a team key or project token.
curl -X DELETE "https://api.polymorfa.com/platform/sip-trunks/<trunkId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "deleted": true
  }
}