Early Access: Dashboard, CLI, MCP-Server und REST-API sind nutzbar. Die Einrichtung für deinen Voice-Stack klären wir gern direkt mit dir.

REST-API

Alle Funktionen per HTTP, für eigene Oberflächen, Onboarding-Strecken und Automatisierungen.

Grundlagen

Basis-URLhttps://app.trunkbeam.com/v1
AnmeldungAuthorization: Bearer tb_live_…
FormatJSON, Zeitangaben nach ISO 8601
RufnummernE.164, zum Beispiel +497422944120
Grenze120 Anfragen pro Minute und Schlüssel
BeschreibungOpenAPI 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

MethodePfadZweckRecht
GET/accountKonto, Tarif, Prüfstatus, Rechte des Schlüsselsread
GET/pricesTarife und Preiseread
GET/verificationStand der Prüfung und Standorteread
GET/onkz?q=SchrambergOrtsnetz zu Ort oder Vorwahl suchenread
GET/numbersDeine Nummern mit Zielread
POST/number-requestsNummer bestellen (Ortsnetz am Standort oder 032)order
GET/number-requestsBestellungen und ihr Standread
DELETE/number-requests/{id}Offene Bestellung zurückziehenorder
POST/numbers/{id}/connectNummer in einem Schritt mit ElevenLabs verbindenmanage
PUT/numbers/{id}/targetNummer an eine SIP-Adresse leitenmanage
PATCH/numbers/{id}Agent, Bezeichnung oder Ersatznummer ändernmanage
POST/numbers/{id}/releaseNummer kündigenorder
GET/connectionsAgent-Anbindungen (SIP-Ziele)read
POST/connectionsAgent-Anbindung anlegenmanage
PATCH/connections/{id}Agent-Anbindung ändernmanage
DELETE/connections/{id}Agent-Anbindung löschenmanage
GET/agent-problemsWarum Anrufe den Agenten nicht erreicht habenread
GET/credentialSIP-Zugang für ausgehende Anrufe (ohne Passwort)read
GET/transfer-policyStandard-Weiterleitungread
PUT/transfer-policyStandard-Weiterleitung setzenmanage
GET/transfer-policiesStandard und geltende Regel je Nummerread
GET, PUT, DELETE/numbers/{id}/transfer-policyEigene Weiterleitung einer Nummerread / manage
GET/hold-musicWartemusik mit Beschreibungread
GET/callsAnrufprotokoll, neueste zuerstread
GET/calls/exportEinzelverbindungen als CSVread
GET/usage?month=2026-10Nutzung und Kosten eines Monatsread
GET/usage/dailyAnrufe und Minuten je Tagread
GET/usage/exportTagessummen eines Monats als CSVread
GET, PUT/call-log-settingsAnrufprotokoll einstellenread / 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" }
HTTPcodeBedeutung
400invalidEingabe fehlt oder ist falsch
401unauthorizedSchlüssel fehlt, ist ungültig, abgelaufen oder widerrufen
403forbiddenDem Schlüssel fehlt das Recht, oder die Funktion gibt es nur im Dashboard
403org_pendingVor der ersten Rufnummer muss die Prüfung abgeschlossen sein
404not_foundNummer, Anbindung oder Bestellung gibt es nicht
409invalidPasst gerade nicht, zum Beispiel Nummernlimit erreicht
429forbiddenMehr als 120 Anfragen pro Minute
Deinen Stack mit TrunkBeam verbinden