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:

Direction — Do you need inbound (receive calls from PSTN), outbound (send calls to PSTN), or both?
Auth method for the trunk (if outbound or both) — ACL-based (static IPs) or Credential-based (digest auth / dynamic IPs)?
Endpoint type (if inbound or both) — Static endpoint (fixed IP/port) or Registered endpoint (SIP UA registers dynamically)?
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

Dependency order matters. Creating resources out of order causes failures.
```
Create Trunk
```
→
```
Create ACL/Credentials
```
→
```
Link to Trunk
```
→
```
Assign Phone Numbers
```
→
```
Create Endpoint
```
The Domain Trap. Never send SIP INVITEs to
```
trunk.pstn.sinch.com
```
. ALWAYS use
```
{your-hostname}.pstn.sinch.com
```
.
60-second propagation. After linking ACLs or Credentials, wait 60 seconds before testing.
Lower priority = higher preference. Endpoint
```
priority: 1
```
is primary;
```
priority: 100
```
is failover.
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

bash

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

CIDR notation — ACL entries require CIDR (
```
/32
```
for single IP,
```
/24
```
for range).
Country permissions — US/Canada enabled by default. Other countries blocked; use
```
updateCountryPermissions
```
.
Project ID ≠ App Key — EST uses
```
projectId
```
, not the Voice Application Key.
Default CPS limit — 1 call per second. Exceeding it → 603. Contact Sinch to increase.
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

sinch-elastic-sip-trunking

NPX Install

Tags

SKILL.md Content