Booking API integration for salons, spas and clinics

A developer brief for booking API integration: middleware, partner and user tokens, webhook deduplication, rate limits and GDPR roles in Europe.

Booking API integration for salons spas and clinics

A booking API integration that holds up in production follows one pattern: a middleware layer sits between your scheduling platform and every other system, reads free time slots, creates appointments and consumes webhooks when appointments are created, changed or deleted. Hand this brief to your developer, give the integration only the access it needs and settle the GDPR roles before anyone writes code. The examples use the Altegio API, documented on the Altegio developer portal.

Your immediate next steps:

  • Check whether a ready-made app in the Integrations Hub already does the job before you commission custom work.
  • Paste the checklist below into a developer ticket.
  • Decide which user the integration’s user token belongs to and keep that user’s access to what the job needs.
  • Sign a data processing agreement with whoever builds or hosts the middleware.

Key takeaways

Point Details
Start with middleware Put one layer between the platform and every consumer: website, CRM, BI dashboard, AI tools.
Use the right credentials A partner token for the public online booking endpoints; a partner token plus a user token for business data. Keep both in a secrets manager.
Treat webhooks as at-least-once Deduplicate by X-Hook-Id, don’t rely on order and run a reconciliation job for anything missed.
Respect the rate limit 200 requests a minute or 5 a second per IP address: cache services and team members, query time slots live.
Phase the rollout A draft application on your own test Location first, then read-only, assisted and automated stages.
Settle GDPR roles The business is the controller; a developer or agency processing data on its behalf is a processor and needs an Article 28 contract.

Which booking API surfaces do you actually need?

Every booking integration touches the same three flows, whatever the platform: read free time slots, create an appointment and react to changes through webhooks. Everything else (clients, services, payments, analytics) supports those three. In the Altegio API they are spread across three documented sets.

What you need Where it lives in the Altegio API Credentials
Services, team members, dates and free time slots for a booking flow Online Booking API: book_services, book_staff, book_dates, book_times Partner token
Validate and create an online appointment, change its date or time Online Booking API: book_check, book_record Partner token
List, read, edit or delete appointments, change attendance status, see change history Business Management API: /locations/{location_id}/appointments and related methods Partner token + user token
Search and add clients Business Management API: client methods Partner token + user token
Get or send a payment link for an appointment Business Management API: /locations/{location_id}/appointments/{record_id}/payment_link Partner token + user token
Notifications about changes Webhooks: appointment, client, team member, service, schedule, product operation, financial operation and loyalty card events Webhook settings per Location

The Online Booking API is the public set behind booking widgets and client portals, so it needs no user authentication. The Business Management API covers scheduling, clients, inventory, finances and loyalty. Both its V1 and V2 are in production, and V2 is the one recommended for new integrations.

Pro Tip: Cache services and team members and refresh the cache when a service, team member or schedule webhook arrives. Query time slots live every time – stale slot data is how double bookings happen.


How does a secure middleware architecture actually work?

The middleware is the engine of your integration. It sits between the platform’s API and every consumer (website widget, CRM, BI dashboard, AI model) and does the work those consumers should never do directly: it authenticates, queues and throttles requests, receives webhooks and logs every call.

Middleware responsibilities:

  • Credentials: keep the partner token and user token in a secrets manager, never in code or in a browser, and know how you will replace them if they leak.
  • Throttling: queue bursts on your side to stay under the rate limit; the documentation lists no rate-limit headers to wait for.
  • Webhook intake: return a 2xx status straight away and process the event from a queue.
  • Deduplication and ordering: the same event can arrive twice, and different events can arrive out of order.
  • Reconciliation: a scheduled job pulls appointments changed since the last run and repairs anything a webhook missed.
  • Audit logging: every inbound webhook and outbound call, with a timestamp and a correlation ID.
  • Client data handling: strip or pseudonymise client details before they reach AI models or analytics tools.
  • Orchestration: multi-step flows (check slot → validate → create → confirm) run as one tracked sequence, so a failure halfway leaves a clear state.

