Atrium — API Documentation
REST API for PMS integration, guest management, billing, and room service
Authentication
Authenticate every request with your hotel's API key, sent in the X-API-Key header (or Authorization: Bearer <key>):
X-API-Key: htv_xxxxxxxxxxxxxxxxxxxxxxxx
Get your API key from the Atrium portal (Installer tab → Integration API key). The key identifies your hotel — you do not need to pass a customer ID, and you only ever see your own guests, rooms, and orders. Keep it secret; if it leaks, click Renew in the portal — the old key stops working immediately.
Base URL
https://ota.mndev.co.za
Testing with a test key (sandbox)
Every hotel also has a test key (htv_test_..., in the portal under the live key). Use it while you build or change an integration, and switch to the live key only after a clean run.
With a test key the guest endpoints behave exactly like live: same URL, same checks, same errors (a 404 ROOM_NOT_CONFIGURED for a room we do not know) and the same reply shape. But nothing real changes: check-ins and checkouts go into a separate test guest list, and no TV, streaming login, casting pairing or welcome screen is touched. GET /api/guests and GET /api/rooms/status return that test list, so a full sync can run end to end.
Every check-in and checkout reply carries a sandbox block saying what would have happened on live, with warnings for anything that would disturb a guest who is still staying:
{
"ok": true,
"signOut": "scheduled",
"sandbox": {
"test": true,
"wouldHappen": "Room 4003 has 1 TV. On live they would be signed out of Netflix, YouTube and the other streaming apps, and AirPlay and casting pairings would end, 10 minutes from now unless the same guest is checked back in.",
"warnings": ["Room 4003 was already checked out 30 seconds ago. Send one checkout per departure."]
}
}
Replies also carry the header X-Atrium-Sandbox: 1. Two extra endpoints work with the test key only:
GET /api/sandbox/report: the integration check for your test calls since the last reset (last 24 hours by default,?hours=up to 168). Returns averdict(pass,warningsorfail), a plainsummary, counts, andfindingswith example rooms: guests checked out and back in within 10 minutes, repeated checkouts of the same room, a guest name that changes during a stay, checkouts for guests whose departure date is still in the future, checkouts for rooms with no guest, more than 20 checkouts within a minute (on live every one of those rooms is still signed out, and we are alerted), unknown rooms, bursts of calls and refused calls.POST /api/sandbox/reset: clears your test guest list and the integration check, for a fresh run.
A test key works with check-in, checkout, guest lookups, room status and the two sandbox endpoints. Every other endpoint answers 403 with "code": "TEST_KEY_NOT_SUPPORTED".
Contents
- Testing with a test key: the sandbox, before you go live
- 1. Guest Management — Check-in, check-out, lookup
- 2. Billing & Folio — Charges, payments, folio view
- 3. Room Service Ordering — Create, update, track orders
1. Guest Management
Use these endpoints to check guests in and out. When a guest checks in, the TV in their room instantly shows a personalised welcome message. When they check out, all streaming app logins (Netflix, YouTube, DStv, Disney+, etc.) are automatically wiped from the TV.
Check in a guest (or update an existing guest). If a guest already exists in this room, their details are updated.
| Field | Type | Description | |
|---|---|---|---|
| roomNumber | string | required | Room number only, e.g. "101" (not "101 Bedroom"). Must be a room listed by GET /api/rooms/status, that is a room with at least one TV registered to it. |
| guestName | string | required | Guest full name, e.g. "John Smith" |
| title | string | optional | Mr, Mrs, Ms, Dr, etc. |
| checkIn | string | optional | ISO date, e.g. "2026-04-01". Defaults to today. |
| checkOut | string | optional | ISO date, e.g. "2026-04-05" |
| notes | string | optional | Internal notes |
curl -X POST "https://ota.mndev.co.za/api/guests" \
-H "X-API-Key: htv_YOUR_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
"roomNumber": "101",
"guestName": "John Smith",
"title": "Mr",
"checkIn": "2026-04-01",
"checkOut": "2026-04-05"
}'
{
"ok": true,
"guest": {
"roomNumber": "101",
"guestName": "John Smith",
"title": "Mr",
"checkIn": "2026-04-01",
"checkOut": "2026-04-05",
"notes": "",
"updatedAt": "2026-04-01T08:30:00.000Z"
}
}
The TV in room 101 will instantly update to show "Welcome Mr Smith".
| Status | code | Meaning | |
|---|---|---|---|
| 400 | roomNumber or guestName missing. | ||
| 404 | ROOM_NOT_CONFIGURED | No TV is registered to this room at this property. Nothing is stored. Check the room number against GET /api/rooms/status. Rooms that have no TV return this too and can be skipped. |
{
"ok": false,
"code": "ROOM_NOT_CONFIGURED",
"error": "Room xyz is not configured at this property: no TV is registered to it"
}
Combined rooms. If your property sells two rooms together under one number (for example 3000A for rooms 3000 and 3001), tell us and we link them. A check-in for 3000A then goes to each linked room that has a TV, and the reply carries "roomNumber": "3000A" and "linkedRooms": ["3000", "3001"]. Rooms sold separately are still sent under their own numbers, as before.
Check out a guest. Removes the guest record for this room and triggers automatic cleanup on the TV.
curl -X DELETE -H "X-API-Key: htv_YOUR_KEY_HERE" "https://ota.mndev.co.za/api/guests/101"
{ "ok": true, "signOut": "scheduled" }
signOut says what happens to the room's TVs: "scheduled" means they are signed out 10 minutes from now (see Timing below).
Checking out a room that has no guest is not an error (returns { "ok": true }). A room number that has no TV and no guest record returns 404 with "code": "ROOM_NOT_CONFIGURED", the same body as check-in.
A checkout for a combined room (3000A) ends only the stay that was checked in as 3000A, in each of its rooms, and the reply lists those rooms in "checkedOut". A guest checked in to 3000 on its own is never touched by a 3000A checkout. If no stay was checked in as 3000A, the reply is { "ok": true, "signOut": "none", "linkedRooms": [...], "checkedOut": [] } and nothing changes.
Timing. The guest record and the welcome screen change at once. The streaming sign-out runs 10 minutes later, and another checkout for the same room restarts those 10 minutes. If the same guest is checked in again (POST /api/guests with the same name) before then, the sign-out is dropped and their logins stay. A different guest in the room never cancels it: the previous guest's sign-out still runs, before the new guest starts using the TV. So send a checkout only when the guest has really left: never for a guest who is still staying, and never as part of a resync. To bring us up to date, send check-ins only; they replace the room's guest, so repeating one is harmless.
Bulk checkouts. Real departures never come quickly. If one hotel's key sends more than 20 checkouts within a minute, it looks like a resync by mistake. Atrium still does exactly what it is sent: every room checked out is signed out, 10 minutes after its checkout as usual. Our team is alerted at once, and every reply in the next 15 minutes carries a warning, so your system can stop the run:
{
"ok": true,
"signOut": "scheduled",
"warning": "Checkout recorded. This hotel's system sent 23 checkouts within a minute, which looks like a bulk sync rather than real departures (more than 20 a minute). Atrium signs out every room it is sent a checkout for, so these guests are being signed out of their apps, and Atrium has been alerted. Please send a checkout only when a guest has really left."
}
If you see a warning, stop the run and tell us what happened. A guest checked in again under the same name within 10 minutes of their checkout keeps their logins. A test key gives the same reply, so you can see this before going live.
List all currently checked-in guests.
[
{
"roomNumber": "101",
"guestName": "John Smith",
"title": "Mr",
"checkIn": "2026-04-01",
"checkOut": "2026-04-05",
"notes": "",
"updatedAt": "2026-04-01T08:30:00.000Z"
}
]
Get guest details for a specific room. Returns 404 if no guest is checked in.
curl -H "X-API-Key: htv_YOUR_KEY_HERE" "https://ota.mndev.co.za/api/guests/101"
One call returns every room the system knows about (any room with a registered TV or a checked-in guest): its occupancy, full guest detail, the room's TVs, and casting pairing state. Built for polling from your own backend, for example to reconcile check-ins between systems.
| Field | Type | Description | |
|---|---|---|---|
| checkedIn | boolean | True when a guest is checked in to the room. | |
| guest | object | Guest details, or null when the room is vacant. | |
| roomNumber | string | The room number only, the same value your PMS uses for check-ins (for example 103). A room with several TVs is one entry. | |
| tvs[].location | string | Where in the room the TV is, for example Bedroom or Lounge. null when the TV has no label (usually a single-TV room). | |
| tvs[].online | boolean | The TV reported in within the last 5 minutes. | |
| casting.enabled | boolean | False when the property has no casting appliance configured. | |
| casting.paired | boolean | A guest device is paired to this room. null means the casting appliance has not reported yet: poll again later. May lag a checkout by up to a minute. |
curl -H "X-API-Key: htv_YOUR_KEY_HERE" "https://ota.mndev.co.za/api/rooms/status"
[
{
"roomNumber": "101",
"checkedIn": true,
"guest": {
"guestName": "John Smith",
"title": "Mr",
"checkIn": "2026-04-01",
"checkOut": "2026-04-05",
"preferredLanguage": "en",
"updatedAt": "2026-04-01T08:30:00.000Z"
},
"tvs": [
{ "deviceId": "a1b2c3d4", "location": "Lounge", "tvRole": "primary", "online": true },
{ "deviceId": "e5f6a7b8", "location": "Bedroom", "tvRole": "secondary", "online": true }
],
"casting": { "enabled": true, "paired": true, "pairedSince": "2026-04-01T09:12:00.000Z" }
},
{
"roomNumber": "102",
"checkedIn": false,
"guest": null,
"tvs": [ { "deviceId": "c9d0e1f2", "location": null, "tvRole": "primary", "online": true } ],
"casting": { "enabled": true, "paired": false, "pairedSince": null }
}
]
2. Billing & Folio
Post charges and payments to a guest's folio. Charges are displayed on the TV's Bill View screen.
Post a charge to a guest's bill.
| Field | Type | Description | |
|---|---|---|---|
| roomNumber | string | required | Room number |
| amount | number | required | Charge amount (e.g. 150.00) |
| description | string | optional | e.g. "Minibar — 2x Water" |
| category | string | optional | e.g. "food", "beverage", "laundry" |
| reference | string | optional | External reference ID |
curl -X POST "https://ota.mndev.co.za/api/hotel/billing/charge" \
-H "X-API-Key: htv_YOUR_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
"roomNumber": "101",
"amount": 150.00,
"description": "Room Service — Club Sandwich",
"category": "food"
}'
Record a payment against a guest's bill.
| Field | Type | Description | |
|---|---|---|---|
| roomNumber | string | required | Room number |
| amount | number | required | Payment amount |
| method | string | optional | "card", "cash", "credit" |
| reference | string | optional | Transaction reference |
Get the full folio (bill) for a guest, including all charges, payments, and balance.
{
"charges": [
{ "id": "ch_1", "description": "Room Service — Club Sandwich", "amount": 150.00, "category": "food", "timestamp": "2026-04-01T12:30:00Z" }
],
"payments": [
{ "id": "pay_1", "amount": 150.00, "method": "card", "timestamp": "2026-04-01T14:00:00Z" }
],
"total": 150.00,
"paid": 150.00,
"balance": 0.00,
"currency": "ZAR"
}
Clear a guest's folio on checkout.
3. Room Service Ordering
Manage room service orders placed from the TV or guest's phone.
Create a room service order.
| Field | Type | Description | |
|---|---|---|---|
| roomNumber | string | required | Room number |
| guestName | string | optional | Overrides guest name from check-in |
| items | array | required | Array of order items (see below) |
| notes | string | optional | Special instructions |
| Field | Type | Description | |
|---|---|---|---|
| itemId | string | required | Menu item ID |
| quantity | number | optional | Defaults to 1 |
| notes | string | optional | e.g. "No onions" |
curl -X POST "https://ota.mndev.co.za/api/hotel/restaurant/orders" \
-H "X-API-Key: htv_YOUR_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
"roomNumber": "101",
"items": [
{ "itemId": "item_1", "quantity": 2, "notes": "Extra cheese" },
{ "itemId": "item_2", "quantity": 1 }
],
"notes": "Please deliver before 19:00"
}'
Charge is automatically posted to the guest's folio.
List all room service orders.
Update order status. The guest's TV is notified in real-time.
| Field | Type | Description | |
|---|---|---|---|
| status | string | required | "pending", "confirmed", "preparing", "delivering", "delivered", or "cancelled" |