TimberSwitch API reference

Getting an API key

1. Sign in and open Account > API keys.
2. Name the key and pick its scopes. A key can only do what its scopes allow; a key with no scopes selected gets read-only profile and workspace access.
3. Under Workspace, limit the key to one workspace. We recommend this for every integration: a bound key is refused (403) on any other workspace's routes. It is required for the zapier scope.
4. Optionally set an expiry. Copy the key when it is shown: we store only a hash and cannot show it again. Keys look like bz_live_ followed by 32 characters.

The key acts as you. Routes that need a workspace owner or admin still check your role in that workspace, and a suspended member's key stops working there.

Authentication

Send the key on every request, in either header:

X-API-Key: bz_live_...
Authorization: Bearer bz_live_...

Keys in the query string are refused. Use HTTPS only. Find your workspace slug with GET /api/v1/orgs:

curl https://www.timberswitch.com/api/v1/orgs -H "X-API-Key: $TS_KEY"
curl "https://www.timberswitch.com/api/v1/orgs/your-slug/calls?limit=20" -H "X-API-Key: $TS_KEY"

Rate limits

Today there is one limit for API traffic: 100 requests per minute per user (fixed window). All of a user's keys and browser sessions share that budget. Over it, you get 429 Too Many Requests with an empty body and no Retry-After header, so back off for up to a minute and retry. Texts sent through the API also count against the workspace's daily texting caps.

Planned for v1: per-key limits by cost group, RateLimit-* headers and Retry-After.

Pagination

List routes return a plain JSON array, newest first, and take a limit query parameter that is clamped to a maximum (200 for calls, voicemail and conversations; 500 for contacts and messages). There is no cursor yet: you can read the most recent page only. For a full history, sync forward with webhooks and keep your own copy.

Planned for v1: ?limit=&cursor= with { "data": [...], "has_more": true, "next_cursor": "..." }.

Errors

Status codes are reliable; bodies are not uniform yet. What you will see today:

The Zapier routes always return { "error": "code", "message": "..." }, with codes such as insufficient_scope, key_not_bound, invalid_to and suppressed.

Planned for v1: one envelope, { "error": { "type", "code", "message", "param", "request_id" } }, on every error.

Webhooks and signing

Add an https endpoint in the app under Phone > Webhooks, with an event filter: *, a list such as call.completed,sms.received, or a prefix such as contact.*. Zapier subscribes its own endpoints through POST /api/zapier/hooks.

Every delivery is a POST with this body:

{ "id": "evt guid", "type": "call.completed", "created": 1759500000, "data": { ... } }

Verifying the signature

Each request carries two headers:

Timberswitch-Timestamp: 1759500000
Timberswitch-Signature: sha256=<hex HMAC-SHA256 of "{timestamp}.{raw body}" keyed with your endpoint's secret>

The secret (whsec_...) is shown when you create the endpoint. Compute the HMAC over the raw request bytes, before any JSON parsing, compare in constant time, and reject timestamps more than 5 minutes from your clock to stop replays. Answer with any 2xx within 10 seconds.

curl / shell (check a captured delivery):

# SECRET = your endpoint's whsec_... secret, TS = the Timberswitch-Timestamp header,
# body.json = the raw request body exactly as received.
{ printf '%s.' "$TS"; cat body.json; } \
  | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.*= /sha256=/'
# The output must equal the Timberswitch-Signature header.

Node.js

const crypto = require('crypto');

// rawBody: the request body as a string or Buffer, before JSON.parse
// (in Express: express.raw({ type: 'application/json' })).
function verifyTimberswitch(rawBody, headers, secret) {
  const ts = headers['timberswitch-timestamp'];
  const sig = headers['timberswitch-signature'] || '';
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret)
    .update(ts + '.').update(rawBody).digest('hex');
  const a = Buffer.from(sig), b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

C#

using System.Security.Cryptography;
using System.Text;

// rawBody: the request body exactly as received (read it before deserializing).
static bool VerifyTimberswitch(string rawBody, string timestamp, string signature, string secret)
{
    if (!long.TryParse(timestamp, out var ts)
        || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - ts) > 300) return false;
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(timestamp + "." + rawBody));
    var expected = "sha256=" + Convert.ToHexString(hash).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(signature ?? ""));
}

Retries: a delivery that fails or gets a non-2xx response is retried with exponential backoff (10 s, 20 s, 40 s and so on), up to 8 attempts in total, then dropped. The id is the same on every retry of an event, so use it to ignore duplicates.

Planned for v1: Standard Webhooks signing (webhook-id, webhook-timestamp, webhook-signature) alongside today's headers, secret rotation, and a delivery log you can replay from.

Reference

Base URL https://www.timberswitch.com. Version: v1 (preview, 2026-10-04).

Account

Who is calling, and which workspaces they can reach.

Numbers and extensions

The workspace's phone numbers and extensions (read only).

Calls

The call log and per-number caller context.

Voicemail

Voicemails with transcripts, read/archive state and audio.

Recordings

Call-recording audio.

Contacts

The shared address book.

SMS

Text conversations and their messages (read only; see the Zapier send-sms action for sending).

Zapier app

The routes the TimberSwitch Zapier app uses. The workspace comes from the key, not the URL.

Schemas

JSON field names are camelCase on the /api/v1 routes and snake_case on the Zapier routes and in webhook payloads. Unknown fields may be added at any time; ignore them.

Changelog

2026-10-04

First published spec (/api/openapi/v1.json) and this reference. Response bodies are now typed projections; the field names did not change. Two fields changed: voicemail audioUrl is always our authenticated audio route, and SMS messages no longer include the carrier's internal message id.

Next: public v1

A versioned /v1 surface with keys bound to one workspace, resource scopes (calls:read, messages:send and so on), cursor pagination, one error envelope, Idempotency-Key, per-key rate-limit headers, sending texts and managing webhook endpoints over the API, and Standard Webhooks signing. The routes on this page keep working through the change, with notice before anything is retired.