API keys

Overview

An API key lets a system you control talk to Bella on your business’s behalf. The two things people build most often are:

A booking form on your own website — read your services, check availability, then create the client and the appointment.
A sync into another system — pull your clients and appointment history into a CRM, a data warehouse or a backup.

Appointments created through the API appear in your scheduler like any other, your clients get the same confirmation messages, and the Booking source report attributes them to Integration so you can tell them apart. You create, edit and revoke keys yourself in Settings → Integrations. Nobody at Bella needs to be involved.

A key belongs to one location. If you run more than one location, switch to that location before creating its key. A key can never be moved to a different location.

Quickstart

Four calls take a visitor from “what do you offer?” to a booked appointment.

# 1 — what can be booked, and at what price
curl https://api.bellabooking.com/api/servicecategories \
  -H "x-api-key: $BELLA_API_KEY"

# 2 — when is it free
curl -G https://api.bellabooking.com/api/Appointments/availability \
  -H "x-api-key: $BELLA_API_KEY" \
  --data-urlencode 'startDate=2026-08-04' \
  --data-urlencode 'endDate=2026-08-09' \
  --data-urlencode 'teamMemberId=any' \
  --data-urlencode 'services=[{"serviceId":"6839...c1"}]'

# 3 — who is booking (creates, or returns the existing client)
curl -X POST https://api.bellabooking.com/api/Clients \
  -H "x-api-key: $BELLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Ava","lastName":"Nguyen","email":"ava@example.com","phoneNumber":"0412 345 678"}'

# 4 — book it
curl -X POST https://api.bellabooking.com/api/Appointments \
  -H "x-api-key: $BELLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "clientId": "6840...9f",
        "appointmentDate": "2026-08-05",
        "services": [{
          "serviceId": "6839...c1",
          "teamMemberId": "6837...a4",
          "startTime": "14:00:00",
          "price": 120,
          "durationInMinutes": 60
        }]
      }'

You supply the price and duration, and Bella records what you send. They are not re-read from your catalogue at booking time.Always take price and durationInMinutes from the catalogue response in step 1 rather than hard-coding them, or a price change in Bella won’t reach your website. See Pricing your booking correctly.

Authentication

Send the key in the x-api-key header on every request. You never need to say which location — the key already knows.

curl https://api.bellabooking.com/api/servicecategories \
  -H "x-api-key: bella_live_7Kq2v9xR4mNp_a3F9…"

Keys are stored hashed, so nobody — including us — can read one back after it’s created. If you lose it, revoke it and create another.

Status	Meaning
`401`	The header is missing, malformed, or the key has been revoked or deleted
`403`	The key is valid but doesn’t have the permission this endpoint needs, or API access isn’t enabled for your account

Managing keys

Open Settings → Integrations

You’ll need permission to manage settings. You can only grant a key permissions you hold yourself.

Name it after what will use it

“Website booking”, “CRM sync”, “Ops bot” — so the Last used column tells you something useful later.

Choose what it can do

Tick only what that integration actually needs. You can change this later without reissuing the key.

Copy the key

It’s shown once. Store it as an environment variable on your server. If you lose it, revoke it and create another.

From the ⋯ menu next to any key:

Edit — rename it or change its permissions. The key itself never changes, so whoever is using it doesn’t have to do anything.
Revoke — stop it working, keep the row so you can still see when it was last used. This cannot be undone.
Delete — remove it from the list entirely. If the key was still active this also stops it working.

Edits, revocations and deletions all take effect within a minute rather than instantly — keys are cached briefly to keep requests fast.

Permissions

Permission	Scope	Opens
Read services & prices	`catalog:view`	`GET /api/servicecategories`
Check availability	`availability:read`	`GET /api/Appointments/availability`
Create a client	`clients:create`	`POST /api/Clients`
Read client records	`clients:view`	`GET /api/Clients/search`, `GET /api/Clients/{id}`
Create an appointment	`appointments:create`	`POST /api/Appointments`
Read appointments	`appointments:read`	`GET /api/Appointments/search`, `GET /api/Appointments/{id}`
Reschedule an appointment	`appointments:edit`	`POST /api/Appointments/{id}/reschedule`
Cancel an appointment	`appointments:cancel`	`POST /api/Appointments/{id}`

Everything else returns 403. A key cannot reach sales, reports, payments, team management, settings, or the API keys themselves — no key can ever create another key.

Give each integration its own key with only the permissions it needs. A website booking form needs the four in the first block; a read-only CRM sync needs only the two view permissions.

API reference

