Conventions: requests and responses

Rules that apply to every API endpoint: formats, dates, identifiers, pagination.

Data formats

Most POST/PUT endpoints also accept application/json-patch+json, text/json and application/*+json, but plain application/json is recommended.

Date and time

All time values use ISO 8601.

Time zone. Reservation times are interpreted in the restaurant’s local time zone. The restaurant’s time zone is available from GET /api/core/admin/account/me → restaurants[].timeZone. date-time values usually carry no zone offset — send the restaurant’s local time. If you operate in a different time zone, convert the time on your side.

Identifiers

ID types in the API are mixed — be careful:

restaurantId is numeric and appears in almost every path: /api/.../restaurants/{restaurantId}/.... Most other identifiers are strings (GUIDs).

Pagination

List endpoints with paged output return a PagedResult wrapper:

{
  "results": [ /* items */ ],
  "count": 1234
}

Paging and filtering parameters (page, pageSize, search, date ranges, etc.) depend on the specific endpoint — see its description in the relevant section.

Filtering by date

Some list endpoints require a date range. For example, the list of reservations for external apps (scope App) requires a mandatory range of no more than 60 days (see Reservations).

Null and optional fields

• In responses most fields are nullable — check for null before use.
• In requests send only the fields you need; missing ones are treated as unset.
• Fields marked * (required) in the sections must be present in the request.

Idempotency and duplicates

The spec does not describe a dedicated idempotency header (Idempotency-Key). To avoid duplicates on retry:

• Keep a “your ID ↔ Hostme reservation ID” mapping on your side.
• Use the source field (and, where applicable, externalUserId) to mark where a record came from.
• On network errors, first check whether the record was created (with a repeat GET) before retrying the POST.

Headers