Grundlagen
| Basis-URL | https://app.trunkbeam.com/v1 |
| Anmeldung | Authorization: Bearer tb_live_… |
| Format | JSON, Zeitangaben nach ISO 8601 |
| Rufnummern | E.164, zum Beispiel +497422944120 |
| Grenze | 120 Anfragen pro Minute und Schlüssel |
| Beschreibung | OpenAPI 3.1 unter https://app.trunkbeam.com/v1/openapi.json |
curl https://app.trunkbeam.com/v1/numbers \
-H "Authorization: Bearer $TRUNKBEAM_API_KEY"
Den Schlüssel legst du im Dashboard unter API, CLI & MCP an. Jeder Schlüssel hat die Rechte Lesen (read), Verwalten (manage) und Bestellen (order), siehe Konto und Prüfung.
Endpunkte
| Methode | Pfad | Zweck | Recht |
|---|---|---|---|
GET | /account | Konto, Tarif, Prüfstatus, Rechte des Schlüssels | read |
GET | /prices | Tarife und Preise | read |
GET | /verification | Stand der Prüfung und Standorte | read |
GET | /onkz?q=Schramberg | Ortsnetz zu Ort oder Vorwahl suchen | read |
GET | /numbers | Deine Nummern mit Ziel | read |
POST | /number-requests | Nummer bestellen (Ortsnetz am Standort oder 032) | order |
GET | /number-requests | Bestellungen und ihr Stand | read |
DELETE | /number-requests/{id} | Offene Bestellung zurückziehen | order |
POST | /numbers/{id}/connect | Nummer in einem Schritt mit ElevenLabs verbinden | manage |
PUT | /numbers/{id}/target | Nummer an eine SIP-Adresse leiten | manage |
PATCH | /numbers/{id} | Agent, Bezeichnung oder Ersatznummer ändern | manage |
POST | /numbers/{id}/release | Nummer kündigen | order |
GET | /connections | Agent-Anbindungen (SIP-Ziele) | read |
POST | /connections | Agent-Anbindung anlegen | manage |
PATCH | /connections/{id} | Agent-Anbindung ändern | manage |
DELETE | /connections/{id} | Agent-Anbindung löschen | manage |
GET | /agent-problems | Warum Anrufe den Agenten nicht erreicht haben | read |
GET | /credential | SIP-Zugang für ausgehende Anrufe (ohne Passwort) | read |
GET | /transfer-policy | Standard-Weiterleitung | read |
PUT | /transfer-policy | Standard-Weiterleitung setzen | manage |
GET | /transfer-policies | Standard und geltende Regel je Nummer | read |
GET, PUT, DELETE | /numbers/{id}/transfer-policy | Eigene Weiterleitung einer Nummer | read / manage |
GET | /hold-music | Wartemusik mit Beschreibung | read |
GET | /calls | Anrufprotokoll, neueste zuerst | read |
GET | /calls/export | Einzelverbindungen als CSV | read |
GET | /usage?month=2026-10 | Nutzung und Kosten eines Monats | read |
GET | /usage/daily | Anrufe und Minuten je Tag | read |
GET | /usage/export | Tagessummen eines Monats als CSV | read |
GET, PUT | /call-log-settings | Anrufprotokoll einstellen | read / manage |
Nur im Dashboard gehen Prüfung und Nachweise, das Anlegen des SIP-Zugangs, Tarifwechsel und API-Schlüssel.
Nummer bestellen
Kostenpflichtige Aktionen laufen in zwei Schritten, damit kein Skript und kein KI-Agent versehentlich kauft. Ohne confirm kommt nur ein Angebot zurück:
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": <Monatspreis netto>,
"message": "Ortsnetznummer im Ortsnetz 07422 für … € netto im Monat …"
}
Dieselbe Anfrage mit "confirm": true bestellt verbindlich:
{
"request": { "id": 41, "kind": "geographic", "status": "fulfilled", "numberE164": "+497422944121" },
"assigned": { "id": 12, "e164": "+497422944121", "status": "active" }
}
Ist gerade keine Nummer sofort verfügbar, ist assigned gleich null und die Bestellung bleibt offen, bis wir die Nummer zuteilen. Für eine 032-Nummer schickst du {"kind": "national032"}. Die Antworten sind hier gekürzt, die vollständigen Felder stehen in der OpenAPI-Beschreibung.
Fehler
{ "error": "Standort ist noch nicht geprüft", "code": "invalid" }
| HTTP | code | Bedeutung |
|---|---|---|
| 400 | invalid | Eingabe fehlt oder ist falsch |
| 401 | unauthorized | Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen |
| 403 | forbidden | Dem Schlüssel fehlt das Recht, oder die Funktion gibt es nur im Dashboard |
| 403 | org_pending | Vor der ersten Rufnummer muss die Prüfung abgeschlossen sein |
| 404 | not_found | Nummer, Anbindung oder Bestellung gibt es nicht |
| 409 | invalid | Passt gerade nicht, zum Beispiel Nummernlimit erreicht |
| 429 | forbidden | Mehr als 120 Anfragen pro Minute |