Early Access: Die Schnittstellen sind als Entwurf dokumentiert. Befehle, Pakete und Endpunkte vor der Nutzung mit uns abstimmen.

REST-API

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

Als Markdown öffnen

Grundlagen

Basis-URLhttps://app.trunkbeam.com/v1
AnmeldungAuthorization: Bearer tb_live_…
FormatJSON, Zeitangaben in UTC nach ISO 8601
RufnummernE.164, zum Beispiel +493023125417
curl https://app.trunkbeam.com/v1/numbers \
  -H "Authorization: Bearer $TRUNKBEAM_API_KEY"

Endpunkte

MethodePfadZweck
GET/numbers/available?area=030Freie Nummern suchen
POST/numbersNummer kaufen
GET/numbersDeine Nummern
GET/numbers/{number}Eine Nummer mit Routing
PATCH/numbers/{number}SIP-Ziel und Fallbacks ändern
DELETE/numbers/{number}Zum Monatsende kündigen
PUT/numbers/{number}/transfer-targetsErlaubte REFER-Ziele setzen
GET/verificationPrüfstatus
GET/callsAnrufe mit Dauer und Kosten
GET/usage?month=2026-10Verbrauch eines Monats
GET/pricesAktuelle Preisliste

Nummer kaufen

curl https://app.trunkbeam.com/v1/numbers \
  -H "Authorization: Bearer $TRUNKBEAM_API_KEY" \
  -H "Idempotency-Key: 6f1c2b" \
  -H "Content-Type: application/json" \
  -d '{"area": "040", "sip": "sip:agent@voice.example"}'
{
  "number": "+494066969351",
  "area": "040",
  "status": "active",
  "sip": "sip:agent@voice.example"
}

Mit Idempotency-Key kaufst du bei einem Netzwerkfehler nicht aus Versehen zwei Nummern. Wiederholst du die Anfrage mit demselben Schlüssel, bekommst du die erste Antwort zurück.

Fehler

{ "error": { "code": "verification_required", "message": "Konto ist noch nicht freigegeben." } }
HTTPcodeBedeutung
400invalid_requestEingabe fehlt oder ist falsch
401unauthorizedSchlüssel fehlt oder ist ungültig
403verification_requiredKonto noch nicht freigegeben
402spend_limit_reachedAusgabelimit des Schlüssels erreicht
409number_unavailableNummer ist inzwischen vergeben
429rate_limitedZu viele Anfragen, Retry-After beachten

Webhooks

Für Ereignisse hinterlegst du eine URL. Wir senden ein POST mit JSON und einer Signatur im Header Signature.

trunkbeam webhooks add https://example.com/hooks/telefon --events call.started,call.ended,call.transferred
EreignisWann
call.startedEin Anruf kommt an
call.endedEin Anruf ist beendet, mit Dauer und Kosten
call.transferredEin Anruf wurde per REFER durchgestellt
verification.approvedKonto oder Adresse freigegeben
verification.rejectedAbgelehnt, mit Grund
Deinen Stack mit TrunkBeam verbinden