Create & Manage

The full booking lifecycle: creating, listing for a period, reading, updating and canceling. All endpoints require a Bearer token (see Authentication).

Base path: /api/rsv/admin/restaurants/{restaurantId}/reservations.

Create a booking

POST /reservations

Creates a new reservation. The behavior depends on the token type:

• Hostme / Partner — the booking is created on behalf of the current user (host/manager).
• Vendor — the booking is created on behalf of an external app (POS, CRM, etc.).

Body — CreateReservationContract. The most used top-level fields are below.

Main fields

Nested objects

Order refusals. On create and update the server prices orderItems from the menu before the booking is saved, and rounds amounts to two decimal places. An order it cannot take is refused with 400 and a code: invalid_price — a product or modifier choice the menu prices below zero; invalid_quantity — the amount of a line or modifier below zero; invalid_amount — tips or the order total below zero; amount_too_large — a total above 21474836.47.

Example (minimal)

curl -X POST https://api.hostmeapp.com/api/rsv/admin/restaurants/123/reservations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reservationTime": "2026-07-01T19:00:00",
    "groupSize": 2,
    "customerName": "John Parker",
    "phone": "+16175550123",
    "email": "ivan@example.com",
    "specialRequests": "Window table",
    "source": "partner-widget"
  }'

Example (with guest profile and requests)

curl -X POST https://api.hostmeapp.com/api/rsv/admin/restaurants/123/reservations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reservationTime": "2026-07-01T20:30:00",
    "groupSize": 4,
    "customerName": "Maria Ivanova",
    "phone": "+16175550100",
    "additionals": { "highChair": true, "vip": true },
    "customerProfile": { "allergy": ["nuts"], "vegetarian": true },
    "internalNotes": "Regular guest",
    "source": "partner-crm"
  }'

Response. On success the created booking is returned as a BookingContract (see below). Documented errors: 400 Bad Request, 404 Not Found (body — ProblemDetails).

List for a period

GET /reservations

Returns the restaurant’s bookings for a period. For requests from external apps (scope App), VendorAppId is set automatically and a date range of no more than 60 days is required.

Parameters

Example

curl -G https://api.hostmeapp.com/api/rsv/admin/restaurants/123/reservations \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "from=2026-07-01T00:00:00" \
  --data-urlencode "to=2026-07-07T23:59:59"

For external apps the range is required and limited to 60 days — split long periods into parts.

Get a booking

GET /reservations/{reservationId}

Returns a booking by identifier. Response — BookingContract.

Key response fields (BookingContract)

The full BookingContract object is extensive (profile, order, check, payment). Only the key blocks are listed here; see the full structure in the Swagger UI.

Update a booking

PUT /reservations/{reservationId}

Updates an existing booking (time, party size, table, etc.). The change is recorded against the current user (for auditing).

Request body — the same fields as when creating (CreateReservationContract): send the fields being changed (reservationTime, groupSize, tableNumber, specialRequests, etc.).

curl -X PUT https://api.hostmeapp.com/api/rsv/admin/restaurants/123/reservations/RID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reservationTime": "2026-07-01T20:00:00", "groupSize": 3 }'

Cancel a booking

PUT /reservations/{reservationId}/cancel

Cancels a booking on behalf of restaurant staff. Body — CancelReservationContract.

Response — the updated booking (BookingContract) with the canceled status.

curl -X PUT https://api.hostmeapp.com/api/rsv/admin/restaurants/123/reservations/RID/cancel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cancelOptionName": "Guest cancelled", "note": "Moved to another day", "doNotChargeFee": true }'

Need to moderate bookings from external channels? Use Booking Requests — the host approves a request before it becomes a full booking.