Cache what changes slowly, query live what changes by the minute and keep live calls for the operations that matter. That is the strategic case for this architecture: the platform stays the source of truth for appointments, and you can swap the tools around it without rebuilding the core.

Pro Tip: Give each consumer only what it needs. A CRM connector should read clients and appointments; it has no reason to touch finances or schedules. In Altegio, the user token belongs either to your installed application’s system user or to a business user you authorise, and their Location access and permissions can differ – choose deliberately.


Step-by-step technical checklist for your developer

Hand this list to your developer as a ticket. Each step is a separate deliverable.

  1. Discovery: read Getting Started on developer.alteg.io and pick the API set for each flow. The base URL is https://api.alteg.io/api, every request goes over TLS 1.2 or higher, and date-times use ISO 8601 with an offset.
  2. Credentials: take the partner token from your developer account and, for business data, add a user token (see how to get Altegio API keys and getting credentials on the portal). Send them as Authorization: Bearer <partner_token>, User <user_token> together with Accept: application/vnd.api.v2+json.
  3. Test environment: there is no separate sandbox. Install a draft application on your own test Location, activate it and make authenticated calls there before moderation and before any live data is involved.
  4. Webhooks: subscribe to the resource types you need in the webhook settings (help-centre guide to webhooks) and build the receiver to the rules in the next section.
  5. Duplicate protection on writes: the API documents no idempotency-key header. Put your own reference into the appointment’s api_id field (external appointment ID) and, after a timeout, check whether the appointment exists before you retry the create.
  6. Rate limits: throttle to stay under 200 requests a minute and 5 a second per IP address; on HTTP 429, back off before retrying.
  7. Errors and retries: retry 429 and 5xx with exponential back-off and a hard cap on attempts; alert a person on 401 and 403, which point to credentials or permissions; don’t retry other 4xx errors – fix the request.
  8. Reconciliation: run a scheduled job that lists appointments with changed_after set to the last successful run (the list method also takes with_deleted) and repairs any gaps.
  9. Audit logging: log method, endpoint, status code, latency, correlation ID and a pseudonymised client reference for every call.

Minimal HTTP examples:

# 1. Free time slots for one team member on one day
#    (Online Booking API, partner token only)
GET https://api.alteg.io/api/v1/book_times/{location_id}/{team_member_id}/2026-12-15?service_ids[]=331
Accept: application/vnd.api.v2+json
Content-Type: application/json
Authorization: Bearer <partner_token>

# 2. Validate with POST /v1/book_check/{location_id}, then create the appointment
POST https://api.alteg.io/api/v1/book_record/{location_id}
Accept: application/vnd.api.v2+json
Content-Type: application/json
Authorization: Bearer <partner_token>

{
  "phone": "+48500100200",
  "fullname": "Anna Kowalska",
  "email": "[email protected]",
  "api_id": "web-2026-000123",
  "appointments": [
    { "id": 1, "services": [331], "staff_id": 6544, "datetime": "2026-12-15T10:00:00+01:00" }
  ]
}

# 3. Business data needs both tokens (Business Management API)
GET https://api.alteg.io/api/v1/locations/{location_id}/appointments?changed_after=2026-12-15T00:00:00
Accept: application/vnd.api.v2+json
Content-Type: application/json
Authorization: Bearer <partner_token>, User <user_token>

The Online Booking API also has methods to change an appointment’s date and time and to send an SMS confirmation code when a Location asks clients to confirm their phone number. Field names follow the API, not the interface: a Location appears as company or location, a team member as staff and an appointment as record.


How should your middleware handle webhooks?

