sinch-elastic-sip-trunking

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 for full auth setup. EST uses OAuth2 client credentials (production) or Basic Auth (testing only, rate-limited).

SDK Installation

Language	Package	Install
Node.js	@sinch/sdk-core	npm install @sinch/sdk-core
Python	sinch	pip install sinch
Java	com.sinch.sdk:sinch-sdk-java	Maven dependency
.NET	Sinch	dotnet add package Sinch

First API Call — Create a Trunk

curl -X POST "https://elastic-trunking.api.sinch.com/v1/projects/YOUR_PROJECT_ID/trunks" \
  -H "Authorization: Bearer YOUR_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.

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 → Create ACL → Link ACL to trunk → List ACLs for trunk

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 → Create SIP endpoint → Get phone numbers

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 → Create ACL → Link ACL to trunk → Create SIP endpoint → Get phone numbers

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 → Credential Lists → Create SIP endpoint → Get phone numbers

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 → Credential Lists → Add credential list to trunk → List credential lists for trunk

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.

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 · Endpoints · ACLs · Credential Lists · Phone Numbers · Country Permissions
• Diagnostics & debugging runbooks: references/diagnostics.md

Links

• EST Overview
• Getting Started Guide
• API Reference (Markdown)
• OpenAPI Spec (YAML)
• Twilio BYOC Integration
• npm: @sinch/sdk-core