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

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

1. Guest Management — Check-in, check-out, lookup
2. Billing & Folio — Charges, payments, folio view
3. Room Service Ordering — Create, update, track orders
4. PMS Configuration — Connect your property management system

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

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

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

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"
}

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 }

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.

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

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.

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.

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.

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

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.

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 /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.

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

Item Object

Field	Type		Description
itemId	string	required	Menu item ID
quantity	number	optional	Defaults to 1
notes	string	optional	e.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.

Field	Type		Description
status	string	required	"pending", "confirmed", "preparing", "delivering", "delivered", or "cancelled"

4. PMS Configuration

Connect your property management system for automatic guest sync and folio posting.

GET /api/hotel/pms/adapters

List available PMS adapter types and their required configuration fields. Currently supported: Mews, Opera, Sihot, and a generic REST adapter.

PUT /api/hotel/pms/config

Configure PMS connection credentials and settings.

Field	Type		Description
pmsType	string	required	Adapter type from /api/hotel/pms/adapters
apiUrl	string	required	PMS API base URL
hotelCode	string	optional	Hotel identifier in PMS
apiKey	string	optional	API key / token
syncGuests	boolean	optional	Auto-sync guest check-ins
postCharges	boolean	optional	Auto-post room service charges

POST /api/hotel/pms/test

Test your PMS connection with the current configuration.

Atrium — API Documentation

Authentication

Base URL

Contents

1. Guest Management

2. Billing & Folio

3. Room Service Ordering

4. PMS Configuration