Webhooks are where integrations break quietly, so build the receiver to the documented behaviour from day one.

  • Envelope: each POST carries JSON with company_id (the Location), resource (for example record for an appointment or client), resource_id, status (create, update or delete) and data with the record itself. There is no separate “cancelled” event: read data to see what changed.
  • Timing: events are queued and sent about 5 seconds after the change. Each attempt times out after 10 seconds in total and 5 seconds for the connection, and only a 2xx response counts as delivered.
  • Retries: failures before the request reaches you, HTTP 429 and 5xx are retried up to twice, 5 and then 30 seconds after the previous attempt. A timeout after the request was sent and other 4xx answers are not retried, so a slow handler can lose an event – which is why you reconcile.
  • Duplicates: delivery is at-least-once. The X-Hook-Id header is a UUID that stays the same across retries; store it and skip anything you have already processed. A retry carries the current state of the resource, so its data can differ from the first attempt.
  • Order: notifications for different events are not guaranteed to arrive in order. Compare with the record you hold instead of assuming the latest webhook is the latest state.
  • Authenticity: requests carry the Authorization: Bearer token configured for webhooks. It is shared, not a secret unique to your URL, and the documentation describes no payload signature. Check the header, check that company_id is a Location you serve and, before writing anything, re-read the record through the API.
  • Debugging: there is no delivery log, test send or replay for partners, so keep your own log of every X-Hook-Id and test with real appointments on your test Location.

Webhook skeleton and handler:

POST https://your-middleware.example/altegio/webhooks
Content-Type: application/json
Authorization: Bearer <configured_token>
X-Hook-Id: 6f1d2c3a-8b4e-4f7a-9c21-5e0b7d9a1f42

{
  "company_id": 123456,
  "resource": "record",
  "resource_id": 501,
  "status": "update",
  "data": { "id": 501, "staff_id": 101, "datetime": "2026-12-15T10:00:00+01:00", "attendance": 0, "services": [ ... ], "client": { ... } }
}

# Handler (pseudocode)
if header["Authorization"] != configured_token: return 401
if seen(header["X-Hook-Id"]): return 200
enqueue(header["X-Hook-Id"], body); return 200      # well inside the 10-second timeout

# Worker: re-read the record through the API, apply the change, mark the X-Hook-Id as processed
# Nightly: list appointments with changed_after = last successful run and repair gaps

Pro Tip: To prove your deduplication works, make your test endpoint return a 500 on purpose. The retries arrive with the same X-Hook-Id, and your log should show one processed event, not three.


AI and automation patterns mapped to booking API endpoints

Design AI and automation around specific API surfaces, and don’t rebuild what the platform already does. Altegio sends automatic notifications (appointment notifications, confirmation requests, reminders, repeat-visit invitations and a feedback request after an Arrived visit) and runs loyalty programmes natively, so your middleware should add to those, not duplicate them.

Four practical automation sequences:

  1. Chat booking: client message → intent parser → book_times → offer options → client confirms → book_check → book_record. Altegio’s automatic notifications then take over, depending on how the Location has set them up.
  2. No-show risk: nightly job → appointments for the next two days → score each client on their history → a list of high-risk appointments for the front desk to call. Altegio sends one reminder per appointment, so the call is the extra step for risky ones.
  3. BI sync: appointment and financial operation webhooks → queue → data warehouse; the nightly changed_after job fills any gaps.
  4. CRM sync: client webhook → match by phone → update the CRM contact; marketing status lives in the CRM (see the GDPR section).

If what you need is an AI assistant that works inside your Altegio account rather than a custom bot, look at the Altegio MCP server first (help-centre guide): it connects an AI assistant to Altegio without middleware of your own.

Pro Tip: Start with read-only automations. Switch on each new recipe behind a feature flag and keep a human approval step for anything that changes or deletes an appointment until you trust the data.


Security, privacy and GDPR in Europe

The GDPR (Regulation 2016/679) applies to every client record your integration touches, in every EU and EEA country. Start with roles, because they decide who signs what.

