hoastnow — Community-Powered Brand Engagement

Overview

Base URL https://app.hoastnow.com/api/v1

Content type application/json

Authentication Bearer token (Authorization header)

HTTP Status Codes

Code	Meaning
`200`	OK — request succeeded, response body contains the result
`201`	Created — resource created successfully (e.g. new booking)
`204`	No Content — request succeeded, no response body (e.g. DELETE)
`400`	Bad Request — missing or malformed request body / query parameter
`401`	Unauthorized — API key missing or invalid
`403`	Forbidden — key does not have the required permission for this endpoint
`404`	Not Found — resource does not exist or is not accessible to this key
`422`	Unprocessable Entity — business rule violation (e.g. slot no longer available)
`500`	Internal Server Error — unexpected server-side failure

Authentication

All API requests must include a valid API key in the Authorization header using the Bearer scheme. Keys are generated from the hoastnow platform and are non-expiring until revoked.

Key Scopes

Scope	Description
Community	Issued to a community (property). Sees bookings and availability for spaces belonging to that community.
Brand	Issued to a brand account. Can create booking requests and read own bookings only.

Permission Flags

Permission	Value	Description
`ReadAvailability`	1	Query available time slots for spaces
`ReadBookings`	2	List bookings (scoped by key type)
`WriteBookings`	4	Create booking requests (Brand keys only)
`ReadReviews`	8	Read community and space reviews
`Webhooks`	16	Register and manage webhook endpoints

HTTP Header

Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx

cURL

curl https://app.hoastnow.com/api/v1/spaces/42/availability \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx" \
  -G --data-urlencode "date=2026-04-15"

Availability

GET /spaces/{spaceId}/availability ReadAvailability

Returns the available time slots for a space on a specific date. The response includes the community's booking window, the duration per event, and an array of individual hour slots showing availability.

Query Parameters

Parameter	Type	Required	Description
`date`	string	required	Date to check in `YYYY-MM-DD` format. Must be today or a future date.

Response Model — `AvailabilityResponse`

Field	Type	Description
`spaceId`	integer	Unique identifier of the space
`spaceName`	string	Display name of the space
`date`	string (date)	The queried date in YYYY-MM-DD format
`windowStart`	integer (0–23)	Earliest available hour for this space
`windowEnd`	integer (0–23)	Latest hour in the booking window
`durationHours`	number	Fixed event duration defined by the community
`timeSlots`	array	Array of `TimeSlot` objects (see below)

TimeSlot Object

Field	Type	Description
`hour`	integer (0–23)	The starting hour in 24-hour format
`label`	string	Human-readable label, e.g. `"9:00 AM"`
`isAvailable`	boolean	Whether this slot is open for booking

cURL

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

JSON — 200 OK

{
  "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 },
    { "hour": 12, "label": "12:00 PM", "isAvailable": true  },
    { "hour": 13, "label": "1:00 PM",  "isAvailable": true  },
    { "hour": 14, "label": "2:00 PM",  "isAvailable": false },
    { "hour": 15, "label": "3:00 PM",  "isAvailable": true  }
  ]
}

Bookings

GET /bookings ReadBookings

Returns a list of bookings visible to the authenticated key. Community keys see all bookings for spaces within their community. Brand keys see only bookings they created.

Query Parameters

Parameter	Type	Required	Description
`startDate`	string	optional	Filter bookings on or after this date (`YYYY-MM-DD`)
`endDate`	string	optional	Filter bookings on or before this date (`YYYY-MM-DD`)
`status`	string	optional	Filter by status: `Pending`, `Approved`, `Cancelled`, `Completed`

cURL

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

JSON — 200 OK

[
  {
    "id": 1001,
    "spaceId": 42,
    "spaceName": "Sunset Clubhouse",
    "date": "2026-04-15",
    "startHour": 10,
    "endHour": 13,
    "status": "Approved",
    "totalPrice": 330.00,
    "createdAt": "2026-04-01T14:22:00Z"
  }
]

POST /bookings WriteBookings

Submits a booking request for a space on behalf of the authenticated Brand key. The booking enters a Pending state and must be approved by the community. This endpoint is only available to Brand-scoped keys.

Pricing: The total price is calculated as (pricePerHour × durationHours) × 1.1. The 10% service fee is automatically included. The totalPrice field in the response reflects the final amount the brand will be charged upon approval.

Request Body

Field	Type	Required	Description
`spaceId`	integer	required	The ID of the space to book
`startTime`	string (date)	required	Requested date in `YYYY-MM-DD` format
`startHour`	integer (0–23)	required	Requested start hour in 24-hour format
`message`	string	optional	Optional note to the community (max 500 characters)

cURL

curl -X POST https://app.hoastnow.com/api/v1/bookings \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": 42,
    "startTime": "2026-04-15",
    "startHour": 10,
    "message": "Launching our new product line."
  }'

JSON — 201 Created

{
  "id": 1002,
  "spaceId": 42,
  "spaceName": "Sunset Clubhouse",
  "date": "2026-04-15",
  "startHour": 10,
  "endHour": 13,
  "status": "Pending",
  "totalPrice": 330.00,
  "createdAt": "2026-04-02T09:14:00Z"
}

Reviews

GET /communities/{communityId}/reviews ReadReviews

Returns all reviews for a community. Community keys can only access reviews for their own community. Brand keys can access reviews for any community they have a completed booking with.

Path Parameters

Parameter	Type	Description
`communityId`	integer	The ID of the community whose reviews to retrieve

cURL

curl https://app.hoastnow.com/api/v1/communities/7/reviews \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx"

JSON — 200 OK

