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.

If your system can already send email, email to SMS may be the quicker route. It needs no code beyond adding a gateway key header.

Base URL

All requests go to:

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:

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.

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
`GET`	`/{authKey}/v2/sms/{reference}`	Get an SMS

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.
`500 Internal Server Error`	Something went wrong on our side. The body reads `A server error occurred`. Retry later.

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.

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

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