Who is who:

  • The salon, spa or clinic decides why and how client data is processed, so it is the controller (Article 4(7)).
  • A developer, agency or hosting provider that runs the middleware on the business’s behalf is a processor (Article 4(8)). The controller may use only processors that give sufficient guarantees (Article 28(1)), and the processing must be governed by a contract – a data processing agreement – that sets out its subject-matter, duration, nature and purpose, the type of data and the categories of people concerned (Article 28(3)).
  • That agreement must, among other things, oblige the processor to act only on documented instructions, ensure the people handling the data are bound by confidentiality, apply the security measures of Article 32, help the controller answer data subject requests and delete or return the data when the work ends (Article 28(3)(a), (b), (c), (e) and (g)).
  • The processor may not bring in another processor – a cloud host, a logging service, an AI provider – without the controller’s prior written authorisation (Article 28(2)).

Security controls checklist:

  • Separate credentials per integration, kept in a secrets manager, with the least access that does the job.
  • Encrypted transport everywhere: the Altegio API already requires TLS 1.2 or higher, and your webhook endpoint should be HTTPS only.
  • Encryption at rest and pseudonymisation for any client data you cache – Article 32(1)(a) names both as examples of appropriate measures.
  • Role-based access on the middleware itself and no shared admin logins.
  • Audit logs with a retention period you have decided and written down.
  • Data minimisation: each downstream system gets only the fields it needs (Article 5(1)(c)).

GDPR specifics for booking data:

  • Lawful basis: the data needed to book and deliver an appointment can usually rely on the performance of a contract (Article 6(1)(b)). For email and SMS marketing, plan on consent (Article 6(1)(a)): national rules implementing the ePrivacy Directive 2002/58/EC also apply, and they differ between EU countries.
  • Health data: clinics and aesthetic practices often hold data concerning health, a special category under Article 9 that may be processed only under one of its exceptions, such as explicit consent. Keep visit notes and medical fields out of tools that don’t need them.
  • Consent records: Altegio’s booking form has a mandatory personal-data consent checkbox but no marketing-consent checkbox and no consent timestamp, and opt-outs are set by hand in the client card (Exclude). If you run marketing, capture and store consent in the marketing tool and make sure opt-outs reach every system that sends messages.
  • Data subject rights: the controller must be able to answer access, rectification and erasure requests (Chapter III) across every connected system. In Altegio, deleting a client card doesn’t delete that client’s appointments and payments, so plan erasure system by system rather than trusting one delete.
  • Records of processing: each controller keeps a record of processing activities (Article 30). Add every data flow the integration creates, including each processor.
  • Hosting: check where the middleware and every connected tool store data. If anything leaves the EEA, review the transfer rules with your data protection adviser.

Pro Tip: Never store raw client details next to model outputs. Pass the platform’s client ID or a pseudonymised reference to your AI model; the middleware resolves it back to a name only when a person needs to act.


How should you test and roll out the integration safely?

A phased rollout catches integration bugs before they reach real clients.

Five-phase rollout:

  1. Test Location: a draft application on your own test Location; the three core flows pass, webhook deduplication is proven with forced retries, and a reconciliation run finds no gaps.
  2. Read-only: connect the read methods to your CRM and BI; no writes to live data yet.
  3. Assisted: team members create appointments through the new interface while the middleware logs every call.
  4. Conditional automation: automated flows run, but changes and deletions still need human approval.
  5. Full rollout: all recipes active; feature flags stay in place for instant rollback.

KPIs to monitor from day one:

  • Appointment creation success rate (2xx responses / attempts).
  • Webhook health: duplicates skipped and gaps found by reconciliation.
  • API error rate by endpoint and status code, including 429s.
  • End-to-end latency from the client’s request to the appointment being created.
  • Business results: no-show rate and revenue per appointment.

Pro Tip: Assign a correlation ID where every request enters the middleware and carry it through every log line. When something breaks at night, it is the fastest way from symptom to cause.


What does a booking API integration actually cost and how long does it take?

