Sinch Elastic Sip Trunking

---
name: sinch-elastic-sip-trunking
description: Provisions SIP trunks, endpoints, ACLs, credential lists, and phone numbers via the Sinch Elastic SIP Trunking REST API. Use when the user needs SIP connectivity, trunk provisioning, inbound/outbound PSTN voice routing, PBX integration, or SIP-to-PSTN bridging.
metadata:
  author: Sinch
  version: 1.0.2
  category: Voice
  tags: sip, trunking, est, pstn, voice, pbx, inbound, outbound
  uses:
    - sinch-authentication
    - sinch-sdks
---

# Sinch Elastic SIP Trunking API

## Overview

The Sinch Elastic SIP Trunking (EST) API lets you programmatically provision SIP trunks and route voice traffic between customer infrastructure and the PSTN. The core workflow is: create a trunk, authorize it (ACL or credentials), attach endpoints, assign phone numbers.

## Agent Instructions

Before generating code, ask the user these clarifying questions:

1. **Direction** — Do you need **inbound** (receive calls from PSTN), **outbound** (send calls to PSTN), or **both**?
2. **Auth method for the trunk** (if outbound or both) — **ACL-based** (static IPs) or **Credential-based** (digest auth / dynamic IPs)?
3. **Endpoint type** (if inbound or both) — **Static endpoint** (fixed IP/port) or **Registered endpoint** (SIP UA registers dynamically)?
4. **Language** — curl, Node.js SDK, Python, Java, .NET?

Only ask questions 2-3 when relevant to the user's direction. Wait for answers, then follow the matching workflow below.

## Decision Tree

```
User wants EST →
├─ Outbound only
│  ├─ Static IPs   → Workflow A (Trunk + ACL)
│  └─ Dynamic IPs  → Workflow E (Trunk + Credential List / Digest Auth)
├─ Inbound only
│  ├─ Static IP    → Workflow B (Trunk + Static Endpoint + Phone Number)
│  └─ Dynamic IP   → Workflow D (Trunk + Credential List + Registered Endpoint + Phone Number)
└─ Both           → Workflow C (Trunk + ACL/Creds + Endpoint + Phone Number)
```

## Critical Rules

1. **Dependency order matters.** Creating resources out of order causes failures.
   `Create Trunk` → `Create ACL/Credentials` → `Link to Trunk` → `Assign Phone Numbers` → `Create Endpoint`
2. **The Domain Trap.** Never send SIP INVITEs to `trunk.pstn.sinch.com`. ALWAYS use `{your-hostname}.pstn.sinch.com`.
3. **60-second propagation.** After linking ACLs or Credentials, wait 60 seconds before testing.
4. **Lower priority = higher preference.** Endpoint `priority: 1` is primary; `priority: 100` is failover.
5. **PUT replaces the entire object.** Omitted fields become `null`.

## Getting Started

### Authentication

See [sinch-authentication](../sinch-authentication/SKILL.md) for full auth setup. EST uses **OAuth2 client credentials** (production) or **Basic Auth** (testing only, rate-limited).

### SDK Installation

See [sinch-sdks](../sinch-sdks/SKILL.md) for installation and client initialization. Note: EST is only supported in the **Node.js SDK** — for Java, Python, and .NET, use direct HTTP calls.

### First API Call — Create a Trunk

```bash
curl -X POST \
  "https://elastic-trunking.api.sinch.com/v1/projects/$SINCH_PROJECT_ID/trunks" \
  -H "Authorization: Bearer $SINCH_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-trunk", "hostName": "my-trunk"}'
```

Response includes `sipTrunkId` and `hostName` — use `{hostName}.pstn.sinch.com` for all SIP routing.

