API Documentation

Connect your CRM to your Cloud PBX. Pull every call and its recording automatically, and get a webhook within seconds of each call ending.

Quick start

1. Get your API keyAdd PBX API Access to your account and our support team will issue your key. A key only ever sees your own account's calls.
2. Make your first request

   curl https://pbx.cloudtools.co.za/api/v1/calls \
     -H "Authorization: Bearer YOUR_API_KEY"

3. Register a webhookTell us where to send calls as they end:

   curl -X POST https://pbx.cloudtools.co.za/api/v1/webhooks \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"url": "https://crm.example.com/hooks/calls"}'

Endpoints

The call object

Every endpoint and every webhook describes a call the same way.

{
  "id": 411971,
  "domain": "yourcompany.cloudtools.co.za",
  "direction": "inbound",
  "extension": "101",
  "caller_number": "27821234567",
  "called_number": "27101011200",
  "started_at": "2026-10-12T17:30:50+02:00",
  "answered_at": "2026-10-12T17:30:56+02:00",
  "ended_at": "2026-10-12T17:34:12+02:00",
  "duration_seconds": 196,
  "answered": true,
  "hangup_cause": "NORMAL_CLEARING",
  "has_recording": true,
  "recording_url": "https://pbx.cloudtools.co.za/api/v1/calls/411971/recording"
}

Calls & recordings

GET /calls?start_date=2026-10-01&end_date=2026-10-12&direction=inbound

{
  "success": true,
  "data": [ /* call objects, oldest first */ ],
  "meta": { "count": 3, "last_id": 411974, "has_more": false }
}

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -o call-411971.mp3 \
  https://pbx.cloudtools.co.za/api/v1/calls/411971/recording

Webhooks

Register an HTTPS address and we'll POST every completed call on your account to it, usually within a few seconds of hang-up.

{ "url": "https://crm.example.com/hooks/calls" }

{
  "success": true,
  "data": {
    "id": "306f3bad-8fee-440c-a1e1-b4dea1da24dc",
    "url": "https://crm.example.com/hooks/calls",
    "events": ["call.ended"],
    "enabled": true,
    "secret": "whsec_…"
  }
}

What we send

POST /hooks/calls
Content-Type: application/json
X-Webhook-Event: call.ended
X-Webhook-Id: 18734
X-Webhook-Timestamp: 1791820217
X-Webhook-Signature: sha256=5f1c…

{
  "event": "call.ended",
  "sent_at": "2026-10-12T17:34:15+02:00",
  "call": { /* the call object */ }
}

Verify the signature

Compute an HMAC-SHA256 of timestamp + "." + raw body with your webhook secret and compare it with X-Webhook-Signature. Reject timestamps more than 5 minutes old.

$body = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'];
$sig  = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);

if (!hash_equals($sig, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE']) || abs(time() - $ts) > 300) {
    http_response_code(401); exit;
}

import hmac, hashlib, time

expected = "sha256=" + hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(expected, signature) and abs(time.time() - int(ts)) < 300

const crypto = require('crypto')

const expected = 'sha256=' + crypto.createHmac('sha256', secret)
  .update(`${ts}.` + rawBody).digest('hex')
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
  && Math.abs(Date.now() / 1000 - Number(ts)) < 300

Retries

If your endpoint is down or doesn't reply 2xx, we try again on this schedule, then give up on that call:

X-Webhook-Id stays the same across retries, so you can safely ignore duplicates. A webhook that fails 50 times in a row is paused. Fix the endpoint and re-enable it with PATCH.

Errors