REST API · TrunkBeam Docs

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

REST API

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

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`

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

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

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

Errors

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

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