Developers / Partner Connectivity / FrontDesk Master

FrontDesk Master × MixDorm

ARI push + Reservation Pull

FrontDesk Master pushes availability, inventory, rates, and restrictions to MixDorm via POST /ari, and retrieves new, modified, and cancelled reservations via incremental GET /reservations polling.

RESTJSONAPI v1HTTPS

Documentation for API v1.0.0. Pilot access is provisioned by MixDorm — base URL and credentials are assigned for your sandbox application.

Architecture

Two directions on the same Connectivity V1 surface. MixDorm authorizes each request to an assigned non-live property connection.

FrontDesk MasterChannel ManagerPOST /ariMixDorm ConnectivityPartner API v1GET /reservationsReservation feedNEW · MODIFY · CANCELHTTPS
ARI: FrontDesk Master → MixDorm via POST /ari (Idempotency-Key required, max 200 items; invalid item rejects before application).
Reservations: MixDorm → FrontDesk Master via GET /reservations (no FDM callback required for pull). Optional webhooks exist but are not required for the pilot.

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. Push sample ARI with POST /ari + Idempotency-Key.
  6. Poll GET /reservations?property_id=… every 60s.
  7. Persist your synchronization checkpoint and continuation cursor safely.
  8. Process modifications and cancellations idempotently by reservation_id.

Environments

Pilot model: Same Connectivity API host + sandbox application credentials + non-live MixDorm property. A separate api-sandbox hostname is not required.

Base URL: Provided with pilot credentials (typically the MixDorm API host under /api/connectivity/v1)

Example paths: {base_url}/api/connectivity/v1/ari and {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):

text
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 …. Access tokens expire in ~15 minutes (expires_in: 900).

POST /ari

Push availability, inventory, rates, and restrictions. Scope: connectivity:ari:write. Required header: Idempotency-Key. Max 200 items per request. An invalid item causes the request to be rejected before application; partial validation success is not returned.

POST/api/connectivity/v1/ari

Item fields

GroupFieldTypeNullableDescriptionExample
Identityexternal_property_idstringNoYour property code (must be mapped)fdm_prop_pilot_001
Identityexternal_room_idstringNoYour room code (must be mapped)fdm_room_dorm_a
Identityexternal_rate_plan_idstringNoYour rate-plan code (must be mapped)fdm_rate_standard
Datesstart_datestring (date)NoFirst calendar date YYYY-MM-DD (inclusive)2026-10-01
Datesend_datestring (date)NoLast calendar date YYYY-MM-DD (inclusive)2026-10-03
InventoryinventoryintegerYesAvailable units (≥ 0). Optional on restriction-only rows5
RatesratenumberYesNightly rate (≥ 0). Currency required when rate > 0899
RatescurrencystringYesISO-4217; required when rate > 0; must match property currencyINR
RestrictionsclosedbooleanYesStop-sell / closed for salefalse
Restrictionsclosed_to_arrivalbooleanYesCTA — no arrivals that nightfalse
Restrictionsclosed_to_departurebooleanYesCTD — no departures that nightfalse
Restrictionsmin_stayintegerYesMinimum length of stay (≥ 0)1
Restrictionsmax_stayintegerYesMaximum length of stay (≥ 0)14
  • end_date is inclusive (calendar dates, UTC-safe day keys).
  • When rate > 0, currency is required and must match the property currency.
  • Live MixDorm properties are blocked (pilot_safety / 403).
  • Unmapped property/room/rate-plan rejects the batch (400).
  • Same Idempotency-Key + same body → safe replay; same key + different body → 409.
  • HMAC PATH is /api/connectivity/v1/ari (no query string). Sign the raw JSON body bytes.

Request example

bash
curl -sS -X POST \
  'https://{base_url}/api/connectivity/v1/ari' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: {unique_key}' \
  -H 'X-MixDorm-Key-Id: {key_id}' \
  -H 'X-MixDorm-Timestamp: {unix_seconds}' \
  -H 'X-MixDorm-Signature: {hmac_sha256_hex}' \
  -d '{
    "items": [{
      "external_property_id": "fdm_prop_pilot_001",
      "external_room_id": "fdm_room_dorm_a",
      "external_rate_plan_id": "fdm_rate_standard",
      "start_date": "2026-10-01",
      "end_date": "2026-10-03",
      "inventory": 5,
      "rate": 899,
      "currency": "INR",
      "closed": false
    }]
  }'

ARI examples

