The hotel already knows who’s coming. Let the technology know, too.
The front desk has reservations in the PMS, the heating system has its own schedule, and the locks have their own administration. When a stay is extended or a guest changes rooms, the same information must be updated in multiple places. Automation can take over these repetitive tasks.
Ellipse PMS makes data on stays, occupancy, and currently valid PIN codes available via API. The integration service regularly retrieves this data and converts it into commands for a specific access control system, heating control, or smart home system.
Any system that allows external control via a suitable interface or gateway can be connected. After a one-time setup, data exchange can occur automatically. Compatibility and the scope of control must be verified for each specific device; the Ellipse API itself does not replace the manufacturer’s control software.
For hotels, this means less manual data entry, a single source of information, and the ability to prepare rooms based on guest stays. Actual energy and time savings must be evaluated during operation. The API provides the data; specific temperatures and operating rules are set by the integrator in collaboration with the hotel.
Four Calls, One Data Source
The integration retrieves data from the hotel’s URL https://hotel.example.com/api/stays/. The domain is an example; upon deployment, it will be replaced with the specific hotel’s URL. All described calls use the GET method, HTTP Basic authentication, and the stays:read permission. A successful response has a status code of 200 and a MIME type of application/json.
The existing integration retrieves the heatmap, pinmap, and list every minute, and the room pairs map once per hour. This is an example of usage, not a guarantee of immediate delivery. The change will take effect upon the next successful retrieval and processing in the target system.
curl --fail --silent --show-error \
--connect-timeout 5 --max-time 15 \
--user "$ELLIPSE_USER:$ELLIPSE_PASSWORD" \
"https://hotel.example.com/api/stays/?type=roompairs"The environment variables in the example represent the assigned login credentials. The requests are sent to the server or integration gateway via HTTPS. Login credentials should not be included in public JavaScript or in the URL.
The most important part is the room mapping. The key "12" in the response is the ID of a specific unit on the hotel layout. name: "202" is the room number, and id_room: "2" indicates the room category. The category is not the lock ID. Therefore, the following relationship is established in the integration: unit 12 → room 202 → specific lock and thermostat.
Heating: Plan Based on Occupied Nights
A call to `heatmap` returns all active units and the schedule for today plus the next six days. A ` status: 1 ` value indicates an occupied night; `status: 0 ` indicates an unoccupied night. The day a guest is checking out is not considered an occupied night.
GET /api/stays/?type=heatmapThe sample response is limited to one unit; it includes all seven dates:
{
"12": {
"id": "12", "name": "202", "id_room": "2",
"statuses": [
{ "date": "2026-10-08", "status": 1 },
{ "date": "2026-10-09", "status": 0 },
{ "date": "2026-10-10", "status": 1 },
{ "date": "2026-10-11", "status": 1 },
{ "date": "2026-10-12", "status": 1 },
{ "date": "2026-10-13", "status": 0 },
{ "date": "2026-10-14", "status": 0 }
]
}
}Practical scenario: Based on future occupancy, the control system sets up a comfort mode before arrival and a setback mode after departure. Lead time and temperatures are target control rules, not values returned by this API.
Note regarding the morning of the departure day: " status": 0 does not mean that the guest has already left. For timing decisions, also use data on the length of stay and departure time. The heatmap is not a sensor for detecting human presence in the room; therefore, do not turn off the lights or heating based solely on a single occupancy value.
Access: Currently Valid PIN
A call to `pinmap` returns the current PIN for each unit. The PIN becomes active on the arrival date starting at the reservation’s arrival time; if the reservation does not specify a time, the hotel’s default time is used. On the departure date, it remains valid until the departure time.
GET /api/stays/?type=pinmap{
"12": {
"id": "12", "name": "202",
"id_room": "2", "pin": "1234"
},
"13": {
"id": "13", "name": "203",
"id_room": "2", "pin": "5678"
},
"14": {
"id": "14", "name": "204",
"id_room": "2", "pin": "0"
}
}A PIN of "0" indicates an available room without valid guest access. The integration must revoke the corresponding guest permission; it must not set the number 0 as the access code. Other PIN codes are four-digit strings. Preserve them as text so that any leading zero is not lost.
Same-day guest change: if the new guest’s check-in time has already passed, the API will return the PIN for the new reservation. The integration service must apply the change to the correct lock and verify the result of the update. A successful API response does not confirm that the device has been successfully configured.
This call provides the current status, not a future schedule of code validity. The data does not specify payment conditions or a completed online check-in. If the hotel requires such conditions, they must be separately verified and resolved during the access issuance process.
Stays and Room Map: Context for Automation
When the integration requires stay dates and times, it uses the list. The date parameter is required and has the format YYYY-MM-DD. With acmd=1, all stays listed on the schedule for a given day are returned, even those prior to check-in. Without it—that is, when `acmd=0`—only rooms where the guest is already staying will be returned.
GET /api/stays/?type=list&date=2026-10-08&acmd=1[
{
"room": "13", "roomname": "203",
"reservation": "100001", "lang": "sk",
"name": "First Name", "surname": "Last Name",
"arrival": "2026-10-07",
"departure": "2026-10-09",
"a-time": "15:00:00", "d-time": "10:00:00",
"pin": "5678", "phone": "+421900000000",
"out_of_order": false
}
]"room " identifies the unit. a-time and d-time are the arrival and departure times for the given room. out_of_order: true indicates a technical closure, not temperature. Do not use the PIN in the stay list as proof of current validity; pinmap is used for that purpose.
If the date is missing or incorrect, the API returns status code 400 and the response {"error":"Date"}. The date must change during regular retrievals; the sample date must not remain fixed in the production integration.
The roompairs map associates a unit ID with a room number. Here is a snippet of the response:
GET /api/stays/?type=roompairs{ "12": "202", "13": "203", "14": "204", "21": "303" }Load the map at startup and refresh it periodically. When moving a guest or changing the hotel’s configuration, also verify the links to physical devices.
How Data Leads to Reliable Automation
On the Ellipse side, all you need to do is read the unified API. The integration service then compares the received state with the last successfully applied state and makes the necessary changes via the manufacturer’s interface. Repeatedly loading the same state should not create duplicate access codes or unnecessary commands.
Recommended integrator procedure:
- Obtain access to the hotel API with the
stays:readpermission and verify the HTTPS connection. - Map units from
roompairsto specific locks and controllers. - Retrieve the required statuses, and check both the HTTP response and the JSON structure.
- Evaluate any differences and apply them via the target system’s interface.
- Confirm execution, save the time of the last successful synchronization, and report any errors.
An API outage is not considered a “vacant room.” Do not interpret an error, timeout, or incomplete response as a pin value of “0” or as a command to turn off the heating. Set the maximum data age, outage rules, and manual intervention in advance. When accessing the system, the operation must also handle expiration in the event of unavailable synchronization; the current pinmap itself does not contain an expiration time.
For heating, respect local device security and operational minimums. For accesses, guest synchronization does not change service or emergency permissions. Do not store API passwords and PIN codes in standard logs. From the endpoint, process only the data that the integration requires.
Before deployment, test early check-in, late check-out, stay extensions, room changes, guest changes on the same day, technical maintenance windows, and network outages. Confirm the time zone, cutoff times, and behavior upon cancellation of a stay with the API implementer; the provided documentation does not specify these in detail.
The same data can serve as the basis for other smart home scenarios, such as setting up a room’s comfort mode. Their implementation depends on the capabilities of the target system. The described API reads stay data; commands to devices are executed by the integration layer.
Would you like to integrate your technologies with Ellipse? Send us the name and model of your access control system or control system, along with your integrator’s contact information. Together, we’ll review the interface, room mapping, and the appropriate controller. Schedule a consultation or check out the Ellipse hotel system.
