# REST-API

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

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

Quelle: https://trunkbeam.com/docs/api

## Grundlagen

| | |
| --- | --- |
| Basis-URL | `https://app.trunkbeam.com/v1` |
| Anmeldung | `Authorization: Bearer tb_live_…` |
| Format | JSON, Zeitangaben in UTC nach ISO 8601 |
| Rufnummern | E.164, zum Beispiel `+493023125417` |

```bash
curl https://app.trunkbeam.com/v1/numbers \
  -H "Authorization: Bearer $TRUNKBEAM_API_KEY"
```

## Endpunkte

| Methode | Pfad | Zweck |
| --- | --- | --- |
| `GET` | `/numbers/available?area=030` | Freie Nummern suchen |
| `POST` | `/numbers` | Nummer kaufen |
| `GET` | `/numbers` | Deine 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-targets` | Erlaubte REFER-Ziele setzen |
| `GET` | `/verification` | Prüfstatus |
| `GET` | `/calls` | Anrufe mit Dauer und Kosten |
| `GET` | `/usage?month=2026-10` | Verbrauch eines Monats |
| `GET` | `/prices` | Aktuelle Preisliste |

## Nummer kaufen

```bash
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"}'
```

```json
{
  "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

```json
{ "error": { "code": "verification_required", "message": "Konto ist noch nicht freigegeben." } }
```

| HTTP | `code` | Bedeutung |
| --- | --- | --- |
| 400 | `invalid_request` | Eingabe fehlt oder ist falsch |
| 401 | `unauthorized` | Schlüssel fehlt oder ist ungültig |
| 403 | `verification_required` | Konto noch nicht freigegeben |
| 402 | `spend_limit_reached` | Ausgabelimit des Schlüssels erreicht |
| 409 | `number_unavailable` | Nummer ist inzwischen vergeben |
| 429 | `rate_limited` | Zu 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`.

```bash
trunkbeam webhooks add https://example.com/hooks/telefon --events call.started,call.ended,call.transferred
```

| Ereignis | Wann |
| --- | --- |
| `call.started` | Ein Anruf kommt an |
| `call.ended` | Ein Anruf ist beendet, mit Dauer und Kosten |
| `call.transferred` | Ein Anruf wurde per REFER durchgestellt |
| `verification.approved` | Konto oder Adresse freigegeben |
| `verification.rejected` | Abgelehnt, mit Grund |