Developer API - TimberSwitch

Auth

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

X-API-Key: ts_live_…

Or, equivalently, as a Bearer token:

Authorization: Bearer ts_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/sms/send	Send an outbound SMS. Body: `{ phoneNumberId, contactE164, body }`.
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.

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

More events shipping with later versions - call.answered, call.recording.saved, contact.created, contact.updated.

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 return JSON: { "error": "...message..." } with the standard HTTP status.
Rate limits: 60 req/sec per API key, 1000 req/min per org.
Webhook signatures: HMAC-SHA256 over the raw body, base64 in X-TimberSwitch-Signature.

Need something not here?

Email [email protected] or hop into Switchboard in your workspace - it can answer questions about your own account state and the API.