API Documentation

Quick start

Here's the entire process in 30 seconds:

1

We generate your API key

We create a key for your trust and assign it to your specific hospitals.

2

We send you your credentials

You get an API key and a list of hospital IDs (one per department listing on WaitSmart).

3

You POST to our endpoint

Send waiting times as JSON whenever they change, or on a schedule (every 5-15 minutes is typical).

Endpoint

POST /api/trust-push

Auth header

X-Api-Key

Content type

application/json

Base URL

https://waitsmart.co.uk

Authentication

Include your API key in the X-Api-Key header with every request.

X-Api-Key: your-api-key-here

Your key is locked to specific hospitals. Requests for hospitals not assigned to your key are rejected. If your key is compromised, contact us and we'll revoke and replace it immediately.

Request format

Send a JSON body with a readings array. Each reading is one waiting time update for one hospital.

{
  "readings": [
    {
      "hospitalId": 123,
      "waitMinutes": 47,
      "readAt": "2026-04-15T10:30:00Z",
      "patientsWaiting": 14,
      "department": "A&E"
    }
  ]
}

You can include multiple readings in one request - one for each hospital your trust manages.

Field reference

Field	Type		Description
`hospitalId`	int	Required	WaitSmart hospital ID. We provide this when we set up your key.
`waitMinutes`	int	Required	Current estimated wait in minutes. Range: 0-1440.
`readAt`	string	Required	When the reading was taken. ISO 8601 UTC, e.g. `2026-04-15T10:30:00Z`
`patientsWaiting`	int	Optional	Number of patients currently waiting.
`department`	string	Optional	Department label: `"A&E"`, `"UTC"`, `"MIU"`, etc.
`alertMessage`	string	Optional	Urgent notice shown in a red banner. Max 1,000 chars.
`generalMessage`	string	Optional	General trust message shown in a blue info box. Max 2,000 chars.

Alert & general messages

Communicate directly with patients viewing your hospital on WaitSmart.

Alert message

For urgent, breaking information. Shown in a red banner above the waiting time:

How it appears on WaitSmart

A&E temporarily diverting patients to Royal Derby Hospital due to capacity

Use for: patient diversions, temporary closures, major incidents.

General message

For non-urgent information. Shown in a blue info box below the waiting time:

How it appears on WaitSmart

Message from the trust: We are experiencing higher than usual demand today

Use for: demand updates, seasonal advice, planned changes.

How messages persist: Omit the field to leave the current message unchanged. Send an empty string "" to clear it. Messages stay until you update or clear them.

Response

Every request returns a summary of what was processed:

Success

{
  "ok": true,
  "accepted": 2,
  "rejected": 0,
  "errors": []
}

If some readings fail validation, you get a partial success with details:

Partial success

{
  "ok": true,
  "accepted": 1,
  "rejected": 1,
  "errors": ["Hospital 999 is not assigned to this API key"]
}

Errors & status codes

200	Request processed. Check `accepted` and `rejected` counts.
400	Bad request - invalid JSON, missing `readings` array, or empty body.
401	Missing `X-Api-Key` header.
403	Invalid, revoked, or unconfigured API key.
405	Wrong HTTP method. Must be `POST`.
500	Server error. Retry or contact us.

Code examples

Complete, copy-paste examples in every major language. Replace your-api-key and the hospital ID with your real values.

Basic - push a single reading

curl -X POST https://waitsmart.co.uk/api/trust-push \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{
    "readings": [{
      "hospitalId": 123,
      "waitMinutes": 45,
      "readAt": "2026-04-15T10:30:00Z"
    }]
  }'

import requests

response = requests.post(
    "https://waitsmart.co.uk/api/trust-push",
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": "your-api-key"
    },
    json={
        "readings": [{
            "hospitalId": 123,
            "waitMinutes": 45,
            "readAt": "2026-04-15T10:30:00Z"
        }]
    }
)

print(response.json())
# {"ok": true, "accepted": 1, "rejected": 0, "errors": []}

const response = await fetch("https://waitsmart.co.uk/api/trust-push", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "your-api-key"
  },
  body: JSON.stringify({
    readings: [{
      hospitalId: 123,
      waitMinutes: 45,
      readAt: "2026-04-15T10:30:00Z"
    }]
  })
});

const data = await response.json();
console.log(data);
// { ok: true, accepted: 1, rejected: 0, errors: [] }

$ch = curl_init("https://waitsmart.co.uk/api/trust-push");

curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Content-Type: application/json",
        "X-Api-Key: your-api-key"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "readings" => [[
            "hospitalId"  => 123,
            "waitMinutes" => 45,
            "readAt"       => "2026-04-15T10:30:00Z"
        ]]
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
// {"ok":true,"accepted":1,"rejected":0,"errors":[]}

import java.net.http.*;
import java.net.URI;

var body = """
    {"readings":[{
      "hospitalId": 123,
      "waitMinutes": 45,
      "readAt": "2026-04-15T10:30:00Z"
    }]}
    """;

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://waitsmart.co.uk/api/trust-push"))
    .header("Content-Type", "application/json")
    .header("X-Api-Key", "your-api-key")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
