{ "openapi": "3.1.0", "info": { "title": "FrontDesk PMS API", "version": "1.0.0", "description": "REST API of the FrontDesk hotel PMS. Authenticate with a property API key (Settings > API): `Authorization: Bearer fd_live_\u2026`. Every call is scoped to the key's property. Amounts are integer cents in the property currency. Webhooks: signed POSTs for reservation.created, reservation.updated, reservation.cancelled, charge.created (see /api-docs)." }, "servers": [ { "url": "/api/v1" } ], "security": [ { "bearer": [] } ], "paths": { "/reservations": { "get": { "summary": "List reservations", "description": "Ordered by check-in. from/to select stays overlapping [from, to).", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "YYYY-MM-DD", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "YYYY-MM-DD", "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "required": false, "description": "Reservation status", "schema": { "type": "string", "enum": [ "tentative", "confirmed", "checked_in", "checked_out", "cancelled", "no_show" ] } }, { "name": "updated_since", "in": "query", "required": false, "description": "ISO timestamp", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "1-500, default 100", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "offset", "in": "query", "required": false, "description": "default 0", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Reservation" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a reservation", "description": "Creates the guest too when passed inline. 409 when the room is already taken.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservationCreate" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Reservation" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/availability": { "get": { "summary": "Room availability", "description": "Per room: free for the whole [from, to)? Plus a per room-type summary. Max 366 days.", "parameters": [ { "name": "from", "in": "query", "required": true, "description": "YYYY-MM-DD", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "YYYY-MM-DD, after from", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Availability" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/guests": { "get": { "summary": "List guests", "description": "Essential guest directory; identity documents are never exposed.", "parameters": [ { "name": "email", "in": "query", "required": false, "description": "Exact match, case-insensitive", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1-500, default 100", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "offset", "in": "query", "required": false, "description": "default 0", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Guest" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/charges": { "get": { "summary": "List folio charges", "description": "Service and extra lines on the property's folios, newest first.", "parameters": [ { "name": "reservation_id", "in": "query", "required": false, "description": "Only this reservation", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "ISO timestamp", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "1-500, default 100", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "offset", "in": "query", "required": false, "description": "default 0", "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Charge" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Post a charge on a folio", "description": "From a POS, restaurant, bar, spa or minibar system. Target the reservation by id, or by room number (the checked-in stay in that room). Idempotent per reservation on idempotency_key (body) or the Idempotency-Key header: a retry returns the original charge with 200. Emits the charge.created webhook.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeCreate" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Charge" } } } } } }, "200": { "description": "Replay of an idempotent request", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Charge" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Reservation cancelled or no-show", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "fd_live_ API key" } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "issues": { "type": "array", "items": {} } } }, "Reservation": { "type": "object", "properties": { "id": { "type": "string" }, "property_id": { "type": "string" }, "unit_id": { "type": "string" }, "guest_id": { "type": "string" }, "check_in": { "type": "string", "format": "date" }, "check_out": { "type": "string", "format": "date" }, "status": { "type": "string" }, "adults": { "type": "integer" }, "children": { "type": "integer" }, "notes": { "type": "string" }, "source": { "type": "string" }, "total_cents": { "type": "integer" }, "meal_plan": { "type": "string" }, "rate_plan_id": { "type": [ "string", "null" ] }, "group_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ReservationCreate": { "type": "object", "required": [ "unit_id", "check_in", "check_out" ], "description": "Pass exactly one of guest_id or guest.", "properties": { "unit_id": { "type": "string" }, "check_in": { "type": "string", "format": "date" }, "check_out": { "type": "string", "format": "date" }, "status": { "type": "string", "enum": [ "tentative", "confirmed" ], "default": "confirmed" }, "adults": { "type": "integer", "minimum": 1, "maximum": 50, "default": 1 }, "children": { "type": "integer", "minimum": 0, "maximum": 50, "default": 0 }, "total_cents": { "type": "integer", "minimum": 0, "default": 0 }, "notes": { "type": "string", "maxLength": 4000 }, "source": { "type": "string", "maxLength": 60, "default": "api" }, "guest_id": { "type": "string" }, "guest": { "type": "object", "required": [ "first_name", "last_name" ], "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } } } } }, "Availability": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "room_types": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "total": { "type": "integer" }, "available": { "type": "integer" } } } }, "rooms": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "unit_type_id": { "type": "string" }, "available": { "type": "boolean" } } } } } }, "Guest": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "nationality": { "type": "string" } } }, "ChargeCreate": { "type": "object", "required": [ "description", "amount_cents" ], "description": "Pass exactly one of reservation_id or room.", "properties": { "reservation_id": { "type": "string" }, "room": { "type": "string", "description": "Room name/number; the checked-in reservation in it is charged" }, "description": { "type": "string", "maxLength": 200 }, "amount_cents": { "type": "integer", "minimum": 1 }, "type": { "type": "string", "enum": [ "service", "extra" ], "default": "service" }, "department": { "type": "string", "maxLength": 60, "examples": [ "restaurant", "bar", "spa", "minibar" ] }, "idempotency_key": { "type": "string", "maxLength": 200 } } }, "Charge": { "type": "object", "properties": { "id": { "type": "string" }, "reservation_id": { "type": "string" }, "folio_id": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "amount_cents": { "type": "integer" }, "type": { "type": "string", "enum": [ "service", "extra" ] }, "department": { "type": [ "string", "null" ] }, "source": { "type": "string", "description": "api, minibar or staff" }, "idempotency_key": { "type": [ "string", "null" ] }, "voided": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } } } }