Get publicly bookable slots · Hallify Developers

Authentication

x-hallify-widget-context: <HALLIFY_STOREFRONT_WIDGET_CONTEXT>

Short-lived server-authenticated widget presentation proof. It binds the configured frame origin to the exact verified parent binding and connection authority. Widget new demand requires this proof; existing native capabilities remain separate and retain their original authority and deadlines.

Connection guide

Parameters

publicHandlePath · Required: Opaque public channel handle used to resolve one venue’s published guest-facing configuration; it is not a credential.
string
Full definition
{ "type": "string", "example": "example" }
originHeader · Optional: Actual browser request Origin used for current presentation authorization. New demand and Storefront-bound continuations require it. Canonical Hallify browser requests use the origin configured by HALLIFY_PUBLIC_APP_URL. This header provides request context and does not authenticate a caller or replace the applicable guest credential.
string · uri
Full definition
{ "type": "string", "format": "uri", "maxLength": 2048, "example": "https://example.test/resource" }
x-hallify-connection-idHeader · Optional: Optional nonsecret connection locator for initial public channel resolution. It never grants authority or replaces an issued grant snapshot.
string · uuid
Full definition
{ "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "example": "9b6163a8-afea-4877-818b-8e2ae28a2845" }
servicePeriodIdQuery · Optional: Optional Hallify UUID filter for service period.
string · uuid
Full definition
{ "format": "uuid", "type": "string", "example": "9b6163a8-afea-4877-818b-8e2ae28a2845" }
partySizeQuery · Required: Number of guests used to evaluate capacity and guest-bookable availability.
integer
Full definition
{ "minimum": 1, "maximum": 99, "type": "integer", "example": 1 }
dateQuery · Required: Venue-local business date evaluated by this operation, serialized as YYYY-MM-DD without a time of day.
string
Full definition
{ "type": "string", "example": "example" }

Responses

200Returns available public booking slots and their service-period context.

ReservationAvailabilityDto

Full definition

{
  "$ref": "#/components/schemas/ReservationAvailabilityDto"
}

Example response · 200 · application/json

[
  {
    "scheduledAt": "2026-01-15T12:00:00.000Z",
    "endsAt": "2026-12-31T18:00:00.000Z",
    "occupancyEndsAt": "2026-12-31T18:00:00.000Z",
    "offset": "example",
    "servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646"
  }
]

Schemas

ReservationAvailabilityDto

Returns available staff booking slots and their capacity context.

Full definition

{
  "type": "array",
  "items": {
    "type": "object",
    "required": [
      "scheduledAt",
      "endsAt",
      "occupancyEndsAt",
      "offset",
      "servicePeriodId"
    ],
    "properties": {
      "scheduledAt": {
        "type": "string",
        "format": "date-time",
        "description": "RFC 3339 timestamp for scheduled at; offsets represent the same absolute instant.",
        "example": "2026-01-15T12:00:00.000Z"
      },
      "endsAt": {
        "type": "string",
        "format": "date-time",
        "description": "RFC 3339 timestamp for ends at; offsets represent the same absolute instant.",
        "example": "2026-12-31T18:00:00.000Z"
      },
      "occupancyEndsAt": {
        "type": "string",
        "format": "date-time",
        "description": "RFC 3339 timestamp for occupancy ends at; offsets represent the same absolute instant.",
        "example": "2026-12-31T18:00:00.000Z"
      },
      "offset": {
        "type": "string",
        "description": "Offset for reservations availability item.",
        "example": "example"
      },
      "servicePeriodId": {
        "type": "string",
        "format": "uuid",
        "description": "Hallify UUID identifying service period associated with reservations availability item.",
        "example": "4846c409-f4df-40f6-81cc-1d7157a5c646"
      }
    },
    "example": {
      "scheduledAt": "2026-01-15T12:00:00.000Z",
      "endsAt": "2026-12-31T18:00:00.000Z",
      "occupancyEndsAt": "2026-12-31T18:00:00.000Z",
      "offset": "example",
      "servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646"
    }
  },
  "description": "Returns available staff booking slots and their capacity context.",
  "example": [
    {
      "scheduledAt": "2026-01-15T12:00:00.000Z",
      "endsAt": "2026-12-31T18:00:00.000Z",
      "occupancyEndsAt": "2026-12-31T18:00:00.000Z",
      "offset": "example",
      "servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646"
    }
  ]
}

Request examples

Illustrative data. These examples do not send requests. Replace sample values with data from the preceding workflow steps in your own integration.

cURL

curl --request GET 'https://api.hallify.co/public/reservations/example/availability?servicePeriodId=b7a1b3de-8581-4d78-8597-435227131989&partySize=1&date=example' \
  -H 'origin: https://example.test/resource' \
  -H 'x-hallify-connection-id: c19ce6d1-1d3c-4c48-801b-35468501181c' \
  -H "x-hallify-widget-context: ${HALLIFY_STOREFRONT_WIDGET_CONTEXT}"

Example response

Returns available public booking slots and their service-period context.

Example response · 200 · application/json

[
  {
    "scheduledAt": "2026-01-15T12:00:00.000Z",
    "endsAt": "2026-12-31T18:00:00.000Z",
    "occupancyEndsAt": "2026-12-31T18:00:00.000Z",
    "offset": "example",
    "servicePeriodId": "4846c409-f4df-40f6-81cc-1d7157a5c646"
  }
]