FrontDesk Master × MixDorm

Architecture

FrontDesk Master polls MixDorm over HTTPS. MixDorm authorizes each request to an assigned property connection and returns a reservation feed derived from confirmed bookings.

Quickstart

1. Receive MixDorm partner credentials (key id + signing secret or OAuth client).
2. Authenticate each request (signed headers or Bearer token).
3. Confirm your assigned property via GET /properties.
4. Retrieve room and rate mappings via GET /properties/{id}/mappings.
5. Poll GET /reservations?property_id=… incrementally.
6. Persist your synchronization checkpoint and continuation cursor safely.
7. Process modifications and cancellations idempotently by reservation_id.

Environments

All paths in this reference are relative to your assigned base URL. Example full path: {base_url}/api/connectivity/v1/reservations

Authentication

MixDorm Connectivity V1 supports two authentication mechanisms. Use whichever is issued for your pilot.

Signed requests (preferred)

Include these headers on every request:

• X-MixDorm-Key-Id — credential key id
• X-MixDorm-Timestamp — Unix seconds (UTC)
• X-MixDorm-Signature — HMAC-SHA256 hex digest

Canonical signing input (newline-separated):

METHOD
PATH
TIMESTAMP
SHA256_HEX(body)

PATH is the URL path only (no query string). Replay window: 5 minutes.

OAuth Bearer

Exchange credentials at POST /api/connectivity/v1/oauth/token (grant_type: client_credentials), then send Authorization: Bearer ….

GET /reservations

Primary integration endpoint for FrontDesk Master. Returns confirmed, modified, and cancelled reservations for an assigned property.

Request examples

curl -sS -X GET \
  'https://{base_url}/api/connectivity/v1/reservations?property_id={property_id}&limit=50' \
  -H 'X-MixDorm-Key-Id: {key_id}' \
  -H 'X-MixDorm-Timestamp: {unix_seconds}' \
  -H 'X-MixDorm-Signature: {hmac_sha256_hex}'

Response schema

Each reservation in reservations[] contains the fields below. Internal MixDorm identifiers are not exposed.

Envelope

Reservation object

Reservation lifecycle

• reservation_id remains stable across modifications and cancellation.
• Modifications appear with a later updated_at on incremental poll.
• Cancelled reservations remain in the feed with status: cancelled and cancelled: true.
• Cancellation does not remove the reservation from subsequent sync — process idempotently.

Incremental synchronization

Poll with updated_since set to your last successfully processed checkpoint (ISO-8601 UTC). Reservations are ordered deterministically for pagination; use cursor to continue pages.

• Safe retry: Re-fetching the same page is safe; upsert by reservation_id.
• Duplicate tolerance: Same reservation may appear if updated again — always upsert.
• Checkpoint: Advance only after a page is fully processed.
• Modifications & cancellations: Discovered via later updated_at values on the same id.

checkpoint = load_checkpoint()  // ISO-8601 UTC, default epoch

loop forever:
  cursor = null
  repeat:
    response = GET /reservations(
      property_id = CONNECTION_ID,
      updated_since = checkpoint,
      cursor = cursor,
      limit = 50
    )
    if response.status != 200:
      backoff_and_retry()
      break inner

    for reservation in response.reservations:
      upsert_idempotently(reservation)
      checkpoint = max(checkpoint, reservation.updated_at)

    cursor = response.pagination.next_cursor
  until not response.pagination.has_more

  save_checkpoint(checkpoint)
  sleep(POLL_INTERVAL_SECONDS)

Pagination

When pagination.has_more is true, pass pagination.next_cursor as the cursor query parameter. Default limit is 50 (max 100).

GET /api/connectivity/v1/reservations?property_id={property_id}&updated_since=2026-09-01T00:00:00.000Z&limit=2

→ pagination.has_more: true, next_cursor: "…"

GET /api/connectivity/v1/reservations?property_id={property_id}&cursor={next_cursor}

Examples

{
  "schema_version": "1.0.0",
  "property_id": "prp_conn_example",
  "external_property_id": "fdm_prop_pilot_001",
  "reservations": [
    {
      "reservation_id": "MXD-90001",
      "property_id": "prp_conn_example",
      "external_property_id": "fdm_prop_pilot_001",
      "status": "confirmed",
      "cancelled": false,
      "check_in": "2026-12-10",
      "check_out": "2026-12-12",
      "currency": "INR",
      "total_amount": 1500,
      "paid_amount": 500,
      "guest_count": 2,
      "guest": {
        "first_name": "FDM",
        "last_name": "Test Guest",
        "full_name": "FDM Test Guest",
        "email": "fdm-test@example.invalid",
        "phone": "+910000000000"
      },
      "accommodation": [
        {
          "external_room_id": "fdm_room_dorm_a",
          "external_rate_plan_id": "fdm_rate_standard",
          "rate_plan_name": "Standard",
          "quantity": 2,
          "beds": 2,
          "bed_type": "bunk",
          "occupancy": {
            "adults": 2,
            "children": 0
          },
          "is_dorm": true
        }
      ],
      "updated_at": "2026-09-01T10:00:00.000Z",
      "created_at": "2026-09-01T09:55:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "count": 1,
    "has_more": false,
    "next_cursor": null
  }
}

Property & inventory mapping

Map MixDorm inventory to your property, room, and rate-plan codes before go-live.

Returns entity_type (property, room, rate_plan), mixdorm_id, and external_id. Reservation responses expose external_* ids when mapped; unmapped values are null.

Partners may write sandbox mappings via POST /properties/{id}/mappings (requires Idempotency-Key; sandbox only). Production mappings are ops-provisioned.

Errors

Errors use { schema_version, error: { code, message, correlation_id } }. Per-reservation issues may appear in errors[] while the page still returns 200.

Retry & reliability

• GET /reservations is safe to retry — no side effects.
• On timeout or 5xx, retry with exponential backoff.
• On 401, refresh credentials or token before retrying.
• On 403, verify property_id — do not retry blindly.
• Persist cursor/checkpoint only after successful page processing.
• Rate limiting (429) is implemented — backoff and retry.

Dates, times & currency

• updated_at, created_at: ISO-8601 UTC timestamps.
• check_in, check_out: calendar dates YYYY-MM-DD.
• currency: ISO-4217 (e.g. INR).
• total_amount: total booking value; paid_amount: amount collected online. No card or gateway data is returned.

Pilot integration checklist

• Credentials issued by MixDorm ops
• Property connection assigned (GET /properties)
• Room mappings verified (GET /properties/{id}/mappings)
• Rate plan mappings verified
• Initial full pull completed
• New reservation appears on incremental poll
• Modification detected with same reservation_id
• Cancellation detected — reservation remains in feed with status cancelled
• Cross-property access denied (403)
• Production approval requested via POST /production/request

Optional connectivity features

MixDorm also supports webhook-style reservation events. FrontDesk Master does not need these endpoints for its pull-based workflow:

• GET /api/connectivity/v1/reservations/events — event index (push fallback)
• POST /api/connectivity/v1/reservations/ack — acknowledge delivered events

API Specification

Machine-readable OpenAPI 3.0 specification is available from the Connectivity API when authenticated:

Contact team@mixdorm.com for pilot credentials and base URL assignment.