[
  {
    "id": 55,
    "propertyId": 7,
    "spaceId": 42,
    "rating": 5,
    "title": "Perfect venue for our product launch",
    "content": "The space was immaculate and the community team was responsive throughout.",
    "isVerifiedBooking": true,
    "createdAt": "2026-03-20T11:30:00Z"
  }
]

Webhooks

Webhooks deliver real-time notifications to your server when events occur on hoastnow. Register an HTTPS endpoint and select which event types to listen for. Each delivery includes a signature header for verification.

GET /webhooks Webhooks

Lists all webhook endpoints registered to this API key.

cURL

curl https://app.hoastnow.com/api/v1/webhooks \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx"

POST /webhooks Webhooks

Registers a new webhook endpoint. The response includes a signingSecret that is shown only once — store it securely. It is used to verify that webhook deliveries originate from hoastnow.

Event Types (Bitmask)

Event	Value	Description
`BookingRequested`	1	A new booking request was submitted
`BookingApproved`	2	A booking request was approved by the community
`BookingCancelled`	4	A booking was cancelled by either party
`ReviewPosted`	8	A new review was submitted for a space

Pass a bitmask sum to subscribe to multiple events. For example, events: 3 subscribes to BookingRequested (1) and BookingApproved (2). Use 15 to subscribe to all events.

Request Body

Field	Type	Required	Description
`url`	string (URL)	required	Your HTTPS endpoint that will receive webhook deliveries
`events`	integer	required	Bitmask of event types to subscribe to (see table above)

cURL

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

JSON — 201 Created

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

Store the signing secret immediately. The signingSecret is shown only once in the creation response. It cannot be retrieved again. If lost, delete the webhook and create a new one.

DELETE /webhooks/{id} Webhooks

Permanently removes a webhook registration. hoastnow will stop delivering events to the associated URL. Returns 204 No Content on success.

cURL

curl -X DELETE https://app.hoastnow.com/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer hoa_live_xxxxxxxxxxxxxxxxxxxx"

Signature Verification

Every webhook delivery includes an X-Hoastnow-Signature header containing an HMAC-SHA256 signature of the raw request body, computed using your signing secret. Always verify this signature before processing a payload.

JSON payload

{
  "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
  }
}

cURL

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

Models

Schema reference cards for all objects returned by the API.

BookingDto

Field	Type	Description
`id`	integer	Unique booking identifier
`spaceId`	integer	ID of the booked space
`spaceName`	string	Display name of the space
`date`	string (date)	Booking date in YYYY-MM-DD format
`startHour`	integer (0–23)	Event start time in 24-hour format
`endHour`	integer (0–23)	Event end time in 24-hour format
`status`	string	`Pending` \| `Approved` \| `Cancelled` \| `Completed`
`totalPrice`	number	Total amount charged (includes 10% service fee)
`createdAt`	string (ISO 8601)	UTC timestamp when the booking was created

AvailabilityResponse

Field	Type	Description
`spaceId`	integer	Space identifier
`spaceName`	string	Space display name
`date`	string (date)	Queried date
`windowStart`	integer	Community booking window open hour
`windowEnd`	integer	Community booking window close hour
`durationHours`	number	Fixed event duration defined by the community
`timeSlots`	array<TimeSlot>	Per-hour availability array

ReviewDto

Field	Type	Description
`id`	integer	Review identifier
`propertyId`	integer	Community (property) the review belongs to
`spaceId`	integer	Specific space reviewed
`rating`	integer (1–5)	Star rating
`title`	string	Review headline
`content`	string	Full review body text
`isVerifiedBooking`	boolean	Whether the reviewer completed a booking
`createdAt`	string (ISO 8601)	UTC timestamp of submission

WebhookDto

Field	Type	Description
`id`	string	Webhook registration identifier
`url`	string	Registered HTTPS endpoint URL
`events`	integer	Subscribed events bitmask
`createdAt`	string (ISO 8601)	UTC registration timestamp

WebhookCreatedDto

Returned only on POST /webhooks. Extends WebhookDto with the one-time signing secret.

Field	Type	Description
`id`	string	Webhook identifier
`url`	string	Registered endpoint URL
`events`	integer	Events bitmask
`signingSecret`	string	HMAC-SHA256 secret for signature verification. Shown once only.
`createdAt`	string (ISO 8601)	UTC registration timestamp

Errors

All error responses use a consistent JSON body. Check the HTTP status code first, then inspect the error field for a machine-readable message and details for additional context.

Common Error Codes

Error Code	HTTP Status	Description
`InvalidApiKey`	401	API key is missing, malformed, or revoked
`InsufficientPermissions`	403	Key exists but lacks the required permission flag
`ResourceNotFound`	404	The requested resource does not exist or is not accessible to this key
`ValidationError`	400	Required field missing or parameter value is invalid
`SlotUnavailable`	422	The requested time slot is already booked or outside the booking window
`BookingNotAllowed`	422	Business rule prevents the booking (e.g. space inactive, date in the past)
`ScopeViolation`	403	Brand key attempted an action only available to Community keys, or vice versa
`InternalError`	500	Unexpected server error — safe to retry with exponential backoff

JSON — 422 Unprocessable Entity

{
  "error": "SlotUnavailable",
  "details": "The requested time slot (hour 10) on 2026-04-15 is no longer available."
}

Overview

HTTP Status Codes

Authentication

Key Scopes

Permission Flags

Availability

Query Parameters

Response Model — AvailabilityResponse

TimeSlot Object

Bookings

Query Parameters

Request Body

Reviews

Path Parameters

Webhooks

Event Types (Bitmask)

Request Body

Signature Verification

Models

BookingDto

AvailabilityResponse

ReviewDto

WebhookDto

WebhookCreatedDto

Errors

Common Error Codes

Response Model — `AvailabilityResponse`