{ "openapi": "3.0.3", "info": { "title": "TableFox Integration API", "version": "1.0.0", "description": "REST API for partner integrations with the TableFox restaurant booking platform.\n\nUse cases include POS / EPOS systems, chat widgets, AI phone agents, CRMs and any other tool that needs to read availability or write bookings on behalf of a restaurant.\n\nEach restaurant has its own API key, issued by TableFox. Master keys (one key, many restaurants) are available for accredited partners on request — email hello@tablefox.co.uk.", "contact": { "name": "TableFox Support", "email": "hello@tablefox.co.uk", "url": "https://tablefox.co.uk/developers" }, "license": { "name": "Proprietary — usage requires an issued API key" } }, "servers": [ { "url": "https://tablefox.co.uk", "description": "Production" } ], "security": [ { "ApiKeyHeader": [] } ], "tags": [ { "name": "Availability", "description": "Read open slots for a date / covers / service." }, { "name": "Bookings", "description": "Create, look up, modify and cancel bookings (customer-side)." }, { "name": "POS / Bookings", "description": "Staff-side booking management — list, detail, status, modify." }, { "name": "Customers", "description": "Search and read customer records + booking history." }, { "name": "Tables", "description": "Read floor plan availability." }, { "name": "Vouchers", "description": "Look up and redeem gift vouchers at point of sale." }, { "name": "Restaurant", "description": "Read public restaurant info + operating hours." }, { "name": "Other", "description": "Misc integration endpoints (callback requests etc.)." } ], "paths": { "/api/v1/availability": { "get": { "tags": [ "Availability" ], "summary": "List available time slots", "description": "Returns the slots a party of the given size can book on the given date.", "parameters": [ { "name": "date", "in": "query", "required": true, "description": "Date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date", "example": "2026-04-05" } }, { "name": "covers", "in": "query", "required": true, "description": "Number of guests (1-30).", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "example": 4 } }, { "name": "service", "in": "query", "required": false, "description": "Service code filter (e.g. LUNCH, DINNER).", "schema": { "type": "string", "example": "DINNER" } }, { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bookings": { "post": { "tags": [ "Bookings" ], "summary": "Create a booking", "description": "Creates a new booking. Sends confirmation email/SMS if the restaurant auto-accepts, or a payment link if a deposit/card-hold is required.", "parameters": [ { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingCreateRequest" } } } }, "responses": { "200": { "description": "Booking created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingCreateResponse" } } } }, "400": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "POS / Bookings" ], "summary": "List bookings for a date", "description": "Paginated list of bookings, with optional filters. Cancelled bookings are hidden unless requested.", "parameters": [ { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "YYYY-MM-DD (defaults to today)." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "SEATED", "COMPLETED", "NO_SHOW", "CANCELLED" ] } }, { "name": "service", "in": "query", "schema": { "type": "string" }, "description": "Service code (LUNCH, DINNER...)." }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search name / phone / email / reference (min 2 chars)." }, { "name": "search_all_dates", "in": "query", "schema": { "type": "boolean" }, "description": "Set true with q to search across all dates instead of one day." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 30 } }, { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingListResponse" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bookings/lookup": { "get": { "tags": [ "Bookings" ], "summary": "Look up upcoming bookings by phone", "description": "Returns up to 5 upcoming bookings matching the supplied phone number. Used by AI phone agents to identify a returning caller. Does not leak data — only bookings matching the phone are returned.", "parameters": [ { "name": "phone", "in": "query", "required": true, "description": "Customer phone number. Matched against +44/0/44 variants.", "schema": { "type": "string", "example": "+447450425161" } }, { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingLookupResponse" } } } }, "400": { "description": "Missing phone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bookings/modify": { "post": { "tags": [ "Bookings" ], "summary": "Modify an existing booking", "description": "Update the date, time, covers, notes or tags on an existing booking. Requires phone match for security. Respects the restaurant's edit settings and self-service cutoff window.", "parameters": [ { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingModifyRequest" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingModifyResponse" } } } }, "400": { "description": "Validation failed or time conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Editing not allowed or within cutoff window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking not found or phone mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bookings/cancel": { "post": { "tags": [ "Bookings" ], "summary": "Cancel a booking", "description": "Cancels an existing booking. Requires phone match for security. Respects the restaurant's self-service cancellation cutoff (see editing_cutoff_hours on the lookup response).", "parameters": [ { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingCancelRequest" } } } }, "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingCancelResponse" } } } }, "403": { "description": "Within cutoff window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking not found or phone mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/restaurant": { "get": { "tags": [ "Restaurant" ], "summary": "Get restaurant info + services for a date", "description": "Returns the restaurant name, contact details, and the services running on the given date (with start/end times).", "parameters": [ { "name": "date", "in": "query", "required": false, "description": "Date in YYYY-MM-DD (defaults to today).", "schema": { "type": "string", "format": "date" } }, { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestaurantResponse" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/callback-request": { "post": { "tags": [ "Other" ], "summary": "Submit a callback request", "description": "Typically used by an AI phone agent when the caller wants to speak to a human. Sends an email to the restaurant and a push notification to staff.", "parameters": [ { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackRequest" } } } }, "responses": { "200": { "description": "Request forwarded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "Missing caller details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Restaurant has no email on file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bookings/{id}": { "get": { "tags": [ "POS / Bookings" ], "summary": "Single booking detail", "description": "Full booking record including customer stats, tables, tags, voucher redemptions and purchased extras.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingDetailResponse" } } } }, "404": { "description": "Booking not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bookings/{id}/status": { "post": { "tags": [ "POS / Bookings" ], "summary": "Change a booking status", "description": "Used by POS / EPOS systems to mark a booking SEATED when the guest is seated, COMPLETED when the bill is closed, or NO_SHOW after a grace window.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusUpdateRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusUpdateResponse" } } } }, "400": { "description": "Invalid status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bookings/{id}/modify": { "post": { "tags": [ "POS / Bookings" ], "summary": "Staff-side modify (no phone match, no cutoff)", "description": "Update date, time, covers, notes, tags or assigned tables. Returns 409 with type=OVERLAP_WARNING when the new time/tables conflict with another booking.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffModifyRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingModifyResponse" } } } }, "400": { "description": "Nothing to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "OVERLAP_WARNING — new time/tables conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/bookings/{id}/redeem-voucher": { "post": { "tags": [ "Vouchers" ], "summary": "Redeem a voucher against a specific booking", "description": "Same as POST /api/v1/vouchers/redeem but the redemption is automatically linked to this booking.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRedeemVoucherRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoucherRedeemResponse" } } } }, "400": { "description": "Validation failed (e.g. amount exceeds balance)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Booking or voucher not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/customers": { "get": { "tags": [ "Customers" ], "summary": "Search customers", "description": "Search by name, email or phone. Useful for POS \"is this a returning guest?\" lookups.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListResponse" } } } }, "400": { "description": "Query too short", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Single customer + booking history", "description": "Full customer record plus up to 50 most-recent bookings.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDetailResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/tables/available": { "get": { "tags": [ "Tables" ], "summary": "Tables list with occupancy + best-fit suggestion", "description": "Returns every active table with an is_occupied flag for the requested time window, plus is_suggested for the best-fit allocation. Used to power POS floor plans.", "parameters": [ { "name": "covers", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 2 } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "time", "in": "query", "schema": { "type": "string", "example": "19:00" } }, { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TablesAvailableResponse" } } } } } } }, "/api/v1/vouchers/lookup": { "get": { "tags": [ "Vouchers" ], "summary": "Look up a voucher by code", "description": "Returns 200 with found=false when the code is unknown (no 404) so POS can render a friendly message.", "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "OK (check found flag)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoucherLookupResponse" } } } } } } }, "/api/v1/vouchers/redeem": { "post": { "tags": [ "Vouchers" ], "summary": "Redeem against a voucher (standalone or linked to a booking)", "description": "Pass booking_reference to link the redemption to a booking. Partial redemptions are supported — the voucher stays ACTIVE with reduced balance until fully drained.", "parameters": [ { "name": "restaurant_id", "in": "query", "required": false, "description": "Required when authenticating with a master API key. Ignored for per-restaurant keys (the key itself identifies the restaurant).", "schema": { "type": "integer", "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoucherRedeemRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoucherRedeemResponse" } } } }, "400": { "description": "Validation failed (amount, balance, etc.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Voucher not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Per-restaurant or master API key issued by TableFox. Also accepted as ?api_key=... query param or Authorization: Bearer ... header." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Validation failed" }, "errors": { "type": "array", "description": "Per-field validation messages (only present on 400 responses).", "items": { "type": "string" } } } }, "Slot": { "type": "object", "properties": { "time": { "type": "string", "example": "12:00", "description": "HH:MM in restaurant local time." }, "service": { "type": "string", "nullable": true, "example": "LUNCH" }, "available": { "type": "boolean" } } }, "AvailabilityResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "restaurant": { "type": "string", "example": "Viva Brazil" }, "date": { "type": "string", "format": "date" }, "covers": { "type": "integer" }, "count": { "type": "integer" }, "slots": { "type": "array", "items": { "$ref": "#/components/schemas/Slot" } } } }, "BookingCreateRequest": { "type": "object", "required": [ "date", "time", "covers", "first_name" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-04-05" }, "time": { "type": "string", "example": "19:00", "description": "24-hour HH:MM." }, "covers": { "type": "integer", "minimum": 1, "maximum": 30 }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string", "description": "Phone OR email is required." }, "email": { "type": "string", "format": "email", "description": "Required if the restaurant has a deposit/card-hold payment mode." }, "notes": { "type": "string" }, "tags": { "description": "Comma-separated string or array.", "oneOf": [ { "type": "string", "example": "BIRTHDAY,ALLERGY" }, { "type": "array", "items": { "type": "string", "enum": [ "BIRTHDAY", "ANNIVERSARY", "ALLERGY", "HIGH_CHAIR", "VIP" ] } } ] }, "source": { "type": "string", "enum": [ "ONLINE", "INTERNAL", "PHONE", "WALKIN", "AI_PHONE" ], "default": "PHONE" }, "restaurant_id": { "type": "integer", "description": "Master key only." } } }, "BookingSummary": { "type": "object", "properties": { "booking_id": { "type": "integer" }, "booking_reference": { "type": "string", "example": "RB-20260405-A1B2C3" }, "status": { "type": "string", "enum": [ "CONFIRMED", "PENDING", "PENDING_PAYMENT", "CANCELLED", "SEATED", "COMPLETED", "NO_SHOW" ] }, "date": { "type": "string", "format": "date" }, "time": { "type": "string" }, "covers": { "type": "integer" }, "customer_name": { "type": "string" } } }, "PaymentInfo": { "type": "object", "nullable": true, "properties": { "required": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "DEPOSIT", "CARD_HOLD" ] }, "amount_pence": { "type": "integer" }, "amount_formatted": { "type": "string", "example": "£20.00" }, "expiry_hours": { "type": "integer" }, "message": { "type": "string" } } }, "BookingCreateResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "booking": { "$ref": "#/components/schemas/BookingSummary" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "message": { "type": "string" } } }, "LookupBooking": { "type": "object", "properties": { "booking_id": { "type": "integer" }, "booking_reference": { "type": "string" }, "date": { "type": "string", "format": "date" }, "time": { "type": "string" }, "covers": { "type": "integer" }, "status": { "type": "string" }, "name": { "type": "string" }, "editable": { "type": "boolean" }, "editable_reason": { "type": "string", "nullable": true }, "cancellable": { "type": "boolean" }, "cancellable_reason": { "type": "string", "nullable": true } } }, "BookingLookupResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "count": { "type": "integer" }, "editing_allowed": { "type": "boolean" }, "editing_cutoff_hours": { "type": "integer" }, "bookings": { "type": "array", "items": { "$ref": "#/components/schemas/LookupBooking" } } } }, "BookingModifyRequest": { "type": "object", "required": [ "booking_id", "phone" ], "properties": { "booking_id": { "type": "integer" }, "phone": { "type": "string", "description": "Must match the booking's customer phone." }, "new_date": { "type": "string", "format": "date" }, "new_time": { "type": "string" }, "new_covers": { "type": "integer" }, "notes": { "type": "string", "description": "Appended to existing notes, not replaced." }, "tags": { "description": "Comma-separated string or array. Merged with existing tags.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "restaurant_id": { "type": "integer", "description": "Master key only." } } }, "BookingModifyResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "booking": { "$ref": "#/components/schemas/BookingSummary" } } }, "BookingCancelRequest": { "type": "object", "required": [ "booking_id", "phone" ], "properties": { "booking_id": { "type": "integer" }, "phone": { "type": "string" }, "restaurant_id": { "type": "integer", "description": "Master key only." } } }, "BookingCancelResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "booking_reference": { "type": "string" } } }, "Service": { "type": "object", "properties": { "name": { "type": "string", "example": "Lunch" }, "code": { "type": "string", "example": "LUNCH" }, "start_time": { "type": "string", "example": "12:00:00" }, "end_time": { "type": "string", "example": "16:00:00" } } }, "RestaurantResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "date": { "type": "string", "format": "date" }, "restaurant": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "max_online_covers": { "type": "integer" } } }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } } }, "CallbackRequest": { "type": "object", "description": "At least one of phone / first_name / notes must be provided.", "properties": { "phone": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "reason": { "type": "string", "example": "menu enquiry" }, "notes": { "type": "string" }, "restaurant_id": { "type": "integer", "description": "Master key only." } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "total_pages": { "type": "integer" } } }, "BookingListItem": { "type": "object", "properties": { "booking_id": { "type": "integer" }, "reference": { "type": "string" }, "date": { "type": "string", "format": "date" }, "time": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "covers": { "type": "integer" }, "status": { "type": "string" }, "seating_status": { "type": "string", "nullable": true }, "service": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "internal_notes": { "type": "string", "nullable": true }, "tables": { "type": "array", "items": { "type": "string" } }, "extras_count": { "type": "integer" }, "extras_total_pence": { "type": "integer" }, "extras_summary": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "BookingListResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "date": { "type": "string", "format": "date" }, "search_all_dates": { "type": "boolean" }, "bookings": { "type": "array", "items": { "$ref": "#/components/schemas/BookingListItem" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "CustomerSummary": { "type": "object", "properties": { "customer_id": { "type": "integer", "nullable": true }, "first_name": { "type": "string" }, "last_name": { "type": "string", "nullable": true }, "name": { "type": "string" }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "is_vip": { "type": "boolean" }, "blocked": { "type": "boolean" }, "total_bookings": { "type": "integer", "nullable": true }, "total_no_shows": { "type": "integer", "nullable": true } } }, "BookingDetailResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "booking": { "type": "object", "properties": { "booking_id": { "type": "integer" }, "reference": { "type": "string" }, "status": { "type": "string" }, "date": { "type": "string", "format": "date" }, "time": { "type": "string" }, "covers": { "type": "integer" }, "service_name": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "customer": { "$ref": "#/components/schemas/CustomerSummary" }, "notes": { "type": "string", "nullable": true }, "internal_notes": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "tables": { "type": "array", "items": { "type": "object", "properties": { "table_id": { "type": "integer" }, "name": { "type": "string" }, "zone": { "type": "string", "nullable": true } } } }, "vouchers": { "type": "array", "items": { "type": "object" } }, "extras": { "type": "array", "items": { "type": "object" } }, "seating_status": { "type": "string", "nullable": true }, "card_on_file": { "type": "boolean" }, "deposit_paid_pence": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "seated_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } } } }, "StatusUpdateRequest": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED", "SEATED", "COMPLETED", "NO_SHOW", "CANCELLED" ] }, "restaurant_id": { "type": "integer", "description": "Master key only." } } }, "StatusUpdateResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "booking": { "type": "object", "properties": { "booking_id": { "type": "integer" }, "reference": { "type": "string" }, "status": { "type": "string" } } }, "message": { "type": "string" } } }, "StaffModifyRequest": { "type": "object", "description": "At least one field must be supplied.", "properties": { "date": { "type": "string", "format": "date" }, "time": { "type": "string" }, "covers": { "type": "integer" }, "notes": { "type": "string", "nullable": true }, "internal_notes": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "table_ids": { "type": "array", "items": { "type": "integer" } }, "restaurant_id": { "type": "integer", "description": "Master key only." } } }, "CustomerListItem": { "type": "object", "properties": { "customer_id": { "type": "integer" }, "name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "total_bookings": { "type": "integer" }, "total_no_shows": { "type": "integer" }, "last_visit": { "type": "string", "format": "date", "nullable": true }, "is_vip": { "type": "boolean" }, "blocked": { "type": "boolean" }, "blocked_reason": { "type": "string", "nullable": true } } }, "CustomerListResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "query": { "type": "string" }, "customers": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerListItem" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "CustomerDetailResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "customer": { "$ref": "#/components/schemas/CustomerListItem" }, "bookings": { "type": "array", "description": "Up to 50 most-recent bookings, most-recent first.", "items": { "type": "object", "properties": { "booking_id": { "type": "integer" }, "booking_reference": { "type": "string" }, "date": { "type": "string", "format": "date" }, "time": { "type": "string" }, "covers": { "type": "integer" }, "status": { "type": "string" }, "service_name": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true } } } } } }, "TableAvailability": { "type": "object", "properties": { "table_id": { "type": "integer" }, "name": { "type": "string" }, "zone": { "type": "string", "nullable": true }, "min_covers": { "type": "integer" }, "max_covers": { "type": "integer" }, "is_occupied": { "type": "boolean" }, "is_suggested": { "type": "boolean" }, "fits_party": { "type": "boolean" } } }, "TablesAvailableResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "tables": { "type": "array", "items": { "$ref": "#/components/schemas/TableAvailability" } }, "suggested_ids": { "type": "array", "items": { "type": "integer" } } } }, "VoucherLookupResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "found": { "type": "boolean" }, "message": { "type": "string", "description": "Present only when found=false." }, "voucher": { "type": "object", "nullable": true, "properties": { "voucher_id": { "type": "integer" }, "code": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "REDEEMED", "EXPIRED", "CANCELLED" ] }, "value_pence": { "type": "integer" }, "balance_pence": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "is_expired": { "type": "boolean" }, "recipient_name": { "type": "string", "nullable": true }, "product_name": { "type": "string", "nullable": true }, "can_redeem": { "type": "boolean" } } } } }, "VoucherRedeemRequest": { "type": "object", "required": [ "code", "amount_pence" ], "properties": { "code": { "type": "string", "example": "TF-ABC123" }, "amount_pence": { "type": "integer", "minimum": 1 }, "booking_reference": { "type": "string", "description": "Optional — links this redemption to a booking." }, "note": { "type": "string" }, "restaurant_id": { "type": "integer", "description": "Master key only." } } }, "BookingRedeemVoucherRequest": { "type": "object", "required": [ "code", "amount_pence" ], "properties": { "code": { "type": "string" }, "amount_pence": { "type": "integer", "minimum": 1 }, "note": { "type": "string" }, "restaurant_id": { "type": "integer", "description": "Master key only." } } }, "VoucherRedeemResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "redemption_id": { "type": "integer" }, "new_balance_pence": { "type": "integer" }, "fully_redeemed": { "type": "boolean" }, "voucher": { "type": "object", "properties": { "voucher_id": { "type": "integer" }, "code": { "type": "string" }, "balance_pence": { "type": "integer" }, "status": { "type": "string" } } }, "message": { "type": "string" } } } } } }