# TrunkBeam · Docs on one page

Every chapter, from quickstart to API and billing. Read the complete documentation, copy it or download it as Markdown.

> Early access: the dashboard, CLI, MCP server and REST API are available. We are happy to help you set them up for your voice stack.

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

## Quickstart

Four steps from zero to your first German phone number for your AI agent.

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

TrunkBeam gives you German phone numbers for voice agents. You manage them in the dashboard, from the terminal, through an MCP server or over a REST API. This page walks through the whole flow once.

### Requirements

- A company or registered business based in Germany. A local number needs a site inside that area code, so a Berlin (030) number needs a Berlin address.
- A voice stack that speaks SIP, for example ElevenLabs, OpenAI Realtime, Vapi, Retell AI, LiveKit or Asterisk.
- Only for the CLI and MCP server: Node.js 22 or newer.

### 1. Request access

TrunkBeam is in early access. [Request access](https://trunkbeam.com/en#waitlist), we discuss your setup with you and activate your account at `https://app.trunkbeam.com`. To protect it, you set up two-factor sign-in when you first log in. More in [Account and verification](https://trunkbeam.com/en/docs/account).

### 2. Get your company verified

Before your first number, we verify your company and your site once. You do this in the dashboard: company details, sites and one proof per site, for example a recent electricity or internet bill for exactly that address. We usually finish within one business day. After that you can buy as many numbers as you like without another review.

### 3. Order a number and connect it

In the dashboard under **Rufnummern** (numbers), you pick your site, order the number and then connect it to your agent on its detail page.

### 4. Enter it at your agent

For calls to arrive, you enter the number and the SIP details at your voice platform. What goes where is covered in the [platform guides](https://trunkbeam.com/en/docs/platforms) for ElevenLabs, LiveKit, Vapi, Retell, Ultravox and OpenAI. From then on, calls to the number go to your agent.

### Automated via MCP server or CLI

Everything in steps 3 and 4 also works without the dashboard. Create an API key in the dashboard under **API, CLI & MCP**. With the [MCP server](https://trunkbeam.com/en/docs/mcp), your AI assistant, for example Claude Code, Codex or Cursor, does the setup when you ask it to. With the [CLI](https://trunkbeam.com/en/docs/cli) it looks like this:

```bash
npx @trunkbeam/cli login                      # asks for the key without echoing it
trunkbeam sites                              # look up the site ID
trunkbeam numbers order --site 3             # shows the price and asks first
trunkbeam numbers connect 12 --elevenlabs    # connect the number to your agent
trunkbeam guide elevenlabs --number 12       # what to enter at ElevenLabs
```

### Next steps

- [Transfers and hold music](https://trunkbeam.com/en/docs/transfer) when a person should take over
- [SIP connection](https://trunkbeam.com/en/docs/sip), including outbound calls
- [Set up the MCP server](https://trunkbeam.com/en/docs/mcp) for Claude Code, Codex and Cursor

---

## Account and verification

Access, verification of your company and sites, API keys.

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

In Germany, phone numbers may only be assigned to real companies with a matching site. The Bundesnetzagentur (the German telecom regulator) requires this. That is why we verify once before your first number.

### Access

TrunkBeam is in early access. [Request access](https://trunkbeam.com/en#waitlist), then we discuss your setup and activate your account at `https://app.trunkbeam.com`. When you first log in, you confirm your email address and set up two-factor sign-in with an authenticator app. Without it you cannot enter the dashboard.

### Get your company verified

You start the verification in the dashboard. It has four steps:

1. **Company:** company details as in the commercial register or business registration.
2. **Sites:** your head office and, if needed, further branches where you want local numbers.
3. **Proofs:** one proof of site per site (see below). Without a commercial register entry, also your business registration with the current address, at most 3 months old. We fetch the register extract ourselves.
4. **Submit:** check and confirm your details.

A human reviews the details, usually within one business day. You can see the status in the dashboard at any time. After that you order numbers without another review.

#### Proof of site

An invoice or official notice addressed to your company, for a service at exactly this address:

| Proof | at most |
| --- | --- |
| Internet or landline bill with the connection address | 3 months old |
| Electricity, gas or water bill with the supply address | 3 months old |
| Annual statement for electricity, gas or water | 12 months old |
| Municipal waste fee or property tax notice | 12 months old |
| Landlord's service charge statement for these premises | 12 months old |
| Trade tax notice listing the business premises | 12 months old |

Mobile phone, online shop or supplier invoices are not enough. They only show a postal address, which a virtual office could have too.

#### If we reject

The dashboard shows the reason, for example "Nachweis älter als 3 Monate" (proof older than 3 months). Submit the missing proof and we review again.

### Which numbers are available

- **Local number** with the area code of a verified site, for example 07422 for Schramberg. Each further area code needs a verified site there.
- **032 number** without an area code. A registered office in Germany is enough.

You cannot pick a specific number. You order a number for a site and get one assigned. Each account can have up to 25 numbers; to get more, request an increase in the dashboard under **Rufnummern** (numbers).

### API keys

For the CLI, MCP server and REST API, create a key in the dashboard under **API, CLI & MCP**. It starts with `tb_live_` and is shown only once. Each key has permissions:

| Permission | allows |
| --- | --- |
| Read (`read`) | Retrieve numbers, agents, calls, usage and prices. Always included. |
| Manage (`manage`) | Change agents, number assignments and transfers |
| Order (`order`) | Order and cancel phone numbers, incurs costs |

You also choose a validity of 30, 90 or 365 days, or unlimited. You can revoke a key at any time. Give AI agents their own key, and the Order permission only if they really should buy numbers.

Only possible in the dashboard: verification and proofs, SIP access for outbound calls, plan changes and creating keys.

---

## Platform guides

What to enter at ElevenLabs, LiveKit, Vapi, Retell, Ultravox, OpenAI and other SIP targets so calls to your number reach your agent.

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

In TrunkBeam you only set **where calls should go** for each number: the address at your provider (SIP URI). Everything else is configured at the provider. This page shows where to find what on the common platforms.

The ElevenLabs guide is tested in production. The others follow the providers' documentation (as of September 2026). Field names there may change.

### How it works

| Direction | What happens | Where you set it |
|---|---|---|
| Inbound | TrunkBeam delivers calls to your number to the provider's SIP URI. | Dashboard → Rufnummern → number → **Verbindung** |
| Outbound and transfers | Your agent calls out or transfers through TrunkBeam. The provider signs in with your SIP access. | Dashboard → Konto → **SIP-Zugang** |

Outbound settings are the same for every provider:

| Field | Value |
|---|---|
| Server / Address | `sip.trunkbeam.com` |
| Port | `5061` |
| Transport | TLS |
| Username / Password | from Konto → SIP-Zugang (the password is shown only when generated) |

#### The SIP target on a number

- **Address at the provider**: number or identifier, server and transport (TLS, TCP or UDP). You do not need to enter a port: 5061 applies for TLS, otherwise 5060. Only for a non-standard port, append it to the server, for example `pbx.example.com:5080`. If you have a complete SIP URI such as `sip:+4930123456@sip.provider.example;transport=tls`, paste it into one of the upper fields; the dashboard splits it across the fields. The SIP URIs further down are meant the same way.
- **Encrypt audio (SRTP)**: on by default. The provider must allow encrypted audio, otherwise calls fail. The call log then shows "encryption mismatch (SIP 488)".
- **Username and password**: only turn this on if the provider requires credentials for inbound calls. Most providers recognise TrunkBeam by its IP address, which the dashboard shows next to the SIP target.

After saving, call the number. If the agent does not answer, the reason is listed under **Anrufe** (calls) in the dashboard.

#### Headers TrunkBeam sends

| SIP header | Content |
|---|---|
| `X-TrunkBeam-Called` | the TrunkBeam number that was called |
| `X-TrunkBeam-Transfer` | only when a call returns after a transfer: the reason (`no-answer`, `busy`, `unavailable`, `not-allowed`, `limit`) |
| `X-TrunkBeam-Transfer-Target` | only on return: the number that did not answer |

The agent transfers with **SIP REFER** to `tel:+49…` or `sip:+49…@sip.trunkbeam.com`. See [Blind transfer, availability check and hold music](https://trunkbeam.com/en/docs/transfer).

### ElevenLabs Agents

**SIP URI in TrunkBeam:** `sip:+49…@sip.rtc.elevenlabs.io;transport=tls` with your TrunkBeam number. Encrypt audio on, username and password as in ElevenLabs.

1. **Import the number**: ElevenLabs → Agents → Phone Numbers → Import number → From SIP trunk.
   - Label: `TrunkBeam`
   - Phone Number: your TrunkBeam number with +, exactly as in the SIP URI
2. **Inbound Configuration**
   - Media Encryption: **Allowed** or **Required**. With "Disabled", calls do not get through.
   - Authentication: **on**. Choose a username and password and enter the same values on the SIP target in TrunkBeam. Without authentication, ElevenLabs accepts calls from anyone.
   - Leave all other switches off. An IP allowlist (Allowed Addresses) and Remote Domains are not needed. If you want to set Remote Domains anyway: `sip.trunkbeam.com`.
3. **Outbound Configuration** for outbound calls and transfers
   - Address: `sip.trunkbeam.com`
   - Transport Type: TLS
   - Media Encryption: Required
   - Username / Password: from Konto → SIP-Zugang
4. **Assign the agent** to the imported number and call it.

**Transfers:** system tool "Transfer to number" with transfer type **SIP REFER**. Without REFER ("Conference"), ElevenLabs places a second call through TrunkBeam.

- The called number is available to the agent as `{{sip_trunkbeam_called}}`.
- When TrunkBeam calls the agent back after an unsuccessful transfer, the reason and number are in `{{sip_trunkbeam_transfer}}` and `{{sip_trunkbeam_transfer_target}}`. Handle them in the prompt, for example by taking a message, instead of greeting the caller again.
- ElevenLabs waits only about 10 to 15 seconds for a transfer result. With an availability check, the target therefore rings for at most 12 seconds.

ElevenLabs documentation: [SIP trunking](https://elevenlabs.io/docs/eleven-agents/phone-numbers/sip-trunking), [Transfer to number](https://elevenlabs.io/docs/agents-platform/customization/tools/system-tools/transfer-to-number)

### LiveKit Cloud

**SIP URI in TrunkBeam:** `sip:+49…@<subdomain>.eu.sip.livekit.cloud;transport=tls`. The address is under Settings → Project. Turn on username and password, with the same values as in the inbound trunk.

1. **Inbound trunk**: LiveKit Cloud → Telephony → SIP trunks → Create inbound trunk, or with the CLI:

   ```bash
   lk sip inbound create --name trunkbeam --numbers "+49…" \
     --auth-user "<username>" --auth-pass "<password>"
   ```

   Set `include_headers: SIP_X_HEADERS` to receive the TrunkBeam headers as attributes `sip.h.x-trunkbeam-called` and `sip.h.x-trunkbeam-transfer`.
2. **Dispatch rule**: Telephony → Dispatch rules, route calls on this trunk to your agent.
3. **Outbound trunk** for outbound calls and transfers:

   ```bash
   lk sip outbound create --name trunkbeam --address sip.trunkbeam.com --transport tls \
     --numbers "+49…" --auth-user "<SIP access username>" --auth-pass "<SIP access password>"
   ```

**Transfers:** `TransferSIPParticipant` sends a SIP REFER, with `transfer_to` as `tel:+49…` or `sip:…`.

LiveKit Cloud offers IP allowlisting only through support. Username and password are enough.

LiveKit documentation: [SIP trunk setup](https://docs.livekit.io/telephony/start/sip-trunk-setup/), [SIP API](https://docs.livekit.io/reference/telephony/sip-api/), [Transfer](https://docs.livekit.io/sip/transfer-cold/)

### Self-hosted LiveKit

Same as LiveKit Cloud, with the [livekit/sip](https://github.com/livekit/sip) service on your own server.

- **SIP URI in TrunkBeam:** `sip:+49…@sip.your-domain.example;transport=tls`. The certificate must match the host name.
- Configure the public IP and TLS in the SIP service. In the firewall, open SIP (5060/5061) and the RTP ports (default 10000–20000) for the TrunkBeam IP.
- Inbound trunk with username and password or with an IP allowlist (`--allowed-addresses <IP>/32`). With an IP allowlist, leave credentials off in TrunkBeam.
- Outbound trunk as for LiveKit Cloud.

### Vapi

**SIP URI in TrunkBeam:** `sip:+49…@<credentialId>.sip.eu.vapi.ai` for EU accounts, otherwise `<credentialId>.sip.vapi.ai`. No credentials, Vapi recognises TrunkBeam by its IP.

1. **Create a credential** via the API, EU accounts through `api.eu.vapi.ai`:

   ```json
   POST /credential
   {
     "provider": "byo-sip-trunk",
     "name": "TrunkBeam",
     "gateways": [{ "ip": "<TrunkBeam IP>", "port": 5061, "inboundEnabled": true,
                    "outboundEnabled": true, "outboundProtocol": "tls" }],
     "outboundAuthenticationPlan": { "authUsername": "<SIP access username>",
                                     "authPassword": "<SIP access password>" }
   }
   ```

2. **Create the phone number**:

   ```json
   POST /phone-number
   { "provider": "byo-phone-number", "number": "+49…", "credentialId": "<credentialId>",
     "numberE164CheckEnabled": true }
   ```

**Transfers:** tool `transferCall` with `destination { "type": "sip", "sipUri": "sip:+49…@sip.trunkbeam.com" }`. Vapi uses REFER by default.

Vapi documentation: [SIP trunk](https://docs.vapi.ai/advanced/sip/sip-trunk), [Networking](https://docs.vapi.ai/advanced/sip/sip-networking)

### Retell AI

**SIP URI in TrunkBeam:** `sip:+49…@sip.retellai.com;transport=tcp`. No credentials.

In Retell under Phone Numbers → Connect via SIP trunking:

| Field | Value |
|---|---|
| Phone Number | your TrunkBeam number in E.164 format |
| Termination URI | `sip.trunkbeam.com` |
| Transport | TLS |
| SIP Trunk User Name / Password | from Konto → SIP-Zugang |
| Inbound Agent | the agent you want |

To change these values later, delete the number in Retell and import it again.

**Transfers:** by default Retell transfers with a new call and stays on the line. With the "SIP REFER" option, Retell hands the call to TrunkBeam.

Retell documentation: [Custom telephony](https://docs.retellai.com/deploy/custom-telephony), [Transfer](https://docs.retellai.com/build/single-multi-prompt/transfer-call)

### Ultravox

**SIP URI in TrunkBeam:** `sip:agent_<agentId>@<your account's SIP domain>`. `GET /api/sip` returns the domain. No credentials.

1. **Allow TrunkBeam**: `PATCH /api/sip` with `{ "allowedCidrRanges": ["<TrunkBeam IP>/32"] }`.
2. **Outbound**: create a call with `medium` `sip.outgoing`:

   ```json
   { "sip": { "outgoing": { "to": "sip:+49…@sip.trunkbeam.com;transport=tls", "from": "+49…",
     "username": "<SIP access username>", "password": "<SIP access password>" } } }
   ```

**Transfers:** the built-in `coldTransfer` sends a SIP REFER to `sip:+49…@sip.trunkbeam.com`.

Ultravox documentation: [SIP](https://docs.ultravox.ai/telephony/sip), [Transfers](https://docs.ultravox.ai/telephony/call-transfers)

### OpenAI Realtime

Inbound only. **SIP URI in TrunkBeam:** `sip:proj_…@sip.api.openai.com;transport=tls`, in the EU `sip-eu.api.openai.com`. Encrypt audio on, OpenAI requires it. No credentials.

1. OpenAI → project → Webhooks: send the `realtime.call.incoming` event to your backend.
2. Your backend accepts each call with `POST /v1/realtime/calls/{call_id}/accept`, including model, instructions and voice. The TrunkBeam SIP headers are in the webhook under `data.sip_headers`.

**Transfers:** `POST /v1/realtime/calls/{call_id}/refer` with `target_uri` `tel:+49…`.

OpenAI documentation: [Realtime SIP](https://developers.openai.com/api/docs/guides/realtime-sip)

### Deepgram Voice Agent

Deepgram has no SIP interface. Build the agent with LiveKit Agents and the Deepgram plugins and connect it like [LiveKit](#livekit-cloud). Alternatively use Pipecat with the Daily or LiveKit transport.

Deepgram documentation: [Deepgram with LiveKit](https://developers.deepgram.com/docs/livekit-integration)

### Other SIP targets

For your own PBX, Asterisk, FreeSWITCH, Synthflow or any other SIP server:

- **SIP URI** with the target's host, port and transport, for example `sip:reception@pbx.example.com:5061;transport=tls`.
- Allow calls from TrunkBeam: username and password (digest) or allowlist the TrunkBeam IP.
- Codecs: G.722 and G.711 (PCMA/PCMU).
- Outbound: server `sip.trunkbeam.com`, port 5061, TLS, with your SIP access.

**Pipecat** has no SIP endpoint of its own. Dial-in through Daily requires the carrier to hand the live call over via API to an address that Daily issues for each call; TrunkBeam delivers to one fixed address per number. Two routes work: run Pipecat with the LiveKit transport and connect the number as described for LiveKit above, or use your own Asterisk or FreeSWITCH as the SIP target and pass the audio on to Pipecat.

Not yet supported: targets that can only use an IP allowlist instead of a password for outbound calls, for example Daily dial-out, and targets that require Opus.

---

## SIP connection

Route inbound calls to your agent over SIP and place outbound calls from your number.

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

### Inbound calls

Every number points to a SIP target, the agent connection. We send each inbound call there. You set the target in the dashboard under **Rufnummern** (numbers) or with the CLI:

```bash
trunkbeam numbers connect 12 --sip-uri "sip:agent@voice.example;transport=tls"
trunkbeam numbers connect 12 --elevenlabs     # ElevenLabs in one step
```

If your agent does not answer, for example during an outage at the provider, a regular German phone number can ring instead, such as your office. Set how long the agent has to pick up with `--after` (5 to 30 seconds, default 8):

```bash
trunkbeam numbers fallback 12 "07422 123456" --after 10
```

The SIP INVITE carries the caller's number in the `From` header and the dialed number in the `To` header and additionally in the `X-TrunkBeam-Called` header. So your agent can behave differently per number.

### Outbound calls

For calls from your agent to the outside and for transfers, set up an access in the dashboard under **SIP-Zugang** (SIP access). You get a username and password, which you enter at your voice platform together with these values:

```text
Host:       sip.trunkbeam.com
Port:       5061
Transport:  TLS
Username:   (from the dashboard)
Password:   (shown once)
```

Only numbers from your account are allowed as caller ID. We reject anything else, so nobody can place calls from numbers they do not own.

### Setup at your platform

Voice platforms usually call this "Bring your own SIP trunk", "Custom telephony" or "SIP trunk". The flow is similar everywhere:

1. Create a SIP trunk at the platform with host `sip.trunkbeam.com` and the credentials above.
2. Add your number at the platform and assign it to your agent.
3. Set the SIP address the platform gives you for inbound calls as the target with us.

`trunkbeam guide <provider> --number <id>` shows you these steps with your real values.

For the exact fields at ElevenLabs, LiveKit, Vapi, Retell, Ultravox and OpenAI, see the [platform guides](https://trunkbeam.com/en/docs/platforms).

### HD voice with G.722

TrunkBeam supports HD voice with the **G.722 wideband codec**, which carries a wider speech frequency range than traditional narrowband telephony.

HD quality requires your device, voice platform and the entire call path to support wideband audio. The systems on the SIP connection must negotiate a suitable codec. An HD-capable phone alone is not enough if another leg carries only narrowband audio, such as G.711. Converting that audio to G.722 later does not restore the lost frequencies.

This also applies to transfers: HD quality on the new connection depends on the destination device and call path.

Technical background: [ITU-T G.722](https://www.itu.int/rec/T-REC-G.722/en) and [SDP codec negotiation in RFC 3264](https://www.rfc-editor.org/rfc/rfc3264.html).

### Technical details

| | |
| --- | --- |
| Signaling | SIP over TLS (port 5061) |
| Media | SRTP and RTP |
| Codecs | G.722, G.711 A-law (PCMA), G.711 µ-law (PCMU) |
| DTMF | RFC 2833 (telephone-event) |
| Number format | E.164, for example `+493023125417` |

We will publish the IP ranges for firewall rules at launch.

---

## Transfers and hold music

Transfer calls from voice agents to people, directly or with an availability check. Return to the agent if nobody answers, with configurable hold music.

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

TrunkBeam supports two ways to transfer a call from a voice agent to a person. Both modes and configurable hold music are already available. Platform access is arranged through early access.

### Blind transfer: hand the call over directly

A blind transfer hands the call directly to the configured destination. The agent does not wait for an answer and leaves the conversation. This flow does not include a return to the agent.

It suits destinations that manage the next step themselves, such as a phone system with its own queue. A successful handover does not necessarily mean that a person has answered.

### Transfer with an availability check

Use an availability check when you want the agent to resume the call if nobody answers:

1. The agent announces the transfer.
2. The destination rings while the caller hears your configured hold music.
3. If someone answers, the caller is connected and the agent leaves the call.
4. If the destination is busy or nobody answers, the conversation with the agent resumes.

The agent can say, for example: “No one is available at reception right now. How else can I help you?” Your conversation logic determines whether to take a callback request or help the caller directly.

An availability check does not promise a separate consultation between the agent and the employee. That consultative flow is often called a “warm transfer” or “attended transfer”. The flow described here checks whether the destination answers and returns the caller to the agent when needed.

### Configure your hold music

Different hold music is available for the waiting phase. You configure what callers hear while the destination rings: the usual ringing tone or hold music. This applies to both modes – for a blind transfer also while fallback numbers are being called. The waiting phase ends when the destination answers or the caller returns to the agent.

This applies to the actual call flow. The example on the [homepage](https://trunkbeam.com/en#transfer) illustrates the behavior without placing calls or saving settings.

### SIP REFER and your voice stack

SIP REFER can initiate a transfer within a SIP network. Your voice stack must support the required signaling. Direct handover and return-to-agent behavior also depend on the integration and the selected flow.

You configure transfers in the dashboard under **Weiterleitung** (transfer), with the CLI using `trunkbeam transfer set`, through the MCP server or via the REST API, as a default for all numbers or per number. We agree the exact setup for your stack during onboarding. We do not claim that every listed platform supports every transfer mode.

Technical background: [IETF RFC 5589 on SIP Call Transfer](https://datatracker.ietf.org/doc/html/rfc5589).

### Destinations and call costs

Define which destinations your agent is allowed to use. Agree target numbers, SIP addresses and unavailable-destination handling before your first production call.

A transfer may create a connection to the destination in addition to the inbound connection. You receive the applicable rates and billing rules before you start. See [pricing and billing](https://trunkbeam.com/en/docs/pricing).

### Access and next steps

Connecting an existing voice agent? [Request early access](https://trunkbeam.com/en#waitlist) or read about [SIP connectivity](https://trunkbeam.com/en/docs/sip).

---

## MCP server

Manage numbers straight from Claude Code, Codex, Cursor or any other MCP client.

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

Through the MCP server, your AI assistant orders numbers, connects them to your agent and sets up transfers and hold music. You say in one sentence what you need, and the assistant calls the right tools.

The server runs locally via `npx @trunkbeam/mcp` and requires Node.js 22 or newer. Create the API key in the dashboard under **API, CLI & MCP** and pass it as the environment variable `TRUNKBEAM_API_KEY`.

### Tools

| Tool | What it does | Permission |
| --- | --- | --- |
| `trunkbeam_account` | Account, verification status, plan and the key's permissions | Read |
| `trunkbeam_prices` | Plans and prices | Read |
| `trunkbeam_list_sites` | Sites; only verified sites get local numbers | Read |
| `trunkbeam_search_area_code` | Search an area code by place or code | Read |
| `trunkbeam_list_numbers` | Your numbers with target | Read |
| `trunkbeam_order_number` | Order a local or 032 number, **asks first** | Order |
| `trunkbeam_list_number_requests` | Orders and their status | Read |
| `trunkbeam_release_number` | Cancel a number, **asks first** | Order |
| `trunkbeam_connect_number_elevenlabs` | Connect a number to ElevenLabs in one step | Manage |
| `trunkbeam_set_number_target` | Route a number to any SIP address | Manage |
| `trunkbeam_set_number_agent_fallback` | Fallback number if the agent is unreachable | Manage |
| `trunkbeam_list_connections` | Agent connections (SIP targets) | Read |
| `trunkbeam_create_connection` | Create an agent connection | Manage |
| `trunkbeam_delete_connection` | Delete an agent connection | Manage |
| `trunkbeam_provider_guide` | Setup guide per provider with your real values | Read |
| `trunkbeam_get_transfer_policy` | Show transfers to people | Read |
| `trunkbeam_set_transfer_policy` | Change transfers, as default or per number | Manage |
| `trunkbeam_reset_number_transfer_policy` | Delete a number's own transfer settings | Manage |
| `trunkbeam_list_hold_music` | Hold music with descriptions, so the assistant can pick a fitting track | Read |
| `trunkbeam_list_calls` | Recent calls | Read |
| `trunkbeam_usage` | Usage and cost for a month | Read |

Ordering and cancelling always take two steps. First the assistant fetches a quote with the price and shows it to you. Only after you agree does it confirm. The server rejects a confirmation without a prior quote.

### Claude Code

```bash
claude mcp add trunkbeam \
  -e TRUNKBEAM_API_KEY=tb_live_… \
  -- npx -y @trunkbeam/mcp
```

With `--scope user` the server is available in all projects. With `--scope project` it goes into the repo's `.mcp.json` and so to your whole team, but then the key does not belong in the file. Check with:

```bash
claude mcp list
```

### Codex

```bash
codex mcp add trunkbeam \
  --env TRUNKBEAM_API_KEY=tb_live_… \
  -- npx -y @trunkbeam/mcp
```

Or directly in `~/.codex/config.toml`:

```toml
[mcp_servers.trunkbeam]
command = "npx"
args = ["-y", "@trunkbeam/mcp"]

[mcp_servers.trunkbeam.env]
TRUNKBEAM_API_KEY = "tb_live_…"
```

Check with `codex mcp list`.

### Cursor, Claude Desktop and others

In `.cursor/mcp.json` in the project, `~/.cursor/mcp.json` for all projects, or for Claude Desktop in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "trunkbeam": {
      "command": "npx",
      "args": ["-y", "@trunkbeam/mcp"],
      "env": { "TRUNKBEAM_API_KEY": "tb_live_…" }
    }
  }
}
```

Windsurf and most other clients read the same `mcpServers` block.

### Keys for assistants

Give your assistant its own key with limited validity. For looking things up, the Read permission is enough. It needs Manage to change targets or transfers, and Order only if it really may buy numbers. You can revoke a key in the dashboard at any time.

### Example

> Get us a number for our Schramberg site and connect it to our ElevenLabs agent.

The assistant lists the sites, fetches the quote for a local number in area code 07422 and asks you about the price. After your OK, it orders, connects the number to ElevenLabs and shows you what to enter at ElevenLabs.

---

## CLI

Installation, login and every command of the command line tool.

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

### Installation

```bash
npm install -g @trunkbeam/cli
```

Or without installing, with `npx @trunkbeam/cli <command>`. Requires Node.js 22 or newer.

### Sign in

In the dashboard, create an API key under **API, CLI & MCP**. Then:

```bash
trunkbeam login
```

The CLI asks for the key without echoing it, checks it and stores it in `~/.config/trunkbeam/config.json`, readable only by your user. `trunkbeam logout` deletes it again.

On servers and in CI, set the environment variable instead:

```bash
export TRUNKBEAM_API_KEY=tb_live_…
```

Order of precedence: `--key` before `TRUNKBEAM_API_KEY` before the stored file.

### Global options

| Option | Effect |
| --- | --- |
| `--json` | Raw API data as JSON, for scripts |
| `--yes`, `-y` | Run paid actions without asking |
| `--key <key>` | Use a different API key for this call |
| `--help`, `-h` | Help, also per command: `trunkbeam numbers --help` |

### Commands

| Command | What it does |
| --- | --- |
| `login`, `logout` | Sign the CLI in or out |
| `account` | Account, verification status, plan and the key's permissions |
| `sites` | Sites with ID; only verified sites get local numbers |
| `onkz <place or area code>` | Search an area code, for example `onkz Schramberg` |
| `numbers ls` | Your numbers with ID, status and target |
| `numbers order --site <id>` | Order a local number at the site, shows the price first |
| `numbers order --032` | Order an 032 number without an area code |
| `numbers connect <id> --elevenlabs` | Connect a number to ElevenLabs in one step |
| `numbers connect <id> --sip-uri <uri>` | Route a number to any SIP address |
| `numbers fallback <id> <number>` | Fallback number if the agent is unreachable |
| `numbers release <id>` | Cancel a number, asks first |
| `requests ls`, `requests rm <id>` | View orders, withdraw open ones |
| `connections ls`, `connections add`, `connections rm <id>` | Manage agent connections (SIP targets) |
| `guide <provider> --number <id>` | Setup guide with your real values |
| `transfer get`, `transfer set`, `transfer reset` | Transfer to people, as default or per number |
| `hold-music` | Hold music with descriptions |
| `calls ls` | Recent calls with duration, status and cost |
| `usage --month <YYYY-MM>` | Usage and cost for a month |
| `prices` | Plans and prices |

Providers for `guide` and `connections add --provider`: `elevenlabs`, `livekit`, `livekit_self`, `vapi`, `retell`, `ultravox`, `openai`, `deepgram`, `sip`.

### In scripts

With `--json` and `--yes`, everything runs without prompts. Example: get a number at site 3 for a new customer and route it to their agent.

```bash
id=$(trunkbeam numbers order --site 3 --yes --json | jq -r '.assigned.id')
trunkbeam numbers connect "$id" --sip-uri "sip:customer-42@voice.example" --json
```

If no number is available right away, `assigned` is `null` and the order stays open. `trunkbeam requests ls` shows its status.

### Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | Error or cancelled |
| `2` | Invalid usage |

---

## REST API

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

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

### Basics

| | |
| --- | --- |
| Base URL | `https://app.trunkbeam.com/v1` |
| Auth | `Authorization: Bearer tb_live_…` |
| Format | JSON, timestamps as ISO 8601 |
| Phone numbers | E.164, for example `+497422944120` |
| Rate limit | 120 requests per minute per key |
| Specification | OpenAPI 3.1 at `https://app.trunkbeam.com/v1/openapi.json` |

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

Create the key in the dashboard under **API, CLI & MCP**. Each key has the permissions Read (`read`), Manage (`manage`) and Order (`order`), see [Account and verification](https://trunkbeam.com/en/docs/account#api-keys).

### Endpoints

| Method | Path | Purpose | Permission |
| --- | --- | --- | --- |
| `GET` | `/account` | Account, plan, verification status, the key's permissions | read |
| `GET` | `/prices` | Plans and prices | read |
| `GET` | `/verification` | Verification status and sites | read |
| `GET` | `/onkz?q=Schramberg` | Search an area code by place or code | read |
| `GET` | `/numbers` | Your numbers with target | read |
| `POST` | `/number-requests` | Order a number (local at a site, or 032) | order |
| `GET` | `/number-requests` | Orders and their status | read |
| `DELETE` | `/number-requests/{id}` | Withdraw an open order | order |
| `POST` | `/numbers/{id}/connect` | Connect a number to ElevenLabs in one step | manage |
| `PUT` | `/numbers/{id}/target` | Route a number to a SIP address | manage |
| `PATCH` | `/numbers/{id}` | Change agent, label or fallback number | manage |
| `POST` | `/numbers/{id}/release` | Cancel a number | order |
| `GET` | `/connections` | Agent connections (SIP targets) | read |
| `POST` | `/connections` | Create an agent connection | manage |
| `PATCH` | `/connections/{id}` | Change an agent connection | manage |
| `DELETE` | `/connections/{id}` | Delete an agent connection | manage |
| `GET` | `/agent-problems` | Why calls did not reach the agent | read |
| `GET` | `/credential` | SIP access for outbound calls (without password) | read |
| `GET` | `/transfer-policy` | Default transfer settings | read |
| `PUT` | `/transfer-policy` | Set default transfer settings | manage |
| `GET` | `/transfer-policies` | Default and effective rule per number | read |
| `GET`, `PUT`, `DELETE` | `/numbers/{id}/transfer-policy` | A number's own transfer settings | read / manage |
| `GET` | `/hold-music` | Hold music with descriptions | read |
| `GET` | `/calls` | Call log, newest first | read |
| `GET` | `/calls/export` | Itemized calls as CSV | read |
| `GET` | `/usage?month=2026-10` | Usage and cost for a month | read |
| `GET` | `/usage/daily` | Calls and minutes per day | read |
| `GET` | `/usage/export` | Daily totals for a month as CSV | read |
| `GET`, `PUT` | `/call-log-settings` | Call log settings | read / manage |

Only possible in the dashboard: verification and proofs, creating SIP access, plan changes and API keys.

### Order a number

Paid actions take two steps, so no script and no AI agent buys by accident. Without `confirm` you only get a quote:

```bash
curl https://app.trunkbeam.com/v1/number-requests \
  -H "Authorization: Bearer $TRUNKBEAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "geographic", "siteId": 3}'
```

```text
{
  "confirmRequired": true,
  "action": "order_number",
  "monthlyEur": <monthly net price>,
  "message": "Ortsnetznummer im Ortsnetz 07422 für … € netto im Monat …"
}
```

The same request with `"confirm": true` places a binding order:

```json
{
  "request": { "id": 41, "kind": "geographic", "status": "fulfilled", "numberE164": "+497422944121" },
  "assigned": { "id": 12, "e164": "+497422944121", "status": "active" }
}
```

If no number is available right away, `assigned` is `null` and the order stays open until we assign the number. For an 032 number, send `{"kind": "national032"}`. The responses here are shortened; the OpenAPI specification lists all fields.

### Errors

```json
{ "error": "Standort ist noch nicht geprüft", "code": "invalid" }
```

| HTTP | `code` | Meaning |
| --- | --- | --- |
| 400 | `invalid` | Input missing or invalid |
| 401 | `unauthorized` | Key missing, invalid, expired or revoked |
| 403 | `forbidden` | The key lacks the permission, or the feature is dashboard-only |
| 403 | `org_pending` | Verification must be complete before the first number |
| 404 | `not_found` | Number, connection or order does not exist |
| 409 | `invalid` | Not possible right now, for example number limit reached |
| 429 | `forbidden` | More than 120 requests per minute |

---

## Pricing and billing

How we break down phone numbers, call minutes and other services. We agree the applicable rates with you before you start.

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

We’re building TrunkBeam with fair, understandable pricing in mind. A clear cost breakdown is part of that.

Public rates have not been finalized yet. We agree the prices and billing rules for your setup before you start. Rates for these services are available on request:

| Service | Price |
| --- | --- |
| German local number | On request |
| 032 number without an area code | On request |
| Inbound calls | On request |
| Outbound to German landlines | On request |
| Outbound to German mobile networks | On request |
| Transfer via SIP REFER | On request |
| Setup and verification | On request |

Tell us which numbers and call destinations you need. [Request access and pricing for your setup](https://trunkbeam.com/en#waitlist).

### A clear cost breakdown

We itemize phone numbers, call minutes and other services so you can see which costs come from your numbers and which come from usage. If additional services or setup fees apply, we list them separately and discuss them with you before you start.

### Billing

Phone numbers and call minutes are recorded separately. A transfer uses an inbound connection and a connection to the target. Your voice platform bills AI, speech recognition and speech synthesis separately.

You can see usage and calls in the dashboard under **Tarif & Nutzung** (plan & usage) and **Anrufe** (calls), or with the CLI:

```bash
trunkbeam usage --month 2026-10
trunkbeam calls ls --limit 20
```

TrunkBeam is for business customers (B2B). We assign numbers only after company verification. Local numbers require a registered office or branch in that area.
