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.
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.
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
- Receive MixDorm partner credentials (key id + signing secret or OAuth client).
- Authenticate each request (signed headers or Bearer token).
- Confirm your assigned property via
GET /properties. - Retrieve room and rate mappings via
GET /properties/{id}/mappings. - Push sample ARI with
POST /ari+Idempotency-Key. - Poll
GET /reservations?property_id=…every 60s. - Persist your synchronization checkpoint and continuation cursor safely.
- 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 idX-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 …. 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.
Item fields
| Group | Field | Type | Nullable | Description | Example |
|---|---|---|---|---|---|
| Identity | external_property_id | string | No | Your property code (must be mapped) | fdm_prop_pilot_001 |
| Identity | external_room_id | string | No | Your room code (must be mapped) | fdm_room_dorm_a |
| Identity | external_rate_plan_id | string | No | Your rate-plan code (must be mapped) | fdm_rate_standard |
| Dates | start_date | string (date) | No | First calendar date YYYY-MM-DD (inclusive) | 2026-10-01 |
| Dates | end_date | string (date) | No | Last calendar date YYYY-MM-DD (inclusive) | 2026-10-03 |
| Inventory | inventory | integer | Yes | Available units (≥ 0). Optional on restriction-only rows | 5 |
| Rates | rate | number | Yes | Nightly rate (≥ 0). Currency required when rate > 0 | 899 |
| Rates | currency | string | Yes | ISO-4217; required when rate > 0; must match property currency | INR |
| Restrictions | closed | boolean | Yes | Stop-sell / closed for sale | false |
| Restrictions | closed_to_arrival | boolean | Yes | CTA — no arrivals that night | false |
| Restrictions | closed_to_departure | boolean | Yes | CTD — no departures that night | false |
| Restrictions | min_stay | integer | Yes | Minimum length of stay (≥ 0) | 1 |
| Restrictions | max_stay | integer | Yes | Maximum length of stay (≥ 0) | 14 |
end_dateis inclusive (calendar dates, UTC-safe day keys).- When
rate > 0,currencyis 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
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
{
"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 inventoryGET /reservations
Primary reservation endpoint for FrontDesk Master. Returns pending, confirmed, modified, and cancelled reservations for an assigned property. Scope: connectivity:reservations:read.
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
property_id | string | Required | Assigned property connection id from GET /properties | prp_conn_example |
updated_since | string (ISO-8601 UTC) | Optional | Lower bound on reservation updated_at for incremental sync | 2026-09-01T00:00:00.000Z |
cursor | string | Optional | Opaque token — echo pagination.next_cursor exactly; do not decode or construct | eyJ1IjoiMjAyNi0wOS0wMVQxMDowMDowMC4wMDBaIiwiaSI6Ik1YRC05MDAwMSJ9 |
limit | integer | Optional | Page size (1–100, default 50) | 50 |
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
| Group | Field | Type | Nullable | Description | Example |
|---|---|---|---|---|---|
| Envelope | schema_version | string | No | API schema version | 1.0.0 |
| Envelope | property_id | string | No | Queried connection id | prp_conn_example |
| Envelope | external_property_id | string | No | Your property code | fdm_prop_pilot_001 |
| Envelope | reservations | array | No | Reservation objects for this page | — |
| Envelope | errors | array | No | Per-reservation serialization issues (page still returns) | — |
| Envelope | pagination.limit | integer | No | Requested page size | 50 |
| Envelope | pagination.count | integer | No | Reservations in this page | 1 |
| Envelope | pagination.has_more | boolean | No | True if more pages exist | false |
| Envelope | pagination.next_cursor | string|null | No | Pass as cursor on next request | null |
Reservation object
| Group | Field | Type | Nullable | Description | Example |
|---|---|---|---|---|---|
| Identity | reservation_id | string | No | Stable MixDorm booking reference (e.g. MXD-90001) | MXD-90001 |
| Property | property_id | string | No | Assigned connection id | prp_conn_example |
| Property | external_property_id | string | No | Your mapped property code | fdm_prop_pilot_001 |
| Stay | check_in | string (date) | No | Arrival date YYYY-MM-DD | 2026-12-10 |
| Stay | check_out | string (date) | No | Departure date YYYY-MM-DD | 2026-12-12 |
| Lifecycle | status | enum | No | pending | confirmed | cancelled | confirmed |
| Lifecycle | cancelled | boolean | No | True when reservation is cancelled | false |
| Lifecycle | updated_at | string (ISO-8601 UTC) | No | Last change timestamp — use for checkpointing | 2026-09-01T10:00:00.000Z |
| Lifecycle | created_at | string (ISO-8601 UTC) | Yes | Original creation time | 2026-09-01T09:55:00.000Z |
| Guest | guest_count | integer | Yes | Booking-level guest count | 2 |
| Guest | guest.first_name | string | Yes | Traveller first name | FDM |
| Guest | guest.last_name | string | Yes | Traveller last name | Test Guest |
| Guest | guest.full_name | string | Yes | Full name when provided | FDM Test Guest |
| Guest | guest.email | string | Yes | Contact email | fdm-test@example.invalid |
| Guest | guest.phone | string | Yes | Contact phone | +910000000000 |
| Financials | currency | string | No | ISO-4217 currency code | INR |
| Financials | total_amount | number | Yes | Total booking value | 1500 |
| Financials | paid_amount | number | Yes | Amount collected online | 500 |
| Accommodation | accommodation[] | array | No | One or more room/rate lines | — |
| Accommodation | accommodation[].external_room_id | string | Yes | Mapped room id (null if unmapped) | fdm_room_dorm_a |
| Accommodation | accommodation[].external_rate_plan_id | string | Yes | Mapped rate plan id | fdm_rate_standard |
| Accommodation | accommodation[].rate_plan_name | string | Yes | Rate plan display name | Standard |
| Accommodation | accommodation[].quantity | integer | No | Units booked (beds/rooms) | 2 |
| Accommodation | accommodation[].beds | integer | Yes | Bed count when applicable | 2 |
| Accommodation | accommodation[].bed_type | string | Yes | Bed type label | bunk |
| Accommodation | accommodation[].room_number | string | Yes | Room number when known | — |
| Accommodation | accommodation[].room_type | string | Yes | Room type label | — |
| Accommodation | accommodation[].is_dorm | boolean | No | Dorm/shared semantics hint | true |
| Accommodation | accommodation[].occupancy.adults | integer | No | Adult count | 2 |
| Accommodation | accommodation[].occupancy.children | integer | No | Child count | 0 |
| Stay | special_requests | string | Yes | Guest special requests | — |
Reservation lifecycle
reservation_idremains stable across modifications and cancellation.- Modifications appear with a later
updated_aton incremental poll. - Cancelled reservations remain in the feed with
status: cancelledandcancelled: 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_sinceacross cycles. - After downtime: Resume from last saved checkpoint; page with echoed cursors until
has_moreis false. - Modifications & cancellations: Discovered via later
updated_atvalues on the same id.
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 algorithmPagination
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.
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=eyJ1IjoiMjAyNi0wOS0wMVQxMDowMDowMC4wMDBaIiwiaSI6Ik1YRC05MDAwMSJ9Examples
{
"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
}
}ConfirmedProperty & 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. Catalog helpers: GET /catalog/rooms, GET /catalog/rate-plans.
- ARI: unmapped external ids reject the entire atomic batch (400).
- Reservations: unmapped lines may return
nullexternal ids plus entries inerrors[]; 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.
| HTTP | Code | Meaning | Recommended action |
|---|---|---|---|
| 401 | invalid_token | Missing or invalid Bearer token | Refresh token via POST /oauth/token |
| 401 | invalid_client | OAuth client_id or client_secret rejected | Verify credentials; never send secrets in query string |
| 401 | invalid_signature | Request signature headers missing or invalid | Check canonical string, timestamp, and HMAC hex |
| 403 | property_forbidden | property_id not assigned to this application | Use property id from GET /properties only |
| 403 | connection_disabled | Property connection is disabled | Contact MixDorm ops |
| 403 | pilot_safety | Write refused against a live MixDorm property | Use the assigned non-live pilot property |
| 403 | insufficient_scope | Credential lacks required scope | Request connectivity:ari:write or connectivity:reservations:read as needed |
| 400 | invalid_request | Missing or malformed query parameter | Fix property_id, updated_since, or limit |
| 400 | invalid_cursor | Continuation cursor corrupted | Restart from last saved checkpoint |
| 400 | ari_validation_failed | ARI batch rejected before application; no items applied | Fix mapping/fields; resend whole batch with new Idempotency-Key if body changed |
| 400 | idempotency_required | Idempotency-Key header missing on mutation | Send Idempotency-Key on POST /ari |
| 409 | idempotency_conflict | Same Idempotency-Key with a different body | Use a new Idempotency-Key |
| 429 | rate_limited | Too many requests; remain within documented limits | Honour Retry-After: 1 and backoff |
| 422 | accommodation_unresolved | Single reservation could not be normalized (in errors[]) | Contact MixDorm with reservation_id |
Retry & reliability
GET /reservationsis safe to retry — no side effects.POST /ariretries 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, verifyproperty_id/ live-property safety — do not retry blindly. - Rate limiting: remain within the documented limit (capacity 60, refill ~1/sec guidance). HTTP
429includesRetry-After: 1— honour it and back off. - Persist cursor/checkpoint only after successful page processing.
Dates, times & currency
- ARI
start_date/end_date: calendar datesYYYY-MM-DD;end_dateinclusive. updated_at,created_at: ISO-8601 UTC timestamps.check_in,check_out: calendar datesYYYY-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:
Contact team@mixdorm.com for pilot credentials and base URL assignment.