Quick Start

Visit the Get API Keys page to generate a key for your community or brand. Select the permissions your integration needs, then copy the key — it starts with hoa_live_.

Use the availability endpoint to see which time slots are open for a space on a given date. You need the spaceId, which you can find in the URL when viewing a space on hoastnow.

curl "https://www.hoastnow.com/api/v1/spaces/42/availability?date=2026-04-15" \
  -H "Authorization: Bearer $HOASTNOW_API_KEY"

The response describes the community's booking window and lists each available hour within it. The durationHours field tells you how long each event will last — this is community-defined and cannot be changed when booking.

{
  "spaceId": 42,
  "spaceName": "Sunset Clubhouse",
  "date": "2026-04-15",
  "windowStart": 9,
  "windowEnd": 21,
  "durationHours": 3,
  "timeSlots": [
    { "hour": 9,  "label": "9:00 AM",  "isAvailable": true  },
    { "hour": 10, "label": "10:00 AM", "isAvailable": true  },
    { "hour": 11, "label": "11:00 AM", "isAvailable": false }
  ]
}

An isAvailable: false slot is already booked. When selecting a start time, ensure that startHour + durationHours falls within windowEnd. hoastnow will allow the booking even if the event extends slightly past the window but will note the reduced usable time.

Fetch availability for the space and date you want to book. Parse the timeSlots array to find which hours are open.

curl "https://www.hoastnow.com/api/v1/spaces/42/availability?date=2026-04-15" \
  -H "Authorization: Bearer $HOASTNOW_API_KEY"

Pass the spaceId, desired startTime (date), and startHour from the slot you selected. Include an optional message for the community. Handle the 422 SlotUnavailable case — another booking may have taken the slot between your availability check and this call.

curl -X POST https://www.hoastnow.com/api/v1/bookings \
  -H "Authorization: Bearer $HOASTNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": 42,
    "startTime": "2026-04-15",
    "startHour": 10,
    "message": "Brand activation event — approximately 50 attendees."
  }'

A successful POST /bookings returns 201 Created with the booking in Pending status. The community must approve before the booking is confirmed. Store the id to poll for status updates, or set up a webhook to be notified when the status changes.

Use startDate and endDate to limit the response to a relevant window. For a daily sync job, pass today's date as startDate to fetch upcoming bookings only.

curl "https://www.hoastnow.com/api/v1/bookings?startDate=2026-04-01&status=Approved" \
  -H "Authorization: Bearer $HOASTNOW_API_KEY"

Map hoastnow statuses to whatever your internal system uses — for example, a calendar app might only display Approved and Pending bookings.

# Filter to approved bookings only
curl "https://www.hoastnow.com/api/v1/bookings?startDate=2026-04-01&status=Approved" \
  -H "Authorization: Bearer $HOASTNOW_API_KEY"

The current API does not paginate — all matching bookings are returned in a single response. However, use date-range filters to limit response size and avoid large payloads as your booking volume grows.

Register your HTTPS URL and select which events to subscribe to using a bitmask sum: BookingRequested=1, BookingApproved=2, BookingCancelled=4, ReviewPosted=8. Use 15 to subscribe to all events.

curl -X POST https://www.hoastnow.com/api/v1/webhooks \
  -H "Authorization: Bearer $HOASTNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/hooks/hoastnow",
    "events": 15
  }'

{
  "id": "wh_abc123",
  "url": "https://your-server.com/hooks/hoastnow",
  "events": 15,
  "signingSecret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "createdAt": "2026-04-01T10:00:00Z"
}

Every delivery includes an X-Hoastnow-Signature header with an HMAC-SHA256 digest of the raw request body. Always verify this before processing the payload — reject requests that fail with 401.

# Manually compute the expected signature for testing:
echo -n '{"event":"BookingApproved",...}' \
  | openssl dgst -sha256 -hmac "$HOASTNOW_WEBHOOK_SECRET"

Dispatch on the event field. Every payload includes a timestamp and a data object with relevant details.

# Webhook payloads look like this:
# {
#   "event": "BookingApproved",
#   "timestamp": "2026-04-15T10:30:00Z",
#   "data": {
#     "bookingId": 1002, "spaceId": 42, "spaceName": "Sunset Clubhouse",
#     "date": "2026-04-15", "startHour": 10, "endHour": 13,
#     "status": "Approved", "totalPrice": 330.00
#   }
# }

• Idempotency: hoastnow may retry deliveries on non-2xx responses or timeouts. Use bookingId as an idempotency key to avoid processing the same event twice.
• Respond quickly: Return 200 within 5 seconds. Enqueue email sends, DB writes, and third-party calls to a background job.
• Always verify signatures: Never skip verification even in development. Use ngrok to expose a local endpoint for testing.
• Log raw payloads: Store raw JSON before processing so you can replay events if your handler has a bug.
• Handle unknown events gracefully: Return 200 for event types you don't recognise — new event types may be added in future.