# DiaryBook API overview

The DiaryBook API lets your own software send SMS over HTTPS: a booking system sending confirmations, a database sending notices, or a monitoring tool alerting on-call staff. Messages sent through the API use the same account, credit, sender IDs and stop list as the web portal.

> [!TIP]
> If your system can already send email, [email to SMS](/docs/email-to-sms/send-by-email/) may be the quicker route. It needs no code beyond adding a [gateway key](/docs/email-to-sms/gateway-keys/) header.

## Base URL

All requests go to:

```text
https://api.diarybook.com/{authKey}/v2
```

Use HTTPS for every request so that your key and message content are encrypted in transit.

## Authentication

Every request is authenticated by your API key, which is the first segment of the URL path:

```text
https://api.diarybook.com/YOUR_API_KEY/v2/sms
```

The key identifies your account and the user that messages are sent as. Treat it like a password: keep it on your server, out of browser code, source control and logs. A request with a missing or unrecognised key gets `401 Unauthorized`.

[Contact us](/contact/) to get an API key for your account.

## Requests and responses

- Request bodies are JSON. Send `Content-Type: application/json`.
- Successful responses are JSON (`application/json`).
- Error responses for `400` and `500` are a short plain-text message, not JSON.
- Dates are UTC in ISO 8601 format, for example `2026-10-14T09:30:00Z`.
- Responses include a `links` array of `{ "href", "rel" }` objects. A link with `rel` of `self` is the URL for retrieving that resource.

## Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| `POST` | `/{authKey}/v2/sms` | [Send an SMS](/docs/api/send-sms/) |
| `GET` | `/{authKey}/v2/sms/{reference}` | [Get an SMS](/docs/api/get-sms/) |
{.table}

## HTTP status codes

| Code | Meaning |
|------|---------|
| `200 OK` | The request succeeded. The body holds the result. |
| `204 No Content` | The request succeeded but there is nothing to return, for example no message matches the reference. |
| `400 Bad Request` | The request was rejected. The body is a plain-text explanation, such as `No mobile number`. |
| `401 Unauthorized` | The API key is missing, unknown or not an API key. The body is empty. |
| `429 Too Many Requests` | You have exceeded your rate limit. See [Rate limits](#rate-limits). |
| `500 Internal Server Error` | Something went wrong on our side. The body reads `A server error occurred`. Retry later. |
{.table}

A `400` from the send endpoint may carry an Iflow status code in the form `Error[9101]: ...`. The number has the same meaning as in the portal; see [Status and error codes](/docs/reference/sms-status-codes/).

## Rate limits

Every call is counted against your account's limits, which can apply per second, per minute and per hour. Each response carries an `X-RateLimit-Limit-Status` header. When a limit is exceeded the API returns `429` with these headers:

| Header | Example | Meaning |
|--------|---------|---------|
| `X-RateLimit-Limit-Status` | `Exceeded` | `Ok` on normal responses, `Exceeded` when blocked |
| `X-RateLimit-Limit-Type` | `Per Minute` | Which limit was hit: `Per Second`, `Per Minute` or `Per Hour` |
| `X-RateLimit-Limit` | `60` | The number of calls allowed in that period |
{.table}

On a `429`, wait for the period named in `X-RateLimit-Limit-Type` to pass before retrying. Don't retry in a tight loop.

## Related

- [Send an SMS](/docs/api/send-sms/)
- [Get an SMS](/docs/api/get-sms/)
- [Status and error codes](/docs/reference/sms-status-codes/)
- [Send SMS by email](/docs/email-to-sms/send-by-email/)

---
Source: https://iflow.net/docs/api/http-api/