Atrium / Documentation / API Reference
Support Portal

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 a verdict (pass, warnings or fail), a plain summary, counts, and findings with 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".

This documentation is for testing purposes only. The base URL and customer ID may change before production deployment.

Contents

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.

POST /api/guests

Check in a guest (or update an existing guest). If a guest already exists in this room, their details are updated.

Request Body
FieldTypeDescription
roomNumberstringrequiredRoom 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.
guestNamestringrequiredGuest full name, e.g. "John Smith"
titlestringoptionalMr, Mrs, Ms, Dr, etc.
checkInstringoptionalISO date, e.g. "2026-04-01". Defaults to today.
checkOutstringoptionalISO date, e.g. "2026-04-05"
notesstringoptionalInternal notes
Example
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"
  }'
Response
{
  "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".

Errors
StatuscodeMeaning
400roomNumber or guestName missing.
404ROOM_NOT_CONFIGUREDNo 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.

DELETE /api/guests/{roomNumber}

Check out a guest. Removes the guest record for this room and triggers automatic cleanup on the TV.

Example
curl -X DELETE -H "X-API-Key: htv_YOUR_KEY_HERE" "https://ota.mndev.co.za/api/guests/101"
Response
{ "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.

On checkout, the TV in this room will automatically: - Clear Netflix login - Clear YouTube login - Clear DStv / DStv Now login - Clear Disney+ login - Clear Amazon Prime Video login - Clear Spotify login - Clear Apple TV login - Reset the welcome screen to default

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.

GET /api/guests

List all currently checked-in guests.

Response
[
  {
    "roomNumber": "101",
    "guestName": "John Smith",
    "title": "Mr",
    "checkIn": "2026-04-01",
    "checkOut": "2026-04-05",
    "notes": "",
    "updatedAt": "2026-04-01T08:30:00.000Z"
  }
]
GET /api/guests/{roomNumber}

Get guest details for a specific room. Returns 404 if no guest is checked in.

Example
curl -H "X-API-Key: htv_YOUR_KEY_HERE" "https://ota.mndev.co.za/api/guests/101"
GET /api/rooms/status

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.

FieldTypeDescription
checkedInbooleanTrue when a guest is checked in to the room.
guestobjectGuest details, or null when the room is vacant.
roomNumberstringThe room number only, the same value your PMS uses for check-ins (for example 103). A room with several TVs is one entry.
tvs[].locationstringWhere in the room the TV is, for example Bedroom or Lounge. null when the TV has no label (usually a single-TV room).
tvs[].onlinebooleanThe TV reported in within the last 5 minutes.
casting.enabledbooleanFalse when the property has no casting appliance configured.
casting.pairedbooleanA 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.
Example
curl -H "X-API-Key: htv_YOUR_KEY_HERE" "https://ota.mndev.co.za/api/rooms/status"
Response
[
  {
    "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 }
  }
]
Casting state reflects the appliance's most recent report. Rooms are listed when they have a registered TV or a checked-in guest; a room with neither does not appear.

2. Billing & Folio

Post charges and payments to a guest's folio. Charges are displayed on the TV's Bill View screen.

POST /api/hotel/billing/charge

Post a charge to a guest's bill.

FieldTypeDescription
roomNumberstringrequiredRoom number
amountnumberrequiredCharge amount (e.g. 150.00)
descriptionstringoptionale.g. "Minibar — 2x Water"
categorystringoptionale.g. "food", "beverage", "laundry"
referencestringoptionalExternal reference ID
Example
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"
  }'
POST /api/hotel/billing/payment

Record a payment against a guest's bill.

FieldTypeDescription
roomNumberstringrequiredRoom number
amountnumberrequiredPayment amount
methodstringoptional"card", "cash", "credit"
referencestringoptionalTransaction reference
GET /api/hotel/pms/folio/{roomNumber}

Get the full folio (bill) for a guest, including all charges, payments, and balance.

Response
{
  "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"
}
POST /api/hotel/billing/clear/{roomNumber}

Clear a guest's folio on checkout.

3. Room Service Ordering

Manage room service orders placed from the TV or guest's phone.

POST /api/hotel/restaurant/orders

Create a room service order.

FieldTypeDescription
roomNumberstringrequiredRoom number
guestNamestringoptionalOverrides guest name from check-in
itemsarrayrequiredArray of order items (see below)
notesstringoptionalSpecial instructions
Item Object
FieldTypeDescription
itemIdstringrequiredMenu item ID
quantitynumberoptionalDefaults to 1
notesstringoptionale.g. "No onions"
Example
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.

GET /api/hotel/restaurant/orders

List all room service orders.

PUT /api/hotel/restaurant/orders/{id}

Update order status. The guest's TV is notified in real-time.

FieldTypeDescription
statusstringrequired"pending", "confirmed", "preparing", "delivering", "delivered", or "cancelled"