// {"ok":true,"accepted":1,"rejected":0,"errors":[]}

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "your-api-key");

var json = @"{""readings"":[{
    ""hospitalId"": 123,
    ""waitMinutes"": 45,
    ""readAt"": ""2026-04-15T10:30:00Z""
}]}";

var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync(
    "https://waitsmart.co.uk/api/trust-push", content);

Console.WriteLine(await response.Content.ReadAsStringAsync());
// {"ok":true,"accepted":1,"rejected":0,"errors":[]}

Multiple hospitals with all fields

curl -X POST https://waitsmart.co.uk/api/trust-push \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{
    "readings": [
      {
        "hospitalId": 123,
        "waitMinutes": 47,
        "readAt": "2026-04-15T10:30:00Z",
        "patientsWaiting": 14,
        "department": "A&E"
      },
      {
        "hospitalId": 456,
        "waitMinutes": 12,
        "readAt": "2026-04-15T10:30:00Z",
        "patientsWaiting": 5,
        "department": "UTC"
      }
    ]
  }'

import requests
from datetime import datetime, timezone

now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

response = requests.post(
    "https://waitsmart.co.uk/api/trust-push",
    headers={"X-Api-Key": "your-api-key"},
    json={
        "readings": [
            {"hospitalId": 123, "waitMinutes": 47, "readAt": now,
             "patientsWaiting": 14, "department": "A&E"},
            {"hospitalId": 456, "waitMinutes": 12, "readAt": now,
             "patientsWaiting": 5, "department": "UTC"}
        ]
    }
)

print(response.json())

const now = new Date().toISOString();

const response = await fetch("https://waitsmart.co.uk/api/trust-push", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "your-api-key"
  },
  body: JSON.stringify({
    readings: [
      { hospitalId: 123, waitMinutes: 47, readAt: now,
        patientsWaiting: 14, department: "A&E" },
      { hospitalId: 456, waitMinutes: 12, readAt: now,
        patientsWaiting: 5, department: "UTC" }
    ]
  })
});

console.log(await response.json());

$now = gmdate("Y-m-d\TH:i:s\Z");

$ch = curl_init("https://waitsmart.co.uk/api/trust-push");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Content-Type: application/json",
        "X-Api-Key: your-api-key"
    ],
    CURLOPT_POSTFIELDS => json_encode(["readings" => [
        ["hospitalId" => 123, "waitMinutes" => 47, "readAt" => $now,
         "patientsWaiting" => 14, "department" => "A&E"],
        ["hospitalId" => 456, "waitMinutes" => 12, "readAt" => $now,
         "patientsWaiting" => 5, "department" => "UTC"]
    ]])
]);

echo curl_exec($ch);
curl_close($ch);

Setting an alert message

curl -X POST https://waitsmart.co.uk/api/trust-push \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{
    "readings": [{
      "hospitalId": 123,
      "waitMinutes": 120,
      "readAt": "2026-04-15T10:30:00Z",
      "alertMessage": "A&E diverting patients to Royal Derby Hospital",
      "generalMessage": "Experiencing significantly higher demand than usual"
    }]
  }'

response = requests.post(
    "https://waitsmart.co.uk/api/trust-push",
    headers={"X-Api-Key": "your-api-key"},
    json={"readings": [{
        "hospitalId": 123,
        "waitMinutes": 120,
        "readAt": "2026-04-15T10:30:00Z",
        "alertMessage": "A&E diverting patients to Royal Derby Hospital",
        "generalMessage": "Experiencing significantly higher demand than usual"
    }]}
)

await fetch("https://waitsmart.co.uk/api/trust-push", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "your-api-key"
  },
  body: JSON.stringify({ readings: [{
    hospitalId: 123,
    waitMinutes: 120,
    readAt: "2026-04-15T10:30:00Z",
    alertMessage: "A&E diverting patients to Royal Derby Hospital",
    generalMessage: "Experiencing significantly higher demand than usual"
  }]})
});

Clearing a message

Send an empty string to remove an alert or general message:

curl -X POST https://waitsmart.co.uk/api/trust-push \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key" \
  -d '{"readings":[{
    "hospitalId": 123,
    "waitMinutes": 35,
    "readAt": "2026-04-15T14:00:00Z",
    "alertMessage": ""
  }]}'

Limits & constraints

Constraint	Value
Readings per request	100 max
`waitMinutes` range	0 - 1440
`readAt` age	Within the last 7 days, not in the future
`alertMessage` length	1,000 characters
`generalMessage` length	2,000 characters
Hospital access	Only hospitals assigned to your API key
Request rate	No limit - push as often as needed

Testing

Your API key is live from the moment we create it. To test:

Send a single reading for one hospital
Visit the hospital's page on WaitSmart and confirm the wait time updated
Try an alertMessage and check it appears as a red banner
Send "alertMessage": "" to clear it
Automate in your systems

Need help? If you run into anything during integration, get in touch. We're happy to debug requests together, hop on a call, or adjust anything on our end.