Base URL: https://api.bellabooking.com Requests and responses are JSON. All ids are strings. Dates are YYYY-MM-DD; times of day are HH:MM:SS.

List the catalogue

GET /api/servicecategories

Returns your categories, each containing its services and bundles, with prices, durations, variants, pricing tiers and add-on groups.

{
  "data": [{
    "id": "6838...b7",
    "name": "Colour",
    "services": [{
      "id": "6839...c1",
      "name": "Full head colour",
      "price": 120,
      "durationInMinutes": 60,
      "disabledForOnlineBooking": false,
      "requiresMembership": false,
      "useVariants": false,
      "usePricingTiers": false
    }],
    "bundles": []
  }]
}

This returns your full catalogue, including services you’ve switched off for online booking. Filter on disabledForOnlineBooking before showing anything to a visitor, or your website will offer services you’ve deliberately taken offline.Check requiresMembership too if you use members-only services — the API will book them for a non-member. The same applies to prerequisiteServiceIds / prerequisiteRequirement / prerequisiteMatchMode — the API does not enforce prerequisite gates.

Check availability

GET /api/Appointments/availability

Parameter	Required	Description
`startDate`	yes	First date to check, `YYYY-MM-DD`
`endDate`	no	Last date to check. Defaults to `startDate`
`teamMemberId`	yes	A team member id, or `any` to let Bella pick whoever is free
`services`	yes	JSON array of the cart, e.g. `[{"serviceId":"…","variantId":"…"}]`
`preferredTime`	no	Biases slot ordering towards a time of day

{
  "days": [{
    "date": "2026-08-05",
    "slotCount": 14,
    "timeSlots": [{
      "startTime": "14:00:00",
      "endTime": "15:00:00",
      "availableTeamMemberIds": ["6837...a4"],
      "availableTeamMemberNames": ["Priya"]
    }]
  }],
  "allowJoinWaitlist": false
}

Pass variantId and any addons in the cart where the service uses them, so the slots you get back match the real length of the appointment.

Availability reflects rosters, existing appointments and blocked time. It uses your dashboard’s view rather than your booking page’s, so it does not apply your minimum-notice period or gap-reduction settings — see Booking rules.

Create or match a client

POST /api/Clients

Field	Required	Description
`firstName`	yes
`lastName`	no
`email`	no	Required unless `phoneNumber` is given
`phoneNumber`	no	Required unless `email` is given. Parsed for your business’s country

If the email or phone already belongs to one of your active clients, that client’s id is returned instead of a duplicate being created — so a returning client filling in your form doesn’t create a second record.

{ "id": "6840...9f" }

Either way you can go straight on to the booking with the id you get back.

Create an appointment

POST /api/Appointments

Field	Required	Description
`clientId`	yes	From the previous step
`appointmentDate`	yes	`YYYY-MM-DD`
`services`	yes	One entry per service line
`services[].serviceId`	yes
`services[].startTime`	yes	`HH:MM:SS`
`services[].price`	yes	See the warning below
`services[].durationInMinutes`	yes	See the warning below
`services[].teamMemberId`	no	Omit only for services that need no team member
`services[].variantId`	no	Required where the service uses variants
`services[].bundleId`	no	Tags the line as part of a bundle
`services[].addons`	no	`[{ "optionGroupId": "…", "optionId": "…" }]`

{ "id": "6841...2c", "warning": null }

Pricing your booking correctly

Bella records the price and durationInMinutes you send. It does not re-read them from your catalogue. That means:

Always read them from GET /api/servicecategories at booking time. Hard-coded prices go stale the moment you change a price in Bella.
Where a service uses variants, take the price and duration from the chosen variant, not the base service.
Where a service uses pricing tiers, take them from the tier matching the assigned team member.
Add-ons add their own price and duration on top of the service line.

Getting this wrong doesn’t fail — it books at the price you sent, and that’s what the client is charged at checkout.

Booking rules

Bookings made with an API key are recorded with the same checks your front desk gets, not the stricter ones your public booking page gets. Bella will accept a booking that:

double-books a team member
is in the past, or inside your minimum-notice period
is with a team member who isn’t qualified for that service
is a members-only service for someone without a membership
has unmet prerequisite services (a treatment that online booking would lock until a consult is booked or completed)
would have needed your approval if it came through your own booking page

Check availability first and only offer slots that came back from it. That is what keeps a website booking honest.

Services that need a room or piece of equipment can’t be booked through the API yet. Your own booking page assigns one automatically; the API doesn’t, so it returns a clear error asking for a resource.

Reschedule an appointment

