Explore Vuzol — interactive product demo

For your website

Integrations for Beauty Studio

Add online booking as a widget or connect your own server-side integration through the API.

Booking widget for your website

Large and compact widgets are available on Pro and Pro+. Paste the ready-made code into your website HTML so customers can complete booking without leaving the page.

<iframe data-vuzol-booking-widget="large" src="https://vzl.one/embed/book/demo-business" title="Online booking — Beauty Studio" loading="lazy" style="width:100%;min-height:720px;border:0;border-radius:24px;"></iframe>
<script async src="https://vzl.one/static/booking-widget-loader.js"></script>

<iframe data-vuzol-booking-widget="compact" src="https://vzl.one/embed/book/demo-business/compact" title="Online booking — Beauty Studio" loading="lazy" style="width:100%;min-height:360px;border:0;border-radius:20px;"></iframe>
<script async src="https://vzl.one/static/booking-widget-loader.js"></script>

API tokens

Create a separate token for each website or server-side integration.

There are no active API tokens yet.

API v1

Secure booking integration

The API intentionally has narrow access and is tied to the selected business.

It can retrieve services, team members and availability, and create a booking.
It cannot access the client list, CRM, or booking history.
Call the API only from your server—never embed the token in website JavaScript.

PUBLIC API · V1

Booking API documentation

A complete server-side integration reference for online booking: retrieve services and availability, create bookings safely, and handle every expected error.

REST JSON Bearer token HTTPS

Base URL https://vzl.one/api/v1/booking

Exchange format JSON requests and responses

Request limit 120 GET / 30 POST per 60 sec

Recommended integration flow

Always retrieve current identifiers and availability from the API before creating a booking.

1
Retrieve servicesShow active services to the client and retain the service_id.
2
Choose a specialistFilter the team by service_id and retain the employee_id.
3
Check availabilityFetch a fresh list of slots immediately before confirmation.
4
Create the bookingSend the exact starts_at value returned by availability.

Authorization for every request

Add a Bearer token to the Authorization header. Each token is scoped to one business.

Server-to-server only

HTTP headers

Authorization: Bearer $VUZOL_API_TOKEN
Accept: application/json

Each token allows up to 120 read requests and 30 write requests per 60 seconds. A 429 response includes a Retry-After header with the number of seconds to wait.

Errors and safe recovery

The API returns a standard HTTP status and a detail field with an explanation. Do not retry booking creation until you have checked the error reason.

401

Missing or invalid token

The Bearer token is missing, revoked, or malformed. Create a new token or verify the Authorization header.

403

Business unavailable

The business was removed, disabled, or no longer belongs to the token owner.

404

Resource not found

The service, team member, or business identifier does not exist or is not available for online booking.

409

Booking creation conflict

The slot is taken, closed, in the past, or became unavailable because of a schedule change, break, day off, closed date, or temporary business closure.

422

Invalid data

A required field is missing or blank, the phone is invalid, or a query parameter does not match the expected format or range.

429

Too many requests

The token limit has been reached. Wait for the number of seconds in Retry-After and then send the request again.

What to do when a slot is closed or already taken

Availability is a snapshot at the time of the request. Another client or an administrator can book or close the slot before your POST request, so only a 201 response from appointments is final confirmation.

Call availability again with the same service_id and employee_id.
Show the refreshed list and ask the client to choose a different starts_at.
Retry POST only with the new starts_at value; never loop on the old slot.

HTTP/1.1 409 Conflict
Content-Type: application/json

{"detail":"This slot is no longer available. Please choose another time."}

Error format For most responses, detail is a string. For FastAPI validation errors, detail may be an array containing the field name and reason.

Endpoints and examples

Every section is open, so parameters, ready-to-use curl requests, response examples, and errors are visible without extra clicks.

All sections open

GET/api/v1/booking/businessPublic details for this business

Returns details for the business scoped to the token, including its public booking page URL.

ParametersNo additional parameters are required.

Request example

curl -H "Authorization: Bearer $VUZOL_API_TOKEN" \
  https://vzl.one/api/v1/booking/business

200 · Response

{
  "data": {
    "id": "business_01",
    "name": "Vuzol Studio",
    "slug": "vuzol-studio",
    "phone": "+380501112233",
    "address": "Kyiv",
    "logo_url": "https://cdn.example.com/logo.png",
    "booking_url": "https://vzl.one/book/vuzol-studio"
  }
}

Possible errors401 The token is missing, invalid, or revoked.403 The business scoped to this token is unavailable.429 The request limit is exhausted; honor Retry-After.

GET/api/v1/booking/servicesServices available for online booking

