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.

Docs on one page

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

Quickstart

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

Open this chapter

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, 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.

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 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, your AI assistant, for example Claude Code, Codex or Cursor, does the setup when you ask it to. With the CLI it looks like this:

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

Account and verification

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

Open this chapter

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, 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:

Proofat most
Internet or landline bill with the connection address3 months old
Electricity, gas or water bill with the supply address3 months old
Annual statement for electricity, gas or water12 months old
Municipal waste fee or property tax notice12 months old
Landlord’s service charge statement for these premises12 months old
Trade tax notice listing the business premises12 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:

Permissionallows
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.

Open this chapter

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

DirectionWhat happensWhere you set it
InboundTrunkBeam delivers calls to your number to the provider’s SIP URI.Dashboard → Rufnummern → number → Verbindung
Outbound and transfersYour 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:

FieldValue
Server / Addresssip.trunkbeam.com
Port5061
TransportTLS
Username / Passwordfrom 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 headerContent
X-TrunkBeam-Calledthe TrunkBeam number that was called
X-TrunkBeam-Transferonly when a call returns after a transfer: the reason (no-answer, busy, unavailable, not-allowed, limit)
X-TrunkBeam-Transfer-Targetonly 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.

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, 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:

    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:

    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, SIP API, Transfer

Self-hosted LiveKit

Same as LiveKit Cloud, with the 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:

    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:

    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, 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:

FieldValue
Phone Numberyour TrunkBeam number in E.164 format
Termination URIsip.trunkbeam.com
TransportTLS
SIP Trunk User Name / Passwordfrom Konto → SIP-Zugang
Inbound Agentthe 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, Transfer

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:

    { "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, 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

Deepgram Voice Agent

Deepgram has no SIP interface. Build the agent with LiveKit Agents and the Deepgram plugins and connect it like LiveKit. Alternatively use Pipecat with the Daily or LiveKit transport.

Deepgram documentation: Deepgram with LiveKit

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.

Open this chapter

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:

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):

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:

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.

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 and SDP codec negotiation in RFC 3264.

Technical details

SignalingSIP over TLS (port 5061)
MediaSRTP and RTP
CodecsG.722, G.711 A-law (PCMA), G.711 µ-law (PCMU)
DTMFRFC 2833 (telephone-event)
Number formatE.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.

Open this chapter

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 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.

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.

Access and next steps

Connecting an existing voice agent? Request early access or read about SIP connectivity.

MCP server

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

Open this chapter

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

ToolWhat it doesPermission
trunkbeam_accountAccount, verification status, plan and the key’s permissionsRead
trunkbeam_pricesPlans and pricesRead
trunkbeam_list_sitesSites; only verified sites get local numbersRead
trunkbeam_search_area_codeSearch an area code by place or codeRead
trunkbeam_list_numbersYour numbers with targetRead
trunkbeam_order_numberOrder a local or 032 number, asks firstOrder
trunkbeam_list_number_requestsOrders and their statusRead
trunkbeam_release_numberCancel a number, asks firstOrder
trunkbeam_connect_number_elevenlabsConnect a number to ElevenLabs in one stepManage
trunkbeam_set_number_targetRoute a number to any SIP addressManage
trunkbeam_set_number_agent_fallbackFallback number if the agent is unreachableManage
trunkbeam_list_connectionsAgent connections (SIP targets)Read
trunkbeam_create_connectionCreate an agent connectionManage
trunkbeam_delete_connectionDelete an agent connectionManage
trunkbeam_provider_guideSetup guide per provider with your real valuesRead
trunkbeam_get_transfer_policyShow transfers to peopleRead
trunkbeam_set_transfer_policyChange transfers, as default or per numberManage
trunkbeam_reset_number_transfer_policyDelete a number’s own transfer settingsManage
trunkbeam_list_hold_musicHold music with descriptions, so the assistant can pick a fitting trackRead
trunkbeam_list_callsRecent callsRead
trunkbeam_usageUsage and cost for a monthRead

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

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:

claude mcp list

Codex

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

Or directly in ~/.codex/config.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:

