Basics
| Base URL | https://app.trunkbeam.com/v1 |
| Auth | Authorization: Bearer tb_live_… |
| Format | JSON, timestamps as ISO 8601 |
| Phone numbers | E.164, for example +497422944120 |
| Rate limit | 120 requests per minute per key |
| Specification | OpenAPI 3.1 at https://app.trunkbeam.com/v1/openapi.json |
curl https://app.trunkbeam.com/v1/numbers \
-H "Authorization: Bearer $TRUNKBEAM_API_KEY"
Create the key in the dashboard under API, CLI & MCP. Each key has the permissions Read (read), Manage (manage) and Order (order), see Account and verification.
Endpoints
| Method | Path | Purpose | Permission |
|---|---|---|---|
GET | /account | Account, plan, verification status, the key’s permissions | read |
GET | /prices | Plans and prices | read |
GET | /verification | Verification status and sites | read |
GET | /onkz?q=Schramberg | Search an area code by place or code | read |
GET | /numbers | Your numbers with target | read |
POST | /number-requests | Order a number (local at a site, or 032) | order |
GET | /number-requests | Orders and their status | read |
DELETE | /number-requests/{id} | Withdraw an open order | order |
POST | /numbers/{id}/connect | Connect a number to ElevenLabs in one step | manage |
PUT | /numbers/{id}/target | Route a number to a SIP address | manage |
PATCH | /numbers/{id} | Change agent, label or fallback number | manage |
POST | /numbers/{id}/release | Cancel a number | order |
GET | /connections | Agent connections (SIP targets) | read |
POST | /connections | Create an agent connection | manage |
PATCH | /connections/{id} | Change an agent connection | manage |
DELETE | /connections/{id} | Delete an agent connection | manage |
GET | /agent-problems | Why calls did not reach the agent | read |
GET | /credential | SIP access for outbound calls (without password) | read |
GET | /transfer-policy | Default transfer settings | read |
PUT | /transfer-policy | Set default transfer settings | manage |
GET | /transfer-policies | Default and effective rule per number | read |
GET, PUT, DELETE | /numbers/{id}/transfer-policy | A number’s own transfer settings | read / manage |
GET | /hold-music | Hold music with descriptions | read |
GET | /calls | Call log, newest first | read |
GET | /calls/export | Itemized calls as CSV | read |
GET | /usage?month=2026-10 | Usage and cost for a month | read |
GET | /usage/daily | Calls and minutes per day | read |
GET | /usage/export | Daily totals for a month as CSV | read |
GET, PUT | /call-log-settings | Call log settings | read / manage |
Only possible in the dashboard: verification and proofs, creating SIP access, plan changes and API keys.
Order a number
Paid actions take two steps, so no script and no AI agent buys by accident. Without confirm you only get a quote:
curl https://app.trunkbeam.com/v1/number-requests \
-H "Authorization: Bearer $TRUNKBEAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kind": "geographic", "siteId": 3}'
{
"confirmRequired": true,
"action": "order_number",
"monthlyEur": <monthly net price>,
"message": "Ortsnetznummer im Ortsnetz 07422 für … € netto im Monat …"
}
The same request with "confirm": true places a binding order:
{
"request": { "id": 41, "kind": "geographic", "status": "fulfilled", "numberE164": "+497422944121" },
"assigned": { "id": 12, "e164": "+497422944121", "status": "active" }
}
If no number is available right away, assigned is null and the order stays open until we assign the number. For an 032 number, send {"kind": "national032"}. The responses here are shortened; the OpenAPI specification lists all fields.
Errors
{ "error": "Standort ist noch nicht geprüft", "code": "invalid" }
| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid | Input missing or invalid |
| 401 | unauthorized | Key missing, invalid, expired or revoked |
| 403 | forbidden | The key lacks the permission, or the feature is dashboard-only |
| 403 | org_pending | Verification must be complete before the first number |
| 404 | not_found | Number, connection or order does not exist |
| 409 | invalid | Not possible right now, for example number limit reached |
| 429 | forbidden | More than 120 requests per minute |