Skip to main content

Base URL

Every path in these docs is relative to it: POST /sms/send means POST https://app.telaven.com/api/v1/sms/send.

Requests

  • Send POST, PATCH and PUT bodies as JSON with Content-Type: application/json.
  • Filtering, search and paging on GET requests use query parameters.
  • IDs are opaque strings. Store them as they are and don’t parse them.
  • Add an Idempotency-Key header to POST requests you might retry.

Responses

Responses are JSON. Most return success: true with the result in data:
Errors return the HTTP status with an error message, plus a stable code where your code may want to branch. See Errors.

Idempotency

Networks fail. If a POST /sms/send times out, you can’t tell whether the SMS went out. Send an Idempotency-Key header so a retry can never send it twice:
  • Use a new unique value, such as a UUID, for each operation, and the same value on every retry of it. Keys are up to 255 characters with no spaces, and belong to your business.
  • Repeating a request with the same key, endpoint and body within 24 hours returns the first response, with the header Idempotent-Replayed: true. Nothing is sent or charged again.
  • Reusing a key for a different request returns 422 IDEMPOTENCY_KEY_REUSED.
  • While the first request is still running, a repeat returns 409 IDEMPOTENCY_IN_PROGRESS with Retry-After: 1.
  • A 4xx or 503 response frees the key: fix the request (or top up) and retry with the same key.
  • A 500 is stored and replayed, because the request may have partly run. Check what happened (for example with GET /sms/messages) before retrying with a new key.
Works on every POST that sends or creates something: send SMS, create and send SMS and email campaigns, send WhatsApp templates, create WhatsApp campaigns, and create contacts, contact lists, unsubscribes, deals, companies and pipelines.

Pagination

List endpoints take page (from 1) and limit (1–100, default 20) and return a pagination object:
GET /contacts returns hasMore instead of total and totalPages: keep asking for the next page until it’s false.

Phone numbers

Numbers can be in local or international format. Responses always show them in international format. Don’t include spaces or dashes.

Money

Amounts are in your wallet’s currency.
  • Fields ending in Kes are strings with two decimals, for example "balanceKes": "14437.50".
  • Fields ending in Cents are whole numbers of cents, so 100 is 1.00.
  • Your SMS price depends on your account and your recent top-ups. Read it from GET /wallet rather than hard-coding it.

Times

Timestamps are ISO 8601 in UTC (2026-11-12T09:30:01.000Z). When you schedule something, include an offset, for example 2026-11-15T08:00:00+03:00 for 8 am at UTC+3.