# REST API

Everything over HTTP, for your own dashboards, onboarding flows and automations.

> Early access: these interfaces are documented as drafts. Confirm commands, packages and endpoints with us before use.

Source: https://trunkbeam.com/en/docs/api

## Basics

| | |
| --- | --- |
| Base URL | `https://app.trunkbeam.com/v1` |
| Auth | `Authorization: Bearer tb_live_…` |
| Format | JSON, timestamps in UTC as ISO 8601 |
| Phone numbers | E.164, for example `+493023125417` |

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

## Endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/numbers/available?area=030` | Search available numbers |
| `POST` | `/numbers` | Buy a number |
| `GET` | `/numbers` | Your numbers |
| `GET` | `/numbers/{number}` | One number with routing |
| `PATCH` | `/numbers/{number}` | Change SIP target and fallbacks |
| `DELETE` | `/numbers/{number}` | Cancel at month end |
| `PUT` | `/numbers/{number}/transfer-targets` | Set allowed REFER targets |
| `GET` | `/verification` | Verification status |
| `GET` | `/calls` | Calls with duration and cost |
| `GET` | `/usage?month=2026-10` | Usage for a month |
| `GET` | `/prices` | Current price list |

## Buy a number

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

With `Idempotency-Key` a network error cannot make you buy two numbers by accident. Retrying with the same key returns the first response.

## Errors

```json
{ "error": { "code": "verification_required", "message": "Account is not approved yet." } }
```

| HTTP | `code` | Meaning |
| --- | --- | --- |
| 400 | `invalid_request` | Input missing or invalid |
| 401 | `unauthorized` | Key missing or invalid |
| 403 | `verification_required` | Account not approved yet |
| 402 | `spend_limit_reached` | Spend limit of the key reached |
| 409 | `number_unavailable` | Number was taken in the meantime |
| 429 | `rate_limited` | Too many requests, respect `Retry-After` |

## Webhooks

Register a URL for events. We send a `POST` with JSON and a signature in the `Signature` header.

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

| Event | When |
| --- | --- |
| `call.started` | A call comes in |
| `call.ended` | A call ended, with duration and cost |
| `call.transferred` | A call was transferred via REFER |
| `verification.approved` | Account or address approved |
| `verification.rejected` | Rejected, with reason |