json
{
  "items": [
    {
      "external_property_id": "fdm_prop_pilot_001",
      "external_room_id": "fdm_room_dorm_a",
      "external_rate_plan_id": "fdm_rate_standard",
      "start_date": "2026-10-01",
      "end_date": "2026-10-03",
      "inventory": 5,
      "rate": 899,
      "currency": "INR",
      "closed": false,
      "closed_to_arrival": false,
      "closed_to_departure": false,
      "min_stay": 1,
      "max_stay": 14
    }
  ]
}
Open inventory

GET /reservations

Primary reservation endpoint for FrontDesk Master. Returns pending, confirmed, modified, and cancelled reservations for an assigned property. Scope: connectivity:reservations:read.

GET/api/connectivity/v1/reservations
ParameterTypeRequiredDescriptionExample
property_idstringRequiredAssigned property connection id from GET /propertiesprp_conn_example
updated_sincestring (ISO-8601 UTC)OptionalLower bound on reservation updated_at for incremental sync2026-09-01T00:00:00.000Z
cursorstringOptionalOpaque token — echo pagination.next_cursor exactly; do not decode or constructeyJ1IjoiMjAyNi0wOS0wMVQxMDowMDowMC4wMDBaIiwiaSI6Ik1YRC05MDAwMSJ9
limitintegerOptionalPage size (1–100, default 50)50

Request examples

bash
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

GroupFieldTypeNullableDescriptionExample
Envelopeschema_versionstringNoAPI schema version1.0.0
Envelopeproperty_idstringNoQueried connection idprp_conn_example
Envelopeexternal_property_idstringNoYour property codefdm_prop_pilot_001
EnvelopereservationsarrayNoReservation objects for this page—
EnvelopeerrorsarrayNoPer-reservation serialization issues (page still returns)—
Envelopepagination.limitintegerNoRequested page size50
Envelopepagination.countintegerNoReservations in this page1
Envelopepagination.has_morebooleanNoTrue if more pages existfalse
Envelopepagination.next_cursorstring|nullNoPass as cursor on next requestnull

Reservation object

GroupFieldTypeNullableDescriptionExample
Identityreservation_idstringNoStable MixDorm booking reference (e.g. MXD-90001)MXD-90001
Propertyproperty_idstringNoAssigned connection idprp_conn_example
Propertyexternal_property_idstringNoYour mapped property codefdm_prop_pilot_001
Staycheck_instring (date)NoArrival date YYYY-MM-DD2026-12-10
Staycheck_outstring (date)NoDeparture date YYYY-MM-DD2026-12-12
LifecyclestatusenumNopending | confirmed | cancelledconfirmed
LifecyclecancelledbooleanNoTrue when reservation is cancelledfalse
Lifecycleupdated_atstring (ISO-8601 UTC)NoLast change timestamp — use for checkpointing2026-09-01T10:00:00.000Z
Lifecyclecreated_atstring (ISO-8601 UTC)YesOriginal creation time2026-09-01T09:55:00.000Z
Guestguest_countintegerYesBooking-level guest count2
Guestguest.first_namestringYesTraveller first nameFDM
Guestguest.last_namestringYesTraveller last nameTest Guest
Guestguest.full_namestringYesFull name when providedFDM Test Guest
Guestguest.emailstringYesContact emailfdm-test@example.invalid
Guestguest.phonestringYesContact phone+910000000000
FinancialscurrencystringNoISO-4217 currency codeINR
Financialstotal_amountnumberYesTotal booking value1500
Financialspaid_amountnumberYesAmount collected online500
Accommodationaccommodation[]arrayNoOne or more room/rate lines—
Accommodationaccommodation[].external_room_idstringYesMapped room id (null if unmapped)fdm_room_dorm_a
Accommodationaccommodation[].external_rate_plan_idstringYesMapped rate plan idfdm_rate_standard
Accommodationaccommodation[].rate_plan_namestringYesRate plan display nameStandard
Accommodationaccommodation[].quantityintegerNoUnits booked (beds/rooms)2
Accommodationaccommodation[].bedsintegerYesBed count when applicable2
Accommodationaccommodation[].bed_typestringYesBed type labelbunk
Accommodationaccommodation[].room_numberstringYesRoom number when known—
Accommodationaccommodation[].room_typestringYesRoom type label—
Accommodationaccommodation[].is_dormbooleanNoDorm/shared semantics hinttrue
Accommodationaccommodation[].occupancy.adultsintegerNoAdult count2
Accommodationaccommodation[].occupancy.childrenintegerNoChild count0
Stayspecial_requestsstringYesGuest special requests—

