# SIP trunks

## Endpoints

- `POST /platform/sip-trunks`: [Create SIP trunk](https://docs.polymorfa.com/api/sip-trunks/create-sip-trunk)
- `GET /platform/sip-trunks`: [List SIP trunks](https://docs.polymorfa.com/api/sip-trunks/list-sip-trunks)
- `GET /platform/sip/endpoint`: [Get SIP endpoint](https://docs.polymorfa.com/api/sip-trunks/get-sip-endpoint)
- `GET /platform/sip-trunks/{trunkId}`: [Get SIP trunk](https://docs.polymorfa.com/api/sip-trunks/get-sip-trunk)
- `PATCH /platform/sip-trunks/{trunkId}`: [Update SIP trunk](https://docs.polymorfa.com/api/sip-trunks/update-sip-trunk)
- `POST /platform/sip-trunks/{trunkId}/credentials`: [Rotate SIP trunk credentials](https://docs.polymorfa.com/api/sip-trunks/rotate-sip-trunk-credentials)
- `DELETE /platform/sip-trunks/{trunkId}`: [Delete SIP trunk](https://docs.polymorfa.com/api/sip-trunks/delete-sip-trunk)

## The SIP trunk object

### Attributes

- `id` (string (uuid), required, format uuid). Identifier for this resource.
- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
- `name` (string, required). Human-readable name for this resource.
- `enabled` (boolean, required). Disabled trunks receive no calls and cannot place calls.
- `direction` (string, required). Specifies direction for this management platform access sip trunk. Values: `inbound`, `outbound`, `both`.
- `outbound` (object, required, nullable). Specifies outbound for this management platform access sip trunk.
  - `targetUri` (string, required). SIP URI that receives incoming WhatsApp calls, for example `sip:pbx.example.com:5060`.
  - `transport` (string, required). Specifies transport for this management platform access sip trunk outbound. Values: `udp`, `tcp`, `tls`.
  - `authUsername` (string, required, nullable). Username sent when your PBX challenges a call, or null.
  - `hasPassword` (boolean, required). Whether a password is stored for `authUsername`. The password is never returned.
  - `fromUser` (string, required, nullable). Optional override for the From header user on calls sent to your PBX. Null uses the incoming caller identity: E.164 phone number when known, a non-phone LID address otherwise, or `whatsapp` when unknown.
- `inbound` (object, required, nullable). Specifies inbound for this management platform access sip trunk.
  - `username` (string, required). Digest username your PBX uses to authenticate calls it sends to Polymorfa.
  - `realm` (string, required). Digest realm for `username`.
  - `session` (string, required, nullable). Session that places the WhatsApp calls your PBX sends, or null when none is set. Calls from the PBX are refused until a session is set.
  - `allowedAddresses` (array of string, required). IP addresses or CIDR ranges your PBX sends calls from.
  - `allowedDestinations` (array of string, required). E.164 prefixes (for example `+1415`) your PBX may call. Empty allows every destination.
- `codecs` (array of string, required). Audio codecs offered to your PBX, in preference order. Values: `PCMU`, `PCMA`, `opus`.
- `maxConcurrentCalls` (integer, required). Most calls the trunk carries at once.
- `revision` (integer, required). Changes on every update. Send it as `expectedRevision` to avoid overwriting another change.
- `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
- `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
```json
{
  "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 https://api.polymorfa.com/platform/sip-trunks` (Platform API)

Required permission: `sessions:manage`

**Required scope:** `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

- `projectId` (string (uuid), format uuid). Project that owns the trunk. Required for team keys; project keys use their own project.
- `name` (string, required, length 1–100). Display name, 1 to 100 characters.
- `enabled` (boolean). Defaults to true.
- `direction` (string, required). Specifies direction for this management platform access create sip trunk request. Values: `inbound`, `outbound`, `both`.
- `outbound` (object). Specifies outbound for this management platform access create sip trunk request.
  - `targetUri` (string, required, length 5–512). `sip:` or `sips:` URI of your PBX: an optional user, a public host name or IP address, and an optional port. Parameters and passwords are not accepted.
  - `transport` (string, required). Specifies transport for this management platform access sip trunk outbound input. Values: `udp`, `tcp`, `tls`.
  - `authUsername` (string, nullable, length 1–128). Username for digest challenges from your PBX. Send null to remove the username and password.
  - `authPassword` (string, length 1–256). Password for `authUsername`. Write-only; omit it on update to keep the stored password.
  - `fromUser` (string, nullable, pattern ^[A-Za-z0-9+._-]{1,64}$). Optional override for the From header user on calls sent to your PBX. Omit or set null to use the incoming caller identity: E.164 phone number when known, a non-phone LID address otherwise, or `whatsapp` when unknown.
- `inbound` (object). Specifies inbound for this management platform access create sip trunk request.
  - `session` (string, nullable, length 1–64). Session in the same project that places calls from your PBX.
  - `allowedAddresses` (array of string, required, items 1–20, item length 1–64). 1 to 20 public IP addresses or CIDR ranges your PBX sends calls from. `/0` ranges are rejected.
  - `allowedDestinations` (array of string, max items 100). Up to 100 E.164 prefixes, such as `+1415`, your PBX may call. Omit or send an empty list to allow every destination.
- `codecs` (array of string, items 1–3). Distinct codecs in preference order. Defaults to `PCMU`, `PCMA`, `opus`. Values: `PCMU`, `PCMA`, `opus`.
- `maxConcurrentCalls` (integer, range 1–500). 1 to 500. Defaults to 30.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/sip-trunks" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "direction": "inbound"
}'
```

### Responses

#### 201

SIP trunk created. Store `inboundCredentials.password` now; it cannot be retrieved later.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `trunk` (object, required). Specifies trunk for this management platform access create sip trunk result.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `enabled` (boolean, required). Disabled trunks receive no calls and cannot place calls.
    - `direction` (string, required). Specifies direction for this management platform access sip trunk. Values: `inbound`, `outbound`, `both`.
    - `outbound` (object, required, nullable). Specifies outbound for this management platform access sip trunk.
      - `targetUri` (string, required). SIP URI that receives incoming WhatsApp calls, for example `sip:pbx.example.com:5060`.
      - `transport` (string, required). Specifies transport for this management platform access sip trunk outbound. Values: `udp`, `tcp`, `tls`.
      - `authUsername` (string, required, nullable). Username sent when your PBX challenges a call, or null.
      - `hasPassword` (boolean, required). Whether a password is stored for `authUsername`. The password is never returned.
      - `fromUser` (string, required, nullable). Optional override for the From header user on calls sent to your PBX. Null uses the incoming caller identity: E.164 phone number when known, a non-phone LID address otherwise, or `whatsapp` when unknown.
    - `inbound` (object, required, nullable). Specifies inbound for this management platform access sip trunk.
      - `username` (string, required). Digest username your PBX uses to authenticate calls it sends to Polymorfa.
      - `realm` (string, required). Digest realm for `username`.
      - `session` (string, required, nullable). Session that places the WhatsApp calls your PBX sends, or null when none is set. Calls from the PBX are refused until a session is set.
      - `allowedAddresses` (array of string, required). IP addresses or CIDR ranges your PBX sends calls from.
      - `allowedDestinations` (array of string, required). E.164 prefixes (for example `+1415`) your PBX may call. Empty allows every destination.
    - `codecs` (array of string, required). Audio codecs offered to your PBX, in preference order. Values: `PCMU`, `PCMA`, `opus`.
    - `maxConcurrentCalls` (integer, required). Most calls the trunk carries at once.
    - `revision` (integer, required). Changes on every update. Send it as `expectedRevision` to avoid overwriting another change.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
  - `inboundCredentials` (object). Specifies inbound credentials for this management platform access create sip trunk result.
    - `username` (string, required). WhatsApp username when one is available.
    - `password` (string, required). Shown only in this response. Store it in your PBX now; it cannot be retrieved later.
    - `realm` (string, required). Specifies realm for this management platform access sip trunk credential.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "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"
    }
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

`sip_trunk_limit`: the project already has 100 trunks.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "sip_trunk_limit",
    "message": "The project has reached its SIP trunk limit.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#sip-trunk-limit"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

#### 503

`sip_unavailable`: SIP trunks are not available right now.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "api_error",
    "code": "sip_unavailable",
    "message": "SIP trunks are not available.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#sip-unavailable"
}
```

## List SIP trunks

`GET https://api.polymorfa.com/platform/sip-trunks` (Platform API)

Required permission: `sessions:read`

**Required scope:** `sessions:read`

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

### Query parameters

- `projectId` (string (uuid), format uuid). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl "https://api.polymorfa.com/platform/sip-trunks" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

SIP trunks in creation order.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required). Human-readable name for this resource.
  - `enabled` (boolean, required). Disabled trunks receive no calls and cannot place calls.
  - `direction` (string, required). Specifies direction for this management platform access sip trunk. Values: `inbound`, `outbound`, `both`.
  - `outbound` (object, required, nullable). Specifies outbound for this management platform access sip trunk.
    - `targetUri` (string, required). SIP URI that receives incoming WhatsApp calls, for example `sip:pbx.example.com:5060`.
    - `transport` (string, required). Specifies transport for this management platform access sip trunk outbound. Values: `udp`, `tcp`, `tls`.
    - `authUsername` (string, required, nullable). Username sent when your PBX challenges a call, or null.
    - `hasPassword` (boolean, required). Whether a password is stored for `authUsername`. The password is never returned.
    - `fromUser` (string, required, nullable). Optional override for the From header user on calls sent to your PBX. Null uses the incoming caller identity: E.164 phone number when known, a non-phone LID address otherwise, or `whatsapp` when unknown.
  - `inbound` (object, required, nullable). Specifies inbound for this management platform access sip trunk.
    - `username` (string, required). Digest username your PBX uses to authenticate calls it sends to Polymorfa.
    - `realm` (string, required). Digest realm for `username`.
    - `session` (string, required, nullable). Session that places the WhatsApp calls your PBX sends, or null when none is set. Calls from the PBX are refused until a session is set.
    - `allowedAddresses` (array of string, required). IP addresses or CIDR ranges your PBX sends calls from.
    - `allowedDestinations` (array of string, required). E.164 prefixes (for example `+1415`) your PBX may call. Empty allows every destination.
  - `codecs` (array of string, required). Audio codecs offered to your PBX, in preference order. Values: `PCMU`, `PCMA`, `opus`.
  - `maxConcurrentCalls` (integer, required). Most calls the trunk carries at once.
  - `revision` (integer, required). Changes on every update. Send it as `expectedRevision` to avoid overwriting another change.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "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"
    }
  ]
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Get SIP endpoint

`GET https://api.polymorfa.com/platform/sip/endpoint` (Platform API)

Required permission: `sessions:read`

**Required scope:** `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.

### Request

```bash
curl "https://api.polymorfa.com/platform/sip/endpoint" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

The SIP address, or `sip_not_hosted`.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - One of:
    - `hosted` (object).
      - `status` (string, required). This environment accepts SIP at `host`. Values: `hosted`.
      - `host` (string, required, min length 1). Host name your PBX sends SIP to. Allow the addresses it resolves to for both SIP and RTP.
      - `transports` (array of object, required, min items 1). SIP transports and their ports on `host`.
        - `transport` (string, required). Specifies transport for this management platform access sip endpoint transport. Values: `udp`, `tcp`, `tls`.
        - `port` (integer, required). Port on `host` for this transport.
        - `srtp` (string, required). `required`: calls on this transport must use SRTP (SDES) media. `not_supported`: calls use plain RTP; offers with SRTP are refused. Values: `required`, `not_supported`.
      - `rtp` (object, required). Specifies rtp for this management platform access sip endpoint hosted.
        - `protocol` (string, required). Specifies protocol for this management platform access sip endpoint rtp. Values: `udp`.
        - `portMin` (integer, required). First port of the range.
        - `portMax` (integer, required). Last port of the range, inclusive.
    - `sip_not_hosted` (object).
      - `status` (string, required). This environment has no SIP address. Values: `sip_not_hosted`.
      - `host` (string, required, nullable). Always null: there is no address.
      - `transports` (array of object, required, max items 0). Always empty.
        - `transport` (string, required). Specifies transport for this management platform access sip endpoint transport. Values: `udp`, `tcp`, `tls`.
        - `port` (integer, required). Port on `host` for this transport.
        - `srtp` (string, required). `required`: calls on this transport must use SRTP (SDES) media. `not_supported`: calls use plain RTP; offers with SRTP are refused. Values: `required`, `not_supported`.
      - `rtp` (object, required, nullable). Always null.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "status": "hosted",
    "host": "string",
    "transports": [
      {
        "transport": "udp",
        "port": 0,
        "srtp": "required"
      }
    ],
    "rtp": {
      "protocol": "udp",
      "portMin": 0,
      "portMax": 0
    }
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Get SIP trunk

`GET https://api.polymorfa.com/platform/sip-trunks/{trunkId}` (Platform API)

Required permission: `sessions:read`

**Required scope:** `sessions:read`

### Path parameters

- `trunkId` (string (uuid), required, format uuid). Identifier for the trunk.

### Request

```bash
curl "https://api.polymorfa.com/platform/sip-trunks/<trunkId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

The SIP trunk. Passwords are never returned.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required). Human-readable name for this resource.
  - `enabled` (boolean, required). Disabled trunks receive no calls and cannot place calls.
  - `direction` (string, required). Specifies direction for this management platform access sip trunk. Values: `inbound`, `outbound`, `both`.
  - `outbound` (object, required, nullable). Specifies outbound for this management platform access sip trunk.
    - `targetUri` (string, required). SIP URI that receives incoming WhatsApp calls, for example `sip:pbx.example.com:5060`.
    - `transport` (string, required). Specifies transport for this management platform access sip trunk outbound. Values: `udp`, `tcp`, `tls`.
    - `authUsername` (string, required, nullable). Username sent when your PBX challenges a call, or null.
    - `hasPassword` (boolean, required). Whether a password is stored for `authUsername`. The password is never returned.
    - `fromUser` (string, required, nullable). Optional override for the From header user on calls sent to your PBX. Null uses the incoming caller identity: E.164 phone number when known, a non-phone LID address otherwise, or `whatsapp` when unknown.
  - `inbound` (object, required, nullable). Specifies inbound for this management platform access sip trunk.
    - `username` (string, required). Digest username your PBX uses to authenticate calls it sends to Polymorfa.
    - `realm` (string, required). Digest realm for `username`.
    - `session` (string, required, nullable). Session that places the WhatsApp calls your PBX sends, or null when none is set. Calls from the PBX are refused until a session is set.
    - `allowedAddresses` (array of string, required). IP addresses or CIDR ranges your PBX sends calls from.
    - `allowedDestinations` (array of string, required). E.164 prefixes (for example `+1415`) your PBX may call. Empty allows every destination.
  - `codecs` (array of string, required). Audio codecs offered to your PBX, in preference order. Values: `PCMU`, `PCMA`, `opus`.
  - `maxConcurrentCalls` (integer, required). Most calls the trunk carries at once.
  - `revision` (integer, required). Changes on every update. Send it as `expectedRevision` to avoid overwriting another change.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "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"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Update SIP trunk

`PATCH https://api.polymorfa.com/platform/sip-trunks/{trunkId}` (Platform API)

Required permission: `sessions:manage`

**Required scope:** `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

- `trunkId` (string (uuid), required, format uuid). Identifier for the trunk.

### Body

- `expectedRevision` (integer, min 1). Apply the change only if the trunk still has this `revision`.
- `name` (string, length 1–100). Display name, 1 to 100 characters.
- `enabled` (boolean). Whether this feature is enabled.
- `direction` (string). Specifies direction for this management platform access update sip trunk request. Values: `inbound`, `outbound`, `both`.
- `outbound` (object). Specifies outbound for this management platform access update sip trunk request.
  - `targetUri` (string, length 5–512). `sip:` or `sips:` URI of your PBX: an optional user, a public host name or IP address, and an optional port. Parameters and passwords are not accepted.
  - `transport` (string). Specifies transport for this management platform access sip trunk outbound patch. Values: `udp`, `tcp`, `tls`.
  - `authUsername` (string, nullable, length 1–128). Username for digest challenges from your PBX. Send null to remove the username and password.
  - `authPassword` (string, length 1–256). Password for `authUsername`. Write-only; omit it on update to keep the stored password.
  - `fromUser` (string, nullable, pattern ^[A-Za-z0-9+._-]{1,64}$). Optional override for the From header user on calls sent to your PBX. Omit or set null to use the incoming caller identity: E.164 phone number when known, a non-phone LID address otherwise, or `whatsapp` when unknown.
- `inbound` (object). Specifies inbound for this management platform access update sip trunk request.
  - `session` (string, nullable, length 1–64). Session in the same project that places calls from your PBX.
  - `allowedAddresses` (array of string, items 1–20, item length 1–64). 1 to 20 public IP addresses or CIDR ranges your PBX sends calls from. `/0` ranges are rejected.
  - `allowedDestinations` (array of string, max items 100). Up to 100 E.164 prefixes, such as `+1415`, your PBX may call. Omit or send an empty list to allow every destination.
- `codecs` (array of string, items 1–3). Distinct codecs in preference order. Defaults to `PCMU`, `PCMA`, `opus`. Values: `PCMU`, `PCMA`, `opus`.
- `maxConcurrentCalls` (integer, range 1–500). 1 to 500. Defaults to 30.

### Request

```bash
curl -X PATCH "https://api.polymorfa.com/platform/sip-trunks/<trunkId>" \
  -H "Authorization: Bearer <POLYMORFA_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
}'
```

### Responses

#### 200

The updated SIP trunk.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required). Human-readable name for this resource.
  - `enabled` (boolean, required). Disabled trunks receive no calls and cannot place calls.
  - `direction` (string, required). Specifies direction for this management platform access sip trunk. Values: `inbound`, `outbound`, `both`.
  - `outbound` (object, required, nullable). Specifies outbound for this management platform access sip trunk.
    - `targetUri` (string, required). SIP URI that receives incoming WhatsApp calls, for example `sip:pbx.example.com:5060`.
    - `transport` (string, required). Specifies transport for this management platform access sip trunk outbound. Values: `udp`, `tcp`, `tls`.
    - `authUsername` (string, required, nullable). Username sent when your PBX challenges a call, or null.
    - `hasPassword` (boolean, required). Whether a password is stored for `authUsername`. The password is never returned.
    - `fromUser` (string, required, nullable). Optional override for the From header user on calls sent to your PBX. Null uses the incoming caller identity: E.164 phone number when known, a non-phone LID address otherwise, or `whatsapp` when unknown.
  - `inbound` (object, required, nullable). Specifies inbound for this management platform access sip trunk.
    - `username` (string, required). Digest username your PBX uses to authenticate calls it sends to Polymorfa.
    - `realm` (string, required). Digest realm for `username`.
    - `session` (string, required, nullable). Session that places the WhatsApp calls your PBX sends, or null when none is set. Calls from the PBX are refused until a session is set.
    - `allowedAddresses` (array of string, required). IP addresses or CIDR ranges your PBX sends calls from.
    - `allowedDestinations` (array of string, required). E.164 prefixes (for example `+1415`) your PBX may call. Empty allows every destination.
  - `codecs` (array of string, required). Audio codecs offered to your PBX, in preference order. Values: `PCMU`, `PCMA`, `opus`.
  - `maxConcurrentCalls` (integer, required). Most calls the trunk carries at once.
  - `revision` (integer, required). Changes on every update. Send it as `expectedRevision` to avoid overwriting another change.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "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"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

`sip_trunk_revision_conflict`: the trunk changed after `expectedRevision`.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "sip_trunk_revision_conflict",
    "message": "The SIP trunk changed since it was read.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#sip-trunk-revision-conflict"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

#### 503

`sip_unavailable`: SIP trunks are not available right now.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "sip_unavailable",
    "message": "SIP trunks are not available.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#sip-unavailable"
}
```

## Rotate SIP trunk credentials

`POST https://api.polymorfa.com/platform/sip-trunks/{trunkId}/credentials` (Platform API)

Required permission: `sessions:manage`

**Required scope:** `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

- `trunkId` (string (uuid), required, format uuid). Identifier for the trunk.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/sip-trunks/<trunkId>/credentials" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

New credentials. The password is shown only in this response.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `username` (string, required). WhatsApp username when one is available.
  - `password` (string, required). Shown only in this response. Store it in your PBX now; it cannot be retrieved later.
  - `realm` (string, required). Specifies realm for this management platform access sip trunk credential.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "username": "string",
    "password": "string",
    "realm": "string"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

`state_conflict`: the trunk does not accept calls from a PBX.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

#### 503

`sip_unavailable`: SIP trunks are not available right now.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "sip_unavailable",
    "message": "SIP trunks are not available.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#sip-unavailable"
}
```

## Delete SIP trunk

`DELETE https://api.polymorfa.com/platform/sip-trunks/{trunkId}` (Platform API)

Required permission: `sessions:manage`

**Required scope:** `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

- `trunkId` (string (uuid), required, format uuid). Identifier for the trunk.

### Request

```bash
curl -X DELETE "https://api.polymorfa.com/platform/sip-trunks/<trunkId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

SIP trunk deleted.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `deleted` (boolean, required). Whether deleted. Values: `true`.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "deleted": true
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

`sip_trunk_in_use`: a session's call settings route incoming calls to the trunk.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "sip_trunk_in_use",
    "message": "A session still sends incoming calls to this SIP trunk.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#sip-trunk-in-use"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```
