> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telaven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Requests and responses

> Base URL, request format, pagination, phone numbers and money.

## Base URL

```text theme={null}
https://app.telaven.com/api/v1
```

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`](#idempotency) header to `POST` requests you might retry.

## Responses

Responses are JSON. Most return `success: true` with the result in `data`:

```json theme={null}
{
  "success": true,
  "data": { "id": "d4c1…", "name": "Jane Wanjiku", "phone": "+254712345678" }
}
```

Errors return the HTTP status with an `error` message, plus a stable `code` where your code may want to branch. See [Errors](https://docs.telaven.com/get-started/errors.md).

```json theme={null}
{
  "error": "Insufficient wallet balance",
  "code": "INSUFFICIENT_BALANCE"
}
```

## 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:

```bash theme={null}
curl -X POST https://app.telaven.com/api/v1/sms/send \
  -H "Authorization: Bearer $TELAVEN_API_KEY" \
  -H "Idempotency-Key: 5f1c2b0e-8d6a-4c1f-9a43-2b7e0f6d1a90" \
  -H "Content-Type: application/json" \
  -d '{ "to": ["0712345678"], "message": "Your code is 4821" }'
```

* 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:

```bash theme={null}
GET /sms/messages?page=2&limit=50
```

```json theme={null}
{
  "success": true,
  "data": [ … ],
  "pagination": { "page": 2, "limit": 50, "total": 430, "totalPages": 9 }
}
```

[`GET /contacts`](https://docs.telaven.com/api-reference/contacts/list-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`](https://docs.telaven.com/guides/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.