{
  "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.

Open this chapter

Installation

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:

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:

export TRUNKBEAM_API_KEY=tb_live_…

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

Global options

OptionEffect
--jsonRaw API data as JSON, for scripts
--yes, -yRun paid actions without asking
--key <key>Use a different API key for this call
--help, -hHelp, also per command: trunkbeam numbers --help

Commands

CommandWhat it does
login, logoutSign the CLI in or out
accountAccount, verification status, plan and the key’s permissions
sitesSites with ID; only verified sites get local numbers
onkz <place or area code>Search an area code, for example onkz Schramberg
numbers lsYour numbers with ID, status and target
numbers order --site <id>Order a local number at the site, shows the price first
numbers order --032Order an 032 number without an area code
numbers connect <id> --elevenlabsConnect 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 resetTransfer to people, as default or per number
hold-musicHold music with descriptions
calls lsRecent calls with duration, status and cost
usage --month <YYYY-MM>Usage and cost for a month
pricesPlans 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.

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

CodeMeaning
0Success
1Error or cancelled
2Invalid usage

REST API

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

Open this chapter

Basics

Base URLhttps://app.trunkbeam.com/v1
AuthAuthorization: Bearer tb_live_…
FormatJSON, timestamps as ISO 8601
Phone numbersE.164, for example +497422944120
Rate limit120 requests per minute per key
SpecificationOpenAPI 3.1 at https://app.trunkbeam.com/v1/openapi.json
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.

Endpoints

MethodPathPurposePermission
GET/accountAccount, plan, verification status, the key’s permissionsread
GET/pricesPlans and pricesread
GET/verificationVerification status and sitesread
GET/onkz?q=SchrambergSearch an area code by place or coderead
GET/numbersYour numbers with targetread
POST/number-requestsOrder a number (local at a site, or 032)order
GET/number-requestsOrders and their statusread
DELETE/number-requests/{id}Withdraw an open orderorder
POST/numbers/{id}/connectConnect a number to ElevenLabs in one stepmanage
PUT/numbers/{id}/targetRoute a number to a SIP addressmanage
PATCH/numbers/{id}Change agent, label or fallback numbermanage
POST/numbers/{id}/releaseCancel a numberorder
GET/connectionsAgent connections (SIP targets)read
POST/connectionsCreate an agent connectionmanage
PATCH/connections/{id}Change an agent connectionmanage
DELETE/connections/{id}Delete an agent connectionmanage
GET/agent-problemsWhy calls did not reach the agentread
GET/credentialSIP access for outbound calls (without password)read
GET/transfer-policyDefault transfer settingsread
PUT/transfer-policySet default transfer settingsmanage
GET/transfer-policiesDefault and effective rule per numberread
GET, PUT, DELETE/numbers/{id}/transfer-policyA number’s own transfer settingsread / manage
GET/hold-musicHold music with descriptionsread
GET/callsCall log, newest firstread
GET/calls/exportItemized calls as CSVread
GET/usage?month=2026-10Usage and cost for a monthread
GET/usage/dailyCalls and minutes per dayread
GET/usage/exportDaily totals for a month as CSVread
GET, PUT/call-log-settingsCall log settingsread / 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:

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": <monthly net price>,
  "message": "Ortsnetznummer im Ortsnetz 07422 für … € netto im Monat …"
}

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

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

{ "error": "Standort ist noch nicht geprüft", "code": "invalid" }
HTTPcodeMeaning
400invalidInput missing or invalid
401unauthorizedKey missing, invalid, expired or revoked
403forbiddenThe key lacks the permission, or the feature is dashboard-only
403org_pendingVerification must be complete before the first number
404not_foundNumber, connection or order does not exist
409invalidNot possible right now, for example number limit reached
429forbiddenMore 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.

Open this chapter

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:

ServicePrice
German local numberOn request
032 number without an area codeOn request
Inbound callsOn request
Outbound to German landlinesOn request
Outbound to German mobile networksOn request
Transfer via SIP REFEROn request
Setup and verificationOn request

Tell us which numbers and call destinations you need. Request access and pricing for your setup.

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:

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.

Connect your stack to TrunkBeam