For SDK examples, see the [Getting Started Guide](https://developers.sinch.com/docs/est/getting-started.md).
## Key Concepts

- **Trunk**: Connection between your infrastructure and Sinch. Has a `hostName` used in SIP routing.
- **SIP Endpoint**: Where inbound calls go. **Static** (fixed IP) or **Registered** (dynamic, requires Credential List).
- **ACL**: Authorizes outbound by source IP (CIDR notation, e.g. `203.0.113.10/32`).
- **Credential List**: Username/password pairs. Used for registered endpoint auth (inbound) or digest auth (outbound).
- **Phone Numbers**: E.164 DIDs assigned to a trunk for inbound routing.

## Workflows

### Workflow A: Outbound Only (ACL-based)

- [ ] 1. Create trunk
- [ ] 2. Create ACL with your source IPs
- [ ] 3. Link ACL to trunk
- [ ] 4. **Wait 60 seconds**
- [ ] 5. Verify: `GET /trunks/{trunkId}/accessControlLists` — confirm ACL appears

**API docs**: [Create trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/createsiptrunk.md) → [Create ACL](https://developers.sinch.com/docs/est/api-reference/est/access-control-list/createaccesscontrollist.md) → [Link ACL to trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/addaccesscontrollisttotrunk.md) → [List ACLs for trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/getaccesscontrollistsfortrunk.md)

### Workflow B: Inbound Only (Static Endpoint)

- [ ] 1. Create trunk
- [ ] 2. Create static SIP endpoint on trunk
- [ ] 3. Assign phone number(s) to trunk
- [ ] 4. Verify: `GET /trunks/{trunkId}/endpoints` and `GET /trunks/{trunkId}/phoneNumbers`

**API docs**: [Create trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/createsiptrunk.md) → [Create SIP endpoint](https://developers.sinch.com/docs/est/api-reference/est/sip-endpoints/createsipendpoint.md) → [Get phone numbers](https://developers.sinch.com/docs/est/api-reference/est/phone-numbers/getphonenumbers.md)

### Workflow C: Bidirectional (Both Inbound + Outbound)

- [ ] 1. Create trunk
- [ ] 2. Create ACL and/or Credential List → Link to trunk
- [ ] 3. Create SIP endpoint on trunk
- [ ] 4. Assign phone numbers to trunk
- [ ] 5. **Wait 60 seconds** before testing
- [ ] 6. Verify: `GET /trunks/{trunkId}/accessControlLists`, `GET /trunks/{trunkId}/endpoints`, `GET /trunks/{trunkId}/phoneNumbers`

**API docs**: [Create trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/createsiptrunk.md) → [Create ACL](https://developers.sinch.com/docs/est/api-reference/est/access-control-list/createaccesscontrollist.md) → [Link ACL to trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/addaccesscontrollisttotrunk.md) → [Create SIP endpoint](https://developers.sinch.com/docs/est/api-reference/est/sip-endpoints/createsipendpoint.md) → [Get phone numbers](https://developers.sinch.com/docs/est/api-reference/est/phone-numbers/getphonenumbers.md)

### Workflow D: Inbound with Registered Endpoint (Credential-based)

- [ ] 1. Create trunk
- [ ] 2. Create credential list with username/password
- [ ] 3. Create registered endpoint on trunk (references a username from the credential list)
- [ ] 4. Assign phone number(s) to trunk
- [ ] 5. Configure SIP UA to REGISTER to `{hostname}.pstn.sinch.com`
- [ ] 6. Verify: `GET /trunks/{trunkId}/endpoints` and `GET /trunks/{trunkId}/phoneNumbers`

**API docs**: [Create trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/createsiptrunk.md) → [Credential Lists](https://developers.sinch.com/docs/est/api-reference/est/credential-lists/getcredentiallistbyid.md) → [Create SIP endpoint](https://developers.sinch.com/docs/est/api-reference/est/sip-endpoints/createsipendpoint.md) → [Get phone numbers](https://developers.sinch.com/docs/est/api-reference/est/phone-numbers/getphonenumbers.md)

### Workflow E: Outbound Only (Digest Auth / Credential-based)

- [ ] 1. Create trunk
- [ ] 2. Create credential list with username/password
- [ ] 3. Link credential list to trunk
- [ ] 4. **Wait 60 seconds**
- [ ] 5. Verify: `GET /trunks/{trunkId}/credentialLists` — confirm credential list appears

**API docs**: [Create trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/createsiptrunk.md) → [Credential Lists](https://developers.sinch.com/docs/est/api-reference/est/credential-lists/getcredentiallistbyid.md) → [Add credential list to trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/addcredentiallisttotrunk.md) → [List credential lists for trunk](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/getcredentiallistsfortrunk.md)

## SIP Header Rules (Outbound)

| Header | Value | Notes |
|--------|-------|-------|
| `From` | `sip:+1E164@{your-hostname}.pstn.sinch.com` | **Must** be your trunk domain. Wrong domain → 403. Use E.164 format. |
| `To` | `sip:+1E164@{your-hostname}.pstn.sinch.com` | Destination in E.164 + your trunk domain. In most cases, same as Request-URI. |
| `Request-URI` | `sip:+1E164@{your-hostname}.pstn.sinch.com` | Destination in E.164 + your trunk domain. In most cases, same as To. |

## Gotchas and Best Practices

1. **CIDR notation** — ACL entries require CIDR (`/32` for single IP, `/24` for range).
2. **Country permissions** — US/Canada enabled by default. Other countries blocked; use `updateCountryPermissions`.
3. **Project ID ≠ App Key** — EST uses `projectId`, not the Voice Application Key.
4. **Default CPS limit** — 1 call per second. Exceeding it → 603. Contact Sinch to increase.
5. **Teardown order** — Delete in reverse: unassign phone numbers → delete endpoints → unlink ACLs/credentials → delete trunk. Deleting out of order can orphan resources.

## Troubleshooting

For SIP error codes and debugging runbooks, see [references/diagnostics.md](references/diagnostics.md).

Quick reference:
- **401** → Credential mismatch in Credential List
- **403** → IP not in ACL, or wrong `From` domain
- **404** → Using wrong SIP domain (must be `{hostname}.pstn.sinch.com`)
- **503** → No active endpoint on trunk

## References

- **SIP Trunks API**: [Trunks](https://developers.sinch.com/docs/est/api-reference/est/sip-trunks/createsiptrunk.md) · [Endpoints](https://developers.sinch.com/docs/est/api-reference/est/sip-endpoints/createsipendpoint.md) · [ACLs](https://developers.sinch.com/docs/est/api-reference/est/access-control-list/createaccesscontrollist.md) · [Credential Lists](https://developers.sinch.com/docs/est/api-reference/est/credential-lists/getcredentiallistbyid.md) · [Phone Numbers](https://developers.sinch.com/docs/est/api-reference/est/phone-numbers/getphonenumbers.md) · [Country Permissions](https://developers.sinch.com/docs/est/api-reference/est/country-permissions/getcountrypermissions.md)
- **Diagnostics & debugging runbooks**: [references/diagnostics.md](references/diagnostics.md)

## Links

- [EST Overview](https://developers.sinch.com/docs/est/getting-started.md)
- [Getting Started Guide](https://developers.sinch.com/docs/est/getting-started.md)
- [API Reference (Markdown)](https://developers.sinch.com/docs/est/api-reference/est.md)
- [OpenAPI Spec (YAML)](https://developers.sinch.com/_bundle/docs/est/api-reference/est.yaml?download)
- [Twilio BYOC Integration](https://developers.sinch.com/docs/est/integration-guides/twilio-byoc.md)
- [LLMs.txt (full docs index)](https://developers.sinch.com/llms.txt)