How to build a custom booking page with a scheduling API
On this page
What do you need before building a scheduling API page?
You need an active event, its host's connected Google calendars and an application that can display and submit appointments. Configure the event first. A custom interface still uses the host's duration, questions and availability rules, so the API doesn't remove the need to make those settings correct.
Start with the API feature overview, then open the developer reference and current OpenAPI contract. Use the contract for request fields and error shapes instead of copying an old payload into production.
If you only need the booking page inside your website, an embed can avoid building the calendar and form yourself. A custom page makes sense when you need to own those interactions and can maintain their accessibility, time handling and failure states.
Which API key belongs in the browser?
A publishable key is for browser reads and booking creation from its allowed origins; a secret key belongs only on the server. Choose the architecture first. The two key types have different authorisation rules, so moving a secret-key request into browser code won't make it an allowed public integration.
| Integration | Key and constraints |
|---|---|
| Browser talks directly to the API | Publishable key; exact allowed origin; Turnstile for booking creation |
| Your server talks to the API | Secret key from environment; no Origin header |
| Guest manages one booking | Management token for that booking |
We reject a secret-key request carrying an Origin header, and publishable requests need an allowed Origin. Keep host booking-list operations on the server: they require a secret key, and the public page shouldn't expose all appointments.
A server proxy needs its own public abuse controls and input validation. Hiding an API key doesn't make an unrestricted internet endpoint safe to use for arbitrary booking writes.
How do you read events and available appointments?
Read /event-types, select an event slug, then request /event-types/{slug}/slots with start and end instants. Show the returned times in a named zone. We return ISO timestamps for start/end, preferred flags and suggested slots; the page shouldn't invent extra appointments between those results.
Request slots from your server
For a server-based integration, this example requests one UTC day. Set SCHEDULING_ORIGIN to the application's origin, SCHEDULING_SECRET_KEY to your private key and EVENT_SLUG to a configured event; the dates are illustrative inputs.
const origin = process.env.SCHEDULING_ORIGIN;
const key = process.env.SCHEDULING_SECRET_KEY;
const slug = process.env.EVENT_SLUG;
if (!origin || !key || !slug) throw new Error('Missing API configuration');
const url = new URL(
'/api/v1/event-types/' + encodeURIComponent(slug) + '/slots', origin,
);
url.search = new URLSearchParams({
start: '2026-11-23T00:00:00Z',
end: '2026-11-24T00:00:00Z',
timeZone: 'Europe/London',
duration: '30',
}).toString();
const response = await fetch(url, {
headers: { Authorization: 'Bearer ' + key },
});
if (!response.ok) throw new Error('Read slots failed: ' + response.status);
const result = await response.json();Read the allowed durations first. Use one from the event details instead of assuming every event allows 30 minutes. This example doesn't claim a returned slot exists on that date; an empty list is a valid result when hours, conflicts or other rules leave no appointments. Read what a custom scheduling integration controls before building an interface that treats a returned slot as an already-held appointment.
We reject a slot range longer than 31 days. Fetch another bounded range when the visitor changes month, and use Luxon for display-zone conversion instead of adding a fixed offset to wall-clock times.
How does a booking API tutorial create the appointment?
Post to /bookings with the event slug, the returned slot's start, an allowed duration and the guest details required by the contract. Include the configured answers. Submitting fewer fields than the event requires won't become valid merely because the public form has been replaced with your own interface.
The essential payload has this shape; bracketed strings are placeholders to replace, not a request to send literally:
{
"eventType": "[event slug]",
"start": "[returned ISO start timestamp]",
"duration": 30,
"guest": {
"name": "[guest name]",
"email": "[guest email]",
"timeZone": "[IANA time zone]"
},
"answers": {}
}For a publishable-key booking, include the required turnstileToken. A secret-key request uses the server architecture described above; never return its credential to the guest along with a successful booking response.
Use a unique Idempotency-Key for each booking submission and reuse it when retrying that same submission. We accept up to 200 characters for the header and return the original successful booking on replay, so a network timeout needn't lead to a second appointment attempt with a new identity.
What should happen when the selected slot becomes busy?
Refresh availability and ask the guest to select another appointment when the API rejects a stale time. Don't show success prematurely. We recheck selected calendars when creating the booking, which means an appointment returned a minute earlier can legitimately be unavailable when its submission arrives.
A hypothetical page might show four choices at 10:00. If another guest books one before the first visitor confirms, three could remain on the next availability request, assuming no other changes.
Handle the API's error.code, including slot_unavailable, and read Retry-After for a 429 response. Preserve the guest's entered answers while refreshing times so a conflict doesn't force them to retype the whole form.
An accepted booking can also be pending when approval is required. Render the returned status and management options instead of treating every successful HTTP response as a confirmed meeting with conference details ready.
How do you check your custom booking interface?
Complete one appointment through your own interface and inspect the host record, email and calendar entry. Then test failure states. A page that only handles the happy path will give misleading results when there are no times, a field is invalid or approval is still required.
| Test | Expected interface behavior |
|---|---|
| Empty slot response | Explain that no appointments are available |
| Validation rejection | Keep entries and identify the correction |
| Slot taken before submission | Refresh choices without claiming success |
| Retried successful submission | Show the original appointment |
| Pending booking | Explain the approval step |
Our webhook CRM connection guide covers outgoing lifecycle events after submission. To compare documented API options elsewhere, use scheduling apps with a free API.
The API uses rate and fair-use limits, and its host calendars remain Google calendars. Check the current included developer features, then create the event behind your custom page before wiring its public interface.
Steps
Configure an event and Google calendars
Create the appointment type and confirm its durations, required questions and availability. Keep those rules aligned with the custom interface.
Choose a key and request architecture
Use a secret key only on your server, or a publishable key from an allowed browser origin. The public-key booking path requires Turnstile.
Read event details and bounded slots
Load the event and request a start/end range of at most 31 days. Render returned instants in the guest's named time zone.
Submit the selected appointment
Post the selected start, duration, guest details and answers to the bookings endpoint. Reuse one idempotency value for retries of that submission.
Handle status and booking errors
Display pending approval distinctly from confirmation. Refresh stale slots and respect rate-limit response headers.
Verify the guest and host result
Make a trial booking through the custom page and inspect the calendar and messages. Test empty availability, validation failures and a repeated submission too.
Frequently asked questions
Does the API let me ignore the host event settings?
No. The configured event still supplies its allowed durations, questions, calendar rules and approval behavior. Read those settings into your interface, then send an appointment that satisfies them instead of assuming a custom form overrides the booking engine. Read the event's actual returned availability and handle rejections, instead of offering your own start that bypasses the hours, notice or conflicts the host configured.
Should each network retry use a new idempotency header?
No. Reuse the original header for retries of the same submission so a successful replay returns the original booking. Generate a new value for a genuinely new booking attempt instead of confusing a repeated request with a separate appointment. Reuse the key for the same intended operation after an uncertain response, so retries don't turn one guest decision into multiple independent booking attempts.
Can I keep using an old list of slots all afternoon?
You can display a previously loaded choice, but its availability can change before submission. Handle a stale-time rejection and refresh choices; the live check protects the host's calendar even when a custom page has retained older results. Refresh availability and inspect the booking response before displaying success, because another commitment can occupy a previously returned start while the page remains open.
Related pages
- Booking API and webhooks for your own application
Build with REST, OpenAPI and signed webhooks. Browser keys require allowed origins; server keys stay private. Default API access is 600 requests/minute.
- Scheduling apps with a free API and webhooks
Compare scheduling APIs and free webhooks without treating them as the same feature. Includes TidyCal, Cal.com and a Google Calendar booking API.
- How to send new bookings to your CRM with webhooks
Send signed booking events to a CRM or spreadsheet through your receiver. Verify signatures, deduplicate event IDs and handle approvals and retries.
- What is a scheduling API?
A scheduling API lets software read available times and manage bookings. See a 30-minute example, key permissions and the difference from webhooks.
Create your free booking link
Sign in with Google, create an event and share your link.
Create your free link