Zenoti API: A Developer's Field Guide

Zenoti's API is solid REST. If you've worked with any modern JSON API, the shape will feel familiar: predictable URL patterns, standard HTTP verbs, and JSON request/response bodies. This guide covers authentication, the endpoints you actually need for an online booking integration, the rate-limit behavior you'll hit in production, and the gap between "I can call an endpoint" and "this is reliable enough to take real bookings."

Disclosure:We're BookerKit. We sell a wrapper for the Zenoti booking funnel. This guide is honest about what's easy, what's hard, and where our product fits. If you want to build your own integration, everything here will help.

Zenoti API at a Glance

BookerKit touches a focused slice of the API surface: services, therapists, availability slots, guests, bookings, and payments/invoices. Everything else (inventory, payroll, marketing campaigns, etc.) is outside our scope but follows the same conventions.

Authentication

Every request carries an API key in the Authorization header:

Authorization: apikey YOUR_API_KEY

Keys are issued per center. If you manage multiple locations, each one has its own key. Keep keys server-side — never expose them in client-side JavaScript or embed code.

If you're using BookerKit, you add the key once in the dashboard and we handle it from there. See the Getting Started guide for setup.

Endpoints for Online Booking

These are the endpoints that matter for a booking integration, roughly in the order you'll call them.

GET /v1/Centers/{center_id}/services

GET /v1/centers/{center_id}/services/{service_id}/therapists

POST /v1/guests

{
  "center_id": "your-center-id",
  "personal_info": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "mobile_phone": {
      "country_code": 225,
      "number": "5551234567"
    }
  }
}

The Referral Source Gotcha

Some Zenoti organizations require a referral.referral_sourcefield in the create-guest payload. If it's missing, the call fails silently or returns a vague error. This isn't always documented clearly — check with your Zenoti admin whether referral source is a required field for guest creation in your org. If it is, you'll need to include it in every guest creation request.

Rate Limits

Zenoti returns rate-limit information in response headers:

• RateLimit-Remaining — requests left in the current window
• RateLimit-Reset — seconds until the window resets
• RateLimit-Limit — total requests allowed per window

The numeric ceiling can vary by org configuration and endpoint. When you hit a 429 Too Many Requests, back off using exponential backoff with jitter. A simple strategy:

// Exponential backoff with jitter
const backoff = (attempt: number): number => {
  const base = Math.min(1000 * Math.pow(2, attempt), 30000)
  const jitter = Math.random() * base * 0.1
  return base + jitter
}

For write operations (creating guests, confirming bookings), use idempotency keys so retries don't create duplicates. And always set request timeouts — a hung connection against a rate-limited API will cascade failures through your stack.

3D Secure and Payment Redirects

When Zenoti returns a hosted_payment_uriin the payment response, the guest needs to complete card entry (and potentially 3D Secure verification) on Zenoti's hosted page. This means:

• You redirect the guest away from your site to the hosted URI
• After completion, Zenoti redirects back to your callback URL
• You need to handle the redirect back — check payment status, confirm the booking, and show the confirmation screen

The redirect flow adds UX friction. The guest leaves your page, enters a card on a Zenoti-branded page, and comes back. If your booking widget runs in an iframe, the redirect gets more complex because you need to break out of the iframe context for the payment page.

Webhooks

Zenoti supports webhooks for booking lifecycle events — creation, confirmation, cancellation, rescheduling, and no-shows. You register a callback URL in the Zenoti admin, and Zenoti sends a POST request when events fire.

If you're using BookerKit, you can also subscribe to booking_started and booking_completed events from BookerKit's signed webhook system. These include UTM parameters and click-ID attribution data that Zenoti's native webhooks don't carry.

Regardless of which webhook system you use, validate signatures on incoming payloads and protect your endpoint against SSRF. Never trust the source IP alone — always verify the cryptographic signature.

What a Production Wrapper Handles

The gap between "I can hit the endpoint" and "this handles real bookings reliably" is where most of the work lives:

• Transport & reliability — Retry logic, circuit breakers, timeout handling, rate-limit backoff, connection pooling
• Security — Key rotation, key-per-center management, server-side-only API calls, PCI scope management for payments
• Booking correctness — Slot expiration handling, draft cleanup, duplicate guest prevention, referral source injection, payment state machines
• Observability — Request logging, error tracking, latency monitoring, alert on failed bookings, audit trail for every booking attempt

BookerKit handles all of this out of the box. If you're building your own, budget 3-4x the time you think the "happy path" will take.

When to Build vs. Use a Wrapper

Build your own when you need API surface beyond booking — inventory management, payroll, marketing campaigns, custom reporting, or workflows that span multiple Zenoti endpoints in ways a booking widget never would.

Use BookerKit when the booking funnel is your scope and you want attribution data (UTMs, click IDs) flowing through the entire flow. BookerKit gives you a white-label widget, conversion tracking, webhook events with attribution, and the production reliability layer described above — without building or maintaining any of it.

Frequently Asked Questions