POST /api/Appointments/{id}/reschedule

Field	Required	Description
`appointmentDate`	yes	The new date, `YYYY-MM-DD`
`startTime`	yes	The new start time, `HH:MM:SS`

Every service line moves together, keeping the gaps between them. The client gets your usual reschedule message.

Cancel an appointment

POST /api/Appointments/{id}

Field	Required	Description
`reasonId`	no	Your cancellation reason
`cancellationNote`	no	Free text kept on the appointment

Packages, memberships, gift-card balances, loyalty points and promo codes the appointment used are restored automatically.

Cancelling through the API does not apply your cancellation-fee policy — no fee is charged and no policy-based refund is calculated, the same as a front-desk cancellation. If you charge for late cancellations, apply that in your own system or from the dashboard.

Read clients

GET /api/Clients/search
GET /api/Clients/{id}

search accepts filter (name, email or phone), limit, skip and a range of filters including createdAfter, createdBefore, lastAppointmentAfter and tags.

Read appointments

GET /api/Appointments/search
GET /api/Appointments/{id}

search requires startDate and endDate, and accepts teamMemberIds, serviceIds, statusIds, clientFilter, limit, skip and orderBy.

Read endpoints return the full internal record — including private notes, client timeline notes and their attachments, card-on-file details and payment links.Never pass these responses straight through to a browser. Read them on your server, keep only the fields you need, and treat anything you store as you would the records in your dashboard.

There’s no incremental cursor yet. A sync re-reads the date or page range it asks for. Deleted records leave no tombstone, so a full reconciliation is more reliable than a running total.

Errors

Errors are returned as JSON with an HTTP status and a detail explaining what went wrong.

Status	Meaning	What to do
`400`	The request was invalid — a missing field, a bad id, a rule that failed	Read `detail`; don’t retry unchanged
`401`	Missing, malformed or revoked key	Check the header and that the key is still active
`403`	The key lacks the permission this endpoint needs	Add the permission in Settings → Integrations
`404`	No such record in this location	Remember a key only ever sees its own location
`422`	The request was understood but couldn’t be completed	Read `detail`
`429`	Rate limited	Wait for `Retry-After` seconds, then retry
`5xx`	Something went wrong at our end	Retry with backoff; if it persists, contact us

{
  "title": "Validation error",
  "status": 400,
  "detail": "An email address or a phone number is required."
}

Rate limits

Limits are applied per key, per minute.

Limit	Value
Requests overall	150 per minute, burstable
Writes (anything that isn’t a `GET`)	5 per minute — contact the Bella Booking team to increase it
Requests in flight at once	10

Exceeding a limit returns 429 with a Retry-After header. Wait that many seconds and retry — don’t retry immediately in a loop.

The write limit is sized for a real booking form rather than a bulk import — so if you’re migrating data or running a busier site, ask us to raise it rather than working around it. These limits protect your business’s own performance and may change; they aren’t a service guarantee.

Keeping your key safe

Never put an API key in code a visitor’s browser can read. Anyone who can see it can act as your business. Keep it on your own server and call Bella from there.

Store it as an environment variable or in a secrets manager, never in your source code.
Give each integration its own key, so you can revoke one without breaking the others.
Revoke a key the moment it’s no longer needed, or the moment you suspect it’s been exposed.
Narrow a key’s permissions when an integration stops needing something — editing is safer than leaving a key more capable than it has to be.
Your key can read and change real client data. Treat it like the password to your dashboard.

Tell us what you’re building — it genuinely shapes what we build next.

Getting started

Main

Catalogue

Programmes

Insights

Settings

Developers

Overview

Quickstart

Authentication

Managing keys

Permissions

API reference

List the catalogue

Check availability

Create or match a client

Create an appointment

Pricing your booking correctly

Booking rules

Reschedule an appointment

Cancel an appointment

Read clients

Read appointments

Errors

Rate limits

Keeping your key safe

​Overview

​Quickstart

​Authentication

​Managing keys

​Permissions

​API reference

​List the catalogue

​Check availability

​Create or match a client

​Create an appointment

​Pricing your booking correctly

​Booking rules

​Reschedule an appointment

​Cancel an appointment

​Read clients

​Read appointments

​Errors

​Rate limits

​Keeping your key safe

Overview

Quickstart

Authentication

Managing keys

Permissions

API reference

List the catalogue

Check availability

Create or match a client

Create an appointment

Pricing your booking correctly

Booking rules

Reschedule an appointment

Cancel an appointment

Read clients

Read appointments

Errors

Rate limits

Keeping your key safe