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, e.g. "101"
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".

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 }

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"

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