Documentation
Docs
Guides to connect to the booking API and add the booking widget to your site.
Sample (mock): URLs, keys and responses are not real and only show the shape of the documentation.
- Base URL
- https://api.example.com/v1
- Version
- v1
Getting started
Introduction
The booking API lets you read and create provider profiles, services, free slots and bookings from your own app. If you only need a booking button, use the widget instead.
https://api.example.com/v1All responses are JSON and times are returned as ISO 8601 in the provider’s time zone.
Getting started
Quickstart
Create your first booking in three steps: fetch services, find a free slot, then book it.
# 1) list services
curl https://api.example.com/v1/providers/ilia-salon/services \
-H "Authorization: Bearer hg_test_xxxxxxxx"
# 2) find free slots
curl "https://api.example.com/v1/providers/ilia-salon/availability?service=svc_color&date=2026-10-10" \
-H "Authorization: Bearer hg_test_xxxxxxxx"
# 3) book one
curl -X POST https://api.example.com/v1/bookings \
-H "Authorization: Bearer hg_test_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"service":"svc_color","start":"2026-10-10T10:30:00+03:30"}'Getting started
Authentication
Every request must send the API key in the Authorization header. hg_test keys only touch sample data; hg_live keys touch real data.
Authorization: Bearer hg_test_xxxxxxxxNever put the key in browser-side code. For customer-facing booking use the widget or your own server.
Booking API
Providers
GET/providers/{slug}
Returns the public profile of a provider or business.
| Name | Type | Required | Description |
|---|---|---|---|
| slug | string | Yes | The unique identifier in the profile link. |
{
"slug": "ilia-salon",
"name": "Ilia Salon",
"kind": "business",
"timezone": "Asia/Tehran",
"services": 3
}Booking API
Services
GET/providers/{slug}/services
Lists bookable services; each service has a fixed or variable duration.
{
"data": [
{ "id": "svc_cut", "name": "Haircut", "duration": 45, "fixed": true },
{ "id": "svc_color", "name": "Colour & highlights", "duration": 90, "fixed": true },
{ "id": "svc_skin", "name": "Skin cleansing", "duration": null, "fixed": false }
]
}Booking API
Availability
GET/providers/{slug}/availability
Computes the free slots of a day in real time from the provider’s calendar.
| Name | Type | Required | Description |
|---|---|---|---|
| service | string | Yes | The service id. |
| date | YYYY-MM-DD | Yes | The day to check. |
| context | "independent" | "business" | No | Booking context; defaults to the profile’s context. |
/providers/ilia-salon/availability?service=svc_color&date=2026-10-10Booking API
Bookings
POST/bookings
Creates a booking. If the slot was taken, a 409 is returned.
| Name | Type | Required | Description |
|---|---|---|---|
| service | string | Yes | The service id. |
| start | ISO 8601 | Yes | Booking start; must be one of the free slots. |
| customer | object | No | Name and phone; read from the signed-in customer if omitted. |
| note | string | No | A note for the provider. |
{
"id": "bk_8f2a",
"status": "confirmed",
"service": "svc_color",
"start": "2026-10-10T10:30:00+03:30",
"end": "2026-10-10T12:00:00+03:30"
}DELETE/bookings/{id}
Cancels the booking and frees the slot again.
Booking API
Customers
GET/customers/{id}
Returns the customer profile and booking history for the provider.
{
"id": "cus_31c9",
"bookings": 6,
"last_visit": "2026-09-21",
"notes": ["prefers mornings"]
}Booking API
Webhooks
Register a URL to be told when bookings change — events such as booking.created and booking.cancelled. Each request is signed with the X-Signature header.
{
"event": "booking.created",
"data": { "id": "bk_8f2a", "service": "svc_color", "start": "2026-10-10T10:30:00+03:30" }
}Booking widget
Embedding the widget
The booking widget is added to your site with two lines — no server and no API key.
<script src="https://cdn.example.com/booking-widget.js" defer></script>
<div data-booking-widget="ilia-salon"></div>Booking widget
Widget options
| Name | Type | Required | Description |
|---|---|---|---|
| data-booking-widget | string | Yes | The provider slug. |
| data-theme | "dark" | "light" | No | Display theme. |
| data-lang | "fa" | "en" | No | Widget language and direction. |
| data-service | string | No | Pre-selects a service. |
Booking widget
Widget events
The widget dispatches browser events on its own element, so you can for instance show a thank-you message.
document
.querySelector("[data-booking-widget]")
.addEventListener("booking:confirmed", (e) => {
console.log("confirmed", e.detail.id);
});Reference
Errors
Errors come back with an HTTP status and a JSON body containing code and message.
| Name | Type | Required | Description |
|---|---|---|---|
| 400 | invalid_request | No | Invalid or missing parameter. |
| 401 | unauthorized | No | Missing or invalid key. |
| 404 | not_found | No | Provider, service or booking not found. |
| 409 | slot_taken | No | The slot has just been booked. |
| 429 | rate_limited | No | Too many requests. |
{
"error": { "code": "slot_taken", "message": "This slot is no longer free." }
}Reference
Rate limits
Each key may make up to 60 requests per minute. The X-RateLimit-Remaining and Retry-After headers show where you stand.
Reference
Changelog
| Name | Type | Required | Description |
|---|---|---|---|
| v1.2 | 2026-10 | No | Widget: booking:confirmed event and the data-service option. |
| v1.1 | 2026-09 | No | Webhooks and the X-Signature header. |
| v1.0 | 2026-08 | No | First release: providers, services, availability and bookings. |
Still stuck?
Talk to us