Base URL
POST /sms/send means POST https://app.telaven.com/api/v1/sms/send.
Requests
- Send
POST,PATCHandPUTbodies as JSON withContent-Type: application/json. - Filtering, search and paging on
GETrequests use query parameters. - IDs are opaque strings. Store them as they are and don’t parse them.
- Add an
Idempotency-Keyheader toPOSTrequests you might retry.
Responses
Responses are JSON. Most returnsuccess: true with the result in data:
error message, plus a stable code where your code may want to branch. See Errors.
Idempotency
Networks fail. If aPOST /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_PROGRESSwithRetry-After: 1. - A
4xxor503response frees the key: fix the request (or top up) and retry with the same key. - A
500is stored and replayed, because the request may have partly run. Check what happened (for example withGET /sms/messages) before retrying with a new key.
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 takepage (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
Kesare strings with two decimals, for example"balanceKes": "14437.50". - Fields ending in
Centsare whole numbers of cents, so100is 1.00. - Your SMS price depends on your account and your recent top-ups. Read it from
GET /walletrather 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.