There is no honest single number. Effort depends on how many systems you connect, whether the integration only reads or also writes, how many Locations it covers and how strict your data protection requirements are. A read-only BI feed for one Location is a much smaller job than a two-way CRM sync for a chain.

The cheapest integration is the one you don’t build. Check the Integrations Hub first: ready-made apps connect from the Integrations menu without custom code. If you only need to pass events to another tool, Altegio webhooks with Webhooks by Zapier (a paid Zapier plan) may be enough – there is no native Altegio app on Zapier.

For custom work, budget for the parts that take time on any platform: data mapping, webhook handling, reconciliation, testing on a test Location and the data processing agreement. Altegio’s API team offers architecture feedback before you ship; the contact details are on the developer portal.


How do payments, checkout and inventory fit in?

Online payments in Altegio run through a connected provider – Stripe, or Adyen in EU countries – and Altegio charges no commission of its own on them. Through the API you can get a payment link for an appointment and send it to the client, and payment policies such as deposits are set up in Altegio itself rather than in middleware.

If you run an external till or online shop, listen to financial operation and product operation webhooks and reconcile them by appointment. Consumables don’t need middleware: inventory control in Altegio writes them off automatically through bills of materials linked to services, and the Sales by Services report shows consumables cost, payroll and profit per service. There are no low-stock alerts or automatic reordering, so if you want them, build them in middleware from product operation events and your own reorder thresholds.


How do you handle time zones and localisation in appointment scheduling?

Store every date-time in UTC in the middleware and convert to local time only at the presentation layer, using the IANA time zone of each Location (for example Europe/Lisbon, Europe/Warsaw, Europe/Helsinki). The Altegio API exchanges date-times in ISO 8601 with an offset, such as 2026-09-21T23:00:00.000-05:00, and durations in seconds (900 = 15 minutes), so pass the offset through rather than stripping it.

Most of the EU uses three standard time zones, from UTC+0 in mainland Portugal and Ireland to UTC+2 in Finland and Romania, and all of them switch to summer time. A client booking a Warsaw appointment from Lisbon must see the right time in both places: accept local time in the interface, keep the offset in the request, store UTC and render in the Location’s time zone on confirmation.

Localisation goes beyond time zones. Date formats differ (DD.MM.YYYY in Germany, Poland and Czechia; DD/MM/YYYY in France, Spain and Italy), and so do currencies (EUR, PLN, CZK, HUF, RON, SEK and others) and the language of automated messages. Resolve all of them from the Location record and never hard-code them in the middleware.


How should you version and maintain backward compatibility?

Altegio versions its API in the URL path (/v1/, /v2/). Both versions are in production: new features may appear in V2 only, and V1 is maintained for backward compatibility. V2 is recommended for new integrations; the examples above use V1 methods that remain supported. At the time of writing, a V3 contract is published as a preview only and can’t serve calls yet.

Watch the developer portal for changes and run your full test suite on your test Location before moving live traffic to a new version or method. If your middleware exposes its own API to other tools, version it the same way and announce deprecations well in advance.

Never rely on undocumented fields. Treat anything not in the official schema as volatile and parse defensively: if a field is missing, use a safe default instead of throwing an exception.


What happens to your integration under high booking volumes?

At high volume the hard limit is the rate limit: 200 requests a minute or 5 a second per IP address. A chain that polls every Location every few minutes reaches it quickly, so the design must lean on webhooks and caching rather than polling.

Put a message queue between webhook intake and processing. Intake answers well inside the 10-second timeout, the queue absorbs spikes and the processing workers scale horizontally.


How do you map your data model to the booking API?

Data mapping is where integrations lose the most time, so do it in discovery, not during the build.

