What is the default rate limit?

100 requests per second per API key with burst headroom on the default partner tier. X-RateLimit-Remaining and X-RateLimit-Reset headers are returned on every response.

How are webhook payloads signed?

Every event carries an HMAC-SHA256 signature in the X-TKOS-Signature header keyed off your endpoint secret. We retry on 5xx with exponential back-off for up to 24 hours.

Does the API support idempotency?

Yes. Pass an Idempotency-Key header on POST requests and we deduplicate retries safely for 24 hours. Recommended on every billable write.

How are breaking changes handled?

Endpoints are pinned to /v1. Breaking changes ship under a new prefix only — never silently. Deprecations are announced 90 days ahead with migration notes in the changelog.

API Reference

REST API for the TKOS voice & messaging network.

Authenticate, provision DIDs across 100+ countries, route calls over 500+ direct carrier interconnects, send SMS, and stream CDRs in real time. Backed by a 99.9% uptime SLA and a 24/7 NOC out of Johannesburg.

Get A Free Trial See Pricing

/v1 · JSON · HMAC webhooks · OpenAPI · 99.9% SLA

Capabilities

Six surfaces, one carrier-grade API.

Everything you need to launch carrier-grade voice and messaging — from auth and provisioning through to CDR streaming and webhook delivery. Most partners build against the SMS endpoints in the first sprint.

Authentication

Bearer keys

Partner-scoped API keys with rotation, plus OAuth 2.0 client-credentials for multi-tenant resellers.

Voice provisioning

POST /v1/calls

Place outbound calls, hand off media to your SIP endpoint, or trigger PSTN breakouts over 500+ interconnects.

SMS dispatch

POST /v1/messages

A2P and P2P SMS with delivery callbacks and audience segmentation for high-volume campaigns.

Webhooks

HMAC signed

Subscribe to call, SMS, and provisioning events. Retries on 5xx with 30-day delivery history.

Call recording

GET /v1/recordings

Encrypted recordings with PHI redaction on detection plus full audit-trail export.

CDR streaming

GET /v1/cdrs

Real-time call detail records for billing reconciliation. Filter by date, route, destination or partner.

~/tkos — place-first-call.shlive

curl -X POST https://api.tkos.co.za/v1/calls \
  -H "Authorization: Bearer $TKOS_KEY" \
  -H "Idempotency-Key: $UUID" \
  -d '{
    "from": "+27 11 555 0142",
    "to": "+234 1 808 1124",
    "webhook": "https://your.app/hooks"
  }'

# => 201 Created
{ "id": "cl_8h2a", "status": "ringing", "route": "ZA-NG-direct" }

Code Example

Your first call in one cURL.

Bearer auth, an idempotency key, and a JSON body — that's the whole contract. Every endpoint mirrors IETF RFC 3261 semantics on signalling, so your SIP traces line up with what the API returns. The same primitives back our hosted phone system.

POST
/v1/calls
Ring an E.164 number on any of 500+ interconnects.
GET
/v1/numbers
Search DIDs across 100+ country inventories.
POST
/v1/messages
Send SMS with delivery callbacks.
GET
/v1/cdrs
Stream call detail records for billing reconciliation.

Operational

Rate limits & auth, surfaced clearly.

The TKOS partner platform shares limits and auth conventions across every endpoint. Need higher headroom? Reach out via the wholesale voice team and we'll quote a custom tier.

Rate limits

100 req/sec per API key
Burst allowance on retries
X-RateLimit-Remaining on every response

Auth & signing

Authorization: Bearer <key>
Idempotency-Key on writes
HMAC-SHA256 on webhook delivery

Conventions

REST + JSON, predictable URLs
/v1 versioning, no silent breaks
ISO-8601 timestamps in UTC

Developer FAQ

What engineers ask before the first request.

Five things our partners' platform teams raise on the first call. Need more depth? An engineer is one click away.

Bearer tokens on every request. Keys are partner-scoped and rotatable from the portal. OAuth 2.0 client-credentials is available for multi-tenant resellers.

Get A Free Trial

Send your first call through TKOS this week.

A free trial gets you API keys, sandbox numbers, signed webhooks and a tier-3 engineer on standby. 99.9% uptime SLA, STIR/SHAKEN attestation active.

Get A Free Trial See Pricing

REST APIWebhooksTyped SDKsEngineer on call

curl -X POST https://api.tkos.co.za/v1/calls \ -H "Authorization: Bearer $TKOS_KEY" \ -H "Idempotency-Key: $UUID" \ -d '{ "from": "+27 11 555 0142", "to": "+234 1 808 1124", "webhook": "https://your.app/hooks" }' # => 201 Created { "id": "cl_8h2a", "status": "ringing", "route": "ZA-NG-direct" }

REST API for the TKOS voice & messaging network.

Six surfaces, one carrier-grade API.

Authentication

Voice provisioning

SMS dispatch

Webhooks

Call recording

CDR streaming

Your first call in one cURL.

Rate limits & auth, surfaced clearly.

Rate limits

Auth & signing

Conventions

What engineers ask before the first request.

Q1.Which auth scheme does the API use?

Q2.What is the default rate limit?

Q3.How are webhook payloads signed?

Q4.Does the API support idempotency?

Q5.How are breaking changes handled?

Send your first call through TKOS this week.

REST API for the TKOS voice & messaging network.

Six surfaces, one carrier-grade API.

Authentication

Voice provisioning

SMS dispatch

Webhooks

Call recording

CDR streaming

Your first call in one cURL.

Rate limits & auth, surfaced clearly.

Rate limits

Auth & signing

Conventions

What engineers ask before the first request.

Q1.Which auth scheme does the API use?

Q2.What is the default rate limit?

Q3.How are webhook payloads signed?

Q4.Does the API support idempotency?

Q5.How are breaking changes handled?

Send your first call through TKOS this week.