Creating Bookings

You drive a guest's whole access lifecycle — grant on booking, revoke on cancel/checkout — by sending booking events to Mosler Direct. One endpoint handles create, update, and cancel; the action field says which.

Events are processed asynchronously: Mosler accepts your event with 202 Accepted and an eventId, then provisions device access in the background. You can poll the event to confirm completion.

v3 → v4 difference: v3 used synchronous REST — POST /api/v3/booking returned the created booking directly. v4 is fully asynchronous: the 202 response only confirms the event was accepted; you must poll the eventId or wait for a push notification to know when access is ready. The reference_id you choose replaces v3's internal booking IDs as the key used across the entire lifecycle — create, update, cancel, and credential retrieval all key off this same value.

---

Endpoint

POST https://webhook.mosler.in/webhook/t/<your-token>

The token in the URL encodes your company, site, and provider — no other auth is needed. Prefer not to put the credential in the URL? Use the header alternative: POST /webhook/generic with apikey, X-Company-Id, and X-Site-Id.

---

Request body

Guest contact drives delivery. If you want Mosler to send the credential straight to the guest (see Delivering Access), include guest.phone and/or guest.email.

---

Action mapping

The action string is normalised — casing and separators (_, -) are ignored.

---

Create a booking

curl -X POST https://webhook.mosler.in/webhook/t/<your-token> \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "RES-20250718-001",
    "action": "create",
    "room_number": "101",
    "check_in": "2025-07-18T14:00:00.000Z",
    "check_out": "2025-07-22T11:00:00.000Z",
    "guest": {
      "name": "Jane Smith",
      "email": "jane.smith@example.com",
      "phone": "+919991234567"
    },
    "access_type": "EKEY"
  }'

Success — 202 Accepted

The event is validated, stored, and queued. Provisioning happens asynchronously.

{
    "success": true,
    "eventId": "a3f9d2e1-84c7-4b56-9f13-0d2e4c8a1b7f",
    "status": "QUEUED",
    "message": "Event received and queued for processing"
}

Save the eventId.

Validation error — 400 Bad Request

{
    "success": false,
    "errors": [
        "reference_id is required",
        "check_in or start_date is required"
    ],
    "message": "Invalid payload"
}

Duplicate — 202 (idempotent)

If the same reference_id and action arrive within 60 seconds, Mosler returns the original event instead of processing it twice.

{
    "success": true,
    "eventId": "a3f9d2e1-84c7-4b56-9f13-0d2e4c8a1b7f",
    "status": "QUEUED",
    "message": "Duplicate event detected, returning existing event"
}

---

Update or cancel

Send the same reference_id with a different action. For a cancel, room and date fields are optional — Mosler looks up the booking by reference_id and revokes its access.

curl -X POST https://webhook.mosler.in/webhook/t/<your-token> \
  -H "Content-Type: application/json" \
  -d '{ "reference_id": "RES-20250718-001", "action": "cancel" }'

To change dates or room, send action: "update" (or a date-change/room-move action) with the new values and the original reference_id.

---

Tracking an event

Provisioning is asynchronous. Poll the event by its eventId to confirm it reached COMPLETED. In production, wait ~5 seconds before the first check.

curl https://webhook.mosler.in/webhook/events/a3f9d2e1-84c7-4b56-9f13-0d2e4c8a1b7f \
  -H "apikey: YOUR_MOSLER_API_KEY"

{
    "success": true,
    "eventId": "a3f9d2e1-84c7-4b56-9f13-0d2e4c8a1b7f",
    "status": "COMPLETED",
    "message": null
}

To see every event for a booking (create, cancel, …) use GET /webhook/events/reference/:referenceId. Full status semantics, retries, and the dead-letter flow are documented in Event Lifecycle.

Once status is COMPLETED, the credential exists. Fetch it via Retrieving Access, or let Mosler push it for you — see Delivering Access.

---

Common errors