Reservation lifecycle

Confirmed
Modified
Cancelled
  • 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

Recommended poll interval: 60 seconds. Poll with updated_since set to your last successfully processed checkpoint (ISO-8601 UTC). Treat cursor as an opaque token — do not decode, modify, or construct it. When pagination.next_cursor is returned, send that exact value on the next request. Overlapping polls are safe if you upsert by reservation_id.

  • 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. Keep updated_since across cycles.
  • After downtime: Resume from last saved checkpoint; page with echoed cursors until has_more is false.
  • Modifications & cancellations: Discovered via later updated_at values on the same id.
text
checkpoint = load_checkpoint()  // ISO-8601 UTC, default epoch
POLL_INTERVAL_SECONDS = 60

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)
Recommended polling algorithm

Pagination

When pagination.has_more is true, pass pagination.next_cursor verbatim as the cursor query parameter. Default limit is 50 (max 100). Do not invent or edit cursor values.

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

→ pagination.has_more: true
→ pagination.next_cursor: "eyJ1IjoiMjAyNi0wOS0wMVQxMDowMDowMC4wMDBaIiwiaSI6Ik1YRC05MDAwMSJ9"

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

Examples

json
{
  "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
  }
}
Confirmed

Property & inventory mapping

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

GET/api/connectivity/v1/properties/{id}/mappings

Returns entity_type (property, room, rate_plan), mixdorm_id, and external_id. Catalog helpers: GET /catalog/rooms, GET /catalog/rate-plans.

  • ARI: unmapped external ids reject the entire atomic batch (400).
  • Reservations: unmapped lines may return null external ids plus entries in errors[]; the page still returns 200.

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.

HTTPCodeMeaningRecommended action
401invalid_tokenMissing or invalid Bearer tokenRefresh token via POST /oauth/token
401invalid_clientOAuth client_id or client_secret rejectedVerify credentials; never send secrets in query string
401invalid_signatureRequest signature headers missing or invalidCheck canonical string, timestamp, and HMAC hex
403property_forbiddenproperty_id not assigned to this applicationUse property id from GET /properties only
403connection_disabledProperty connection is disabledContact MixDorm ops
403pilot_safetyWrite refused against a live MixDorm propertyUse the assigned non-live pilot property
403insufficient_scopeCredential lacks required scopeRequest connectivity:ari:write or connectivity:reservations:read as needed
400invalid_requestMissing or malformed query parameterFix property_id, updated_since, or limit
400invalid_cursorContinuation cursor corruptedRestart from last saved checkpoint
400ari_validation_failedARI batch rejected before application; no items appliedFix mapping/fields; resend whole batch with new Idempotency-Key if body changed
400idempotency_requiredIdempotency-Key header missing on mutationSend Idempotency-Key on POST /ari
409idempotency_conflictSame Idempotency-Key with a different bodyUse a new Idempotency-Key
429rate_limitedToo many requests; remain within documented limitsHonour Retry-After: 1 and backoff
422accommodation_unresolvedSingle reservation could not be normalized (in errors[])Contact MixDorm with reservation_id

Retry & reliability

  • GET /reservations is safe to retry — no side effects.
  • POST /ari retries must reuse the same Idempotency-Key only when the body is identical.
  • On timeout or 5xx, retry with exponential backoff.
  • On 401, refresh credentials or token before retrying.
  • On 403, verify property_id / live-property safety — do not retry blindly.
  • Rate limiting: remain within the documented limit (capacity 60, refill ~1/sec guidance). HTTP 429 includes Retry-After: 1 — honour it and back off.
  • Persist cursor/checkpoint only after successful page processing.

Dates, times & currency

  • ARI start_date / end_date: calendar dates YYYY-MM-DD; end_date inclusive.
  • updated_at, created_at: ISO-8601 UTC timestamps.
  • check_in, check_out: calendar dates YYYY-MM-DD.
  • currency: ISO-4217 (e.g. INR). No silent FX coerce.
  • 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 (sandbox application)
  • Property connection assigned (GET /properties) — non-live MixDorm property
  • Room mappings verified (GET /properties/{id}/mappings)
  • Rate plan mappings verified
  • POST /ari open-inventory sample accepted
  • POST /ari stop-sell sample accepted
  • Idempotent ARI replay returns same result; body change → 409
  • Initial full reservation 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 (after certification)

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:

GET/api/connectivity/v1/docs/openapi.json
View API Specification — requires pilot Bearer token against your assigned base URL

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