Returns only active services that can be booked online. Use the service id in subsequent requests.

ParametersNo additional parameters are required.

Request example

curl -H "Authorization: Bearer $VUZOL_API_TOKEN" \
  https://vzl.one/api/v1/booking/services

200 · Response

{
  "data": [
    {
      "id": "service_01",
      "name": "Consultation",
      "category": "Services",
      "description": "60-minute consultation",
      "duration_minutes": 60,
      "price": 900.0
    }
  ]
}

Possible errors401 The token is missing, invalid, or revoked.403 The business scoped to this token is unavailable.429 The request limit is exhausted; honor Retry-After.

GET/api/v1/booking/teamTeam members for the selected service

Returns active business team members. When service_id is supplied, the list is limited to specialists assigned to that service.

Parameters
Field	Requirement	Description
`service_id`string · query	Optional	A service ID from /services. If omitted, the API returns the entire available team.

Request example

curl -H "Authorization: Bearer $VUZOL_API_TOKEN" \
  "https://vzl.one/api/v1/booking/team?service_id=SERVICE_ID"

200 · Response

{
  "data": [
    {
      "id": "employee_01",
      "full_name": "Iryna Kovalenko",
      "role": "Specialist",
      "photo_url": "https://cdn.example.com/iryna.jpg"
    }
  ]
}

Possible errors404 The supplied service_id was not found.422 A query parameter has an invalid format or length.429 The request limit is exhausted; honor Retry-After.

GET/api/v1/booking/availabilityAvailable dates and time slots

Calculates open slots from service duration, schedules, breaks, vacations, closed dates, existing bookings, and business availability.

Parameters
Field	Requirement	Description
`service_id`string · query	Required	The active online service ID returned by /services.
`employee_id`string · query	Optional	A specialist ID from /team. When omitted, slots for all available team members are returned.
`start_date`date · YYYY-MM-DD	Optional	The first search date. Defaults to the server’s current date.
`days`integer · 1–31	Optional	Number of calendar days to search. Defaults to 7; allowed range is 1 through 31.

For POST /appointments, send starts_at exactly as returned in this list. A time constructed by the client may not match the calendar interval or schedule.

Request example

curl -H "Authorization: Bearer $VUZOL_API_TOKEN" \
  "https://vzl.one/api/v1/booking/availability?service_id=SERVICE_ID&employee_id=EMPLOYEE_ID&start_date=2026-09-10&days=7"

200 · Response

{
  "data": [
    {
      "employee_id": "employee_01",
      "employee_name": "Iryna Kovalenko",
      "starts_at": "2026-09-10T14:00",
      "date": "2026-09-10",
      "time": "14:00"
    }
  ],
  "meta": {
    "service_id": "service_01",
    "employee_id": "employee_01",
    "start_date": "2026-09-10",
    "days": 7
  }
}

Possible errors404 The service or team member was not found.422 A query parameter has an invalid format or length.429 The request limit is exhausted; honor Retry-After.

POST/api/v1/booking/appointmentsCreate a new online booking

Creates or updates the client record by phone, reserves the slot, and returns a public receipt URL for the booking.

Parameters
Field	Requirement	Description
`service_id`string · max 100	Required	The service ID for which the slot was retrieved.
`employee_id`string · max 100	Required	The team member ID from the selected slot.
`starts_at`string · ISO 8601	Required	The exact ISO starts_at value from /availability. Do not reformat or round it.
`client_name`string · max 120	Required	The client name shown in the calendar and CRM.
`client_phone`string · max 40	Required	A valid client contact number, used to find or create the client record.
`notes`string · max 2000	Optional	Optional booking notes. Send an empty string or omit the field when there are no notes.

Request example

curl -X POST https://vzl.one/api/v1/booking/appointments \
  -H "Authorization: Bearer $VUZOL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "SERVICE_ID",
    "employee_id": "EMPLOYEE_ID",
    "starts_at": "2026-09-10T14:00",
    "client_name": "Iryna Kovalenko",
    "client_phone": "+380501112233",
    "notes": "First visit"
  }'

201 · Response

{
  "data": {
    "booking_id": "appointment_01",
    "status": "booked",
    "service_id": "service_01",
    "employee_id": "employee_01",
    "starts_at": "2026-09-10T14:00",
    "ends_at": "2026-09-10T15:00",
    "receipt_url": "https://vzl.one/book/vuzol-studio/appointments/PUBLIC_TOKEN"
  }
}

Possible errors409 The slot is taken or unavailable; the service or team member may also have been deactivated.422 Required data is blank, the phone is invalid, or a field does not match the schema.429 The request limit is exhausted; honor Retry-After.