TimberSwitch developer API

Programmatic access to numbers, calls, voicemails, SMS, contacts, and the full webhook event stream. Same auth surface your team already uses - just add an X-API-Key header.

API reference: every route with its scopes, parameters and response fields, generated from our OpenAPI 3.1 spec, plus rate limits, errors and webhook signature checks.

Auth

Generate a key in Account → API keys with the scopes you need. Send it on every request as a header:

X-API-Key: bz_live_…

Or, equivalently, as a Bearer token:

Authorization: Bearer bz_live_…

Keys are scoped - you pick exactly which verbs each key can do at create time. Recommended starter scopes: read:telephony, write:telephony, telephony:dial.

Numbers, calls & voicemails

Method	Path	What it does
GET	/api/v1/orgs/{slug}/calls?limit=50	Recent call history.
GET	/api/v1/orgs/{slug}/voicemails	Voicemails for the org.
POST	/api/v1/orgs/{slug}/voicemails/{id}/read	Mark a voicemail read.
POST	/api/v1/orgs/{slug}/voicemails/{id}/archive	Archive a voicemail.
GET	/api/v1/orgs/{slug}/voicemails/{id}/audio	302 → 15-min presigned S3 audio URL.
GET	/api/v1/orgs/{slug}/recordings/{id}/audio	302 → 15-min presigned S3 recording URL.

SMS

Method	Path	What it does
POST	/api/zapier/actions/send-sms	Send an outbound SMS with a `zapier`-scoped key bound to one workspace. Body: `{ to, body, from_number, idempotency_key }`.
GET	/api/v1/orgs/{slug}/sms/threads	List conversation threads.
GET	/api/v1/orgs/{slug}/sms/threads/{id}	Get one thread (with contact + our-number metadata).
GET	/api/v1/orgs/{slug}/sms/threads/{id}/messages?limit=100	Paginated message history for a thread.

US outbound SMS requires A2P 10DLC brand + campaign registration - without it carriers throttle to ~1 msg/sec. Configure under /phone/messaging-registration.

Contacts (address book)

Method	Path	What it does
GET	/api/v1/orgs/{slug}/contacts?search=&limit=100	List or search contacts.
GET	/api/v1/orgs/{slug}/contacts/{id}	Get one contact.
POST	/api/v1/orgs/{slug}/contacts	Upsert by E.164. Body: `{ e164, firstName, lastName, company, email, notes, tags }`.
PATCH	/api/v1/orgs/{slug}/contacts/{id}	Partial update.
DELETE	/api/v1/orgs/{slug}/contacts/{id}	Remove.
GET	/api/v1/orgs/{slug}/caller-context?e164=+1NNN	Aggregated view (contact + last calls + last VMs + last SMS).

curl -X POST https://www.timberswitch.com/api/v1/orgs/your-slug/contacts \
  -H "X-API-Key: ts_live_..." -H "Content-Type: application/json" \
  -d '{"e164":"+15551234567","firstName":"Sarah","company":"Acme"}'

Webhooks

We POST to your endpoint with an HMAC-signed JSON body. Configure endpoints under /phone/webhooks with an event filter glob (e.g. sms.*, call.completed, or *). Delivery retries with exponential backoff up to 8 attempts. See verifying signatures.

Event	When it fires	Key payload fields
`voicemail.received`	Voicemail finalized + transcribed	voicemail_id, from, duration_seconds, transcript, audio_endpoint
`sms.received`	Inbound SMS persisted	message_id, thread_id, from, to_phone_number_id, body, is_stop, is_help
`call.completed`	Call leg ended	call_id, direction, from, to, status, duration_seconds, hangup_cause

Also sent: call.missed (only to endpoints that name it), contact.created, contact.updated and contact.deleted. More call and message events come with the public v1.

Conventions

All IDs are opaque strings - don't parse them.
All timestamps are ISO-8601 in UTC.
Phone numbers are E.164 (+1NNNNNNNNNN for US).
Errors use the standard HTTP status; most bodies are { "error": "..." }. See errors.
Rate limits: 100 requests per minute per user. See rate limits.
Webhook signatures: Timberswitch-Signature: sha256=<hex>, an HMAC-SHA256 of {timestamp}.{raw body} with the Timberswitch-Timestamp header.

Need something not here?

Ask through our support form or hop into Switchboard in your workspace - it can answer questions about your own account state and the API.