Core entity mappings:

  • Location: company_id / location_id in the API ↔ the site or branch ID in your other systems. Every Location belongs to a Chain, even in a single-location business.
  • Client: platform client ID ↔ CRM contact ID; map name, phone, email and preferred language. Online appointments require a phone number, which makes phone the most reliable matching key.
  • Appointment: record ID, services, team member (staff_id), datetime, attendance status and the api_id you set; this feeds no-show scoring and BI. Altegio uses four appointment statuses: Pending, Confirmed, Arrived and No-show.
  • Services: durations come in seconds; map each service to the product codes your till or shop uses if you sync sales.
  • Availability: always ask the API for free time slots (book_times) instead of computing them from working hours, because existing appointments, technical breaks and resources all affect the answer.

Decide the sync frequency per data type during discovery: appointment status in real time through webhooks, client profile changes through client webhooks, and visit history for analytics in a nightly changed_after job.


How do you connect your booking system to a CRM or marketing platform?

A CRM sync is a two-way flow. New clients created through online booking reach your CRM through client webhooks, and CRM updates flow back through the client methods of the Business Management API, matched by phone. The Altegio client base stays the record your front desk works from.

Triggers map naturally. An appointment create event can start a welcome flow in the CRM for a first-time client; an appointment marked Arrived can update the client’s lifetime value; a no-show can open a follow-up task for the front desk. Altegio already sends its automatic notifications, so don’t duplicate confirmations, reminders or feedback requests from the CRM.

Altegio has no bulk email, so newsletters belong in an email marketing platform. Build segments there – for example “booked three times in 90 days” or “cancelled twice” – from the appointment data the middleware feeds in, and keep consent and opt-outs in that platform too, because Altegio’s booking form doesn’t collect marketing consent.


Altegio gives you the API and the integrations to build on

Altegio is appointment scheduling software for appointment-based businesses: beauty, wellness, clinics, auto services, fitness and more. For integrations it gives you:

  • Ready-made apps in the Integrations Hub, connected from the Integrations menu.
  • The Open API – Online Booking and Business Management sets – documented on developer.alteg.io.
  • Webhooks for appointments, clients, team members, services, schedules, products, finances and loyalty cards.
  • An MCP server for connecting an AI assistant to your account.
  • Built-in modules your middleware can lean on instead of rebuilding them: online booking, client base, automatic notifications, inventory and analytics.

Pricing depends on the number of team members and the billing period (see pricing). Start a 7-day free trial and have your developer read the documentation in parallel.


FAQ

What are the three core flows in a booking API integration?

Read free time slots, create the appointment and handle webhooks for appointments that are created, updated or deleted. In the Altegio Online Booking API, the first two are book_times and book_record, with book_check to validate the parameters in between.

How do you prevent duplicate appointments when retrying API calls?

The Altegio API documents no idempotency-key header, so protect yourself in the middleware: store your own reference in api_id and, after a timeout, check whether the appointment was created before retrying. On the incoming side, deduplicate webhooks by X-Hook-Id, which stays the same across retries.

Does Altegio sign its webhooks?

The documentation describes an Authorization: Bearer token configured for webhooks, shared rather than unique to your URL, and no payload signature. Check the header and the company_id, and re-read the record through the API before writing anything based on a webhook.

What GDPR requirements apply to booking API integrations in Europe?

Clear roles (the business as controller, the integrator as processor) with an Article 28 data processing agreement, a lawful basis for each purpose, data minimisation, support for data subject requests across every system, a record of processing activities and appropriate security such as encryption. Clinics need extra care with health data, a special category under Article 9.

Can Altegio be used as the platform for this middleware architecture?

Yes. Altegio has public Online Booking endpoints, a Business Management API for appointments, clients, services, team members, finances and more, and webhooks on changes. Requests use a partner token, plus a user token for business data. There is no separate sandbox: install a draft application on your own test Location and develop there.

Does Altegio work with Zapier?

There is no native Altegio app on Zapier. You can connect the two through Altegio webhooks and Webhooks by Zapier, which needs a paid Zapier plan, or go through the Open API.


This article is general information, not legal or tax advice; rules differ between EU countries.

author avatar
Giorgio Altegi