Retrieving Access

Once a booking event reaches COMPLETED, Mosler has provisioned the guest's credential. This page is the pull half of the loop — the API your system calls to read that credential. (To have Mosler push it to you or the guest instead, see Delivering Access.)

All endpoints authenticate with your company-scoped API key in the apikey header and are looked up by the booking's referenceId.

Credential types at a glance

List a booking's credentials

Returns all active credentials for a booking in a human-readable form.

GET /api/v4/bookings/:referenceId/access

Response

Each access[] entry:

E-key: lockData and lockMac are returned inline here, so a single call to this endpoint gives you every credential for a booking. The dedicated GET …/access/e-key endpoint returns the same two values (plus locationType) and remains available — use it if you only need e-key material and want a smaller response.

Example — passcode booking

{
    "success": true,
    "booking": {
        "id": "6576fe78632cfff91c62a3c2",
        "referenceId": "RES-20250718-001",
        "status": "active",
        "startDate": "2025-08-01T08:30:00.000Z",
        "endDate": "2025-08-05T05:30:00.000Z"
    },
    "access": [
        {
            "deviceId": "63f79d8b8c0d1a55c3172f3c",
            "deviceName": "Room 101 Door",
            "roomNumber": "101",
            "bedNumber": null,
            "siteName": "Delhi",
            "validFrom": "2025-08-01T08:30:00.000Z",
            "validUntil": "2025-08-05T05:30:00.000Z",
            "type": "passcode",
            "passcode": "482910"
        }
    ]
}

Example — multiple locks (door + cabinet)

{
    "success": true,
    "booking": { "referenceId": "RES-20250718-002", "status": "active" },
    "access": [
        {
            "deviceName": "Room 101 Door",
            "roomNumber": "101",
            "bedNumber": null,
            "type": "passcode",
            "passcode": "482910"
        },
        {
            "deviceName": "Bed A Cabinet",
            "roomNumber": null,
            "bedNumber": "A",
            "type": "passcode",
            "passcode": "391047"
        }
    ]
}

Example — booking with both passcode and e-key

A booking created with "access_type": ["PASSCODE", "EKEY"] returns one entry per credential type per lock, each carrying its own secret:

{
    "success": true,
    "booking": { "referenceId": "RES-20250718-003", "status": "active" },
    "access": [
        {
            "deviceId": "63f79d8b8c0d1a55c3172f3c",
            "deviceName": "Room 101 Door",
            "roomNumber": "101",
            "bedNumber": null,
            "type": "passcode",
            "passcode": "482910"
        },
        {
            "deviceId": "63f79d8b8c0d1a55c3172f3c",
            "deviceName": "Room 101 Door",
            "roomNumber": "101",
            "bedNumber": null,
            "type": "ekey",
            "lockData": "Rz7oNSAH1No3YXRiG0j8FKB3xBjhuILrkTjWkOMw...",
            "lockMac": "AA:BB:CC:DD:EE:FF"
        }
    ]
}

Get e-key lock data

Returns the data a mobile app needs to operate an e-key (Bluetooth) for the booking. Pass lockData to the Mobile Key SDK as-is — it is opaque to your app. The lock manufacturer is abstracted by Mosler; your integration does not need to know which vendor a given lock uses.

This is an e-key-only view of the same data. lockData and lockMac are also returned inline by GET …/access, so you don't need both calls — use whichever fits your flow.

GET /api/v4/bookings/:referenceId/access/e-key

v3 → v4 difference: In v3 the equivalent endpoint was GET /api/v3/booking/access/ekey/:bookingId, keyed by the internal bookingId. v4 keys by referenceId (the string you sent when creating the booking), wraps results per-device in a standard envelope, and adds lockMac alongside lockData. The field names lockData and lockMac are the same as v3.

Response

data contains one entry per lock the booking has an e-key on:

{
    "error": false,
    "code": 7005,
    "message": "E-keys retrieved successfully",
    "data": [
        {
            "lockData": "Rz7oNSAH1No3YXRiG0j8FKB3xBjhuILrkTjWkOMw...",
            "lockMac": "AA:BB:CC:DD:EE:FF",
            "deviceId": "63f79d8b8c0d1a55c3172f3c",
            "deviceName": "Room 101 Door",
            "locationType": "door",
            "roomNumber": "101",
            "bedNumber": null,
            "siteName": "Delhi",
            "validFrom": "2025-08-01T08:30:00.000Z",
            "validUntil": "2025-08-05T05:30:00.000Z"
        }
    ]
}

Pass lockData and lockMac to the Mobile Key SDK when initialising the lock for a Bluetooth operation. Both values are required for SDK initialisation — store them like credentials.

Remote unlock

Triggers a server-side unlock on a lock for an active booking — no guest credential required. Designed for staff and kiosk flows: a front-desk attendant clicks a button and the door opens.

POST /api/v4/bookings/:referenceId/unlock

Request body

Validation

• Booking must exist and be active.
• Current time must fall within the booking's check-in → check-out window.
• A device must be bound to the booking's room (or bed).

Response

{
    "message": "Remote unlock successful",
    "error": false,
    "data": {
        "deviceId": "63f79d8b8c0d1a55c3172f3c",
        "deviceName": "Room 101 Door",
        "unlockTime": "2025-08-02T11:04:33.000Z"
    }
}

Every attempt — success or failure — is written to the device's access log, visible in the Mosler Admin Portal under Devices → Access Logs.

Error responses