Build your own booking page
For a practice's web developer — take bookings on a page you design, with the practice's booking-page key and four public calls.
By the end of this page your own page will show free times from the practice's diary and book one, exactly as the hosted page and the embed do. If Smileline's own booking page is enough, paste the embed snippet instead: it needs no code.
What you need
Open Settings → Online booking and copy the Embed snippet:
<script async src="https://widget-eu.smileline.io/booking.js" data-key="YOUR_KEY"></script>- The booking-page key is the
data-keyvalue. It is public: it names the practice and does only what the booking page does. - The API address for your region follows the snippet's address:
https://api-eu.smileline.iowhen it startswidget-eu,https://api-us.smileline.iowhen it startswidget-us. Never call the other region.
Never put a Smileline API key in a website. These calls take the booking-page key in the address and nothing else: no login, no API key, no cookies. They answer any website.
The key works only while Online booking is switched on. While it is paused, every call answers 404.
Check the key from a terminal first:
curl "https://api-eu.smileline.io/booking/YOUR_KEY/config"The four calls, in order
| Step | Call | What it does |
|---|---|---|
| 1 | GET /booking/{key}/config | What the practice offers online |
| 2 | GET /booking/{key}/availability | Free times for one appointment type at one location |
| 3 | POST /booking/{key}/hold | Reserves the chosen time and records the patient |
| 4 | POST /booking/{key}/complete | Turns the hold into a booking |
Every example below starts from these two lines:
const API = "https://api-eu.smileline.io"; // api-us for a widget-us snippet
const KEY = "YOUR_KEY";1. Read what the practice offers
const config = await fetch(`${API}/booking/${KEY}/config`).then((r) => r.json());
// config.locations, config.appointmentTypes, config.practitioners, config.practiceShow only what config lists: the locations, the appointment types marked bookable online (each with its durationMin, depositAmountCents, requiresConfirmation, description and audience — any, new or existing) and the practitioners. config.config.fields, when present, is what the practice wants its form to ask: see What to ask the patient. config.config.design, when present, is the design the practice chose for Smileline's own page: see The design the practice chose. A change made in Settings can take up to a minute to appear.
2. Load the free times
const query = new URLSearchParams({
appointmentTypeId: type.id,
locationId: location.id,
from: "2026-12-01",
to: "2026-12-14",
});
const { timezone, days } = await fetch(
`${API}/booking/${KEY}/availability?${query}`,
).then((r) => r.json());
// days: [{ date: "2026-12-01", slots: [{ startsAt, practitionerId }] }]fromandtoare calendar days at the practice, both included. Ask for at most 14 days per request, within the next 54 weeks (a little over a year). To show the next free days however far ahead, ask window after window until enough days have times.- Add
practitionerIdfor one clinician's times. Leave it out for anyone: each slot then names the clinician it is with. - Show times in the
timezonethe answer names, not the visitor's. - At a location that books into a practice system with more than 10 linked practitioners, a request without
practitionerIdanswers400withPRACTITIONER_REQUIRED: ask the patient to choose a clinician first.
3. Hold the time
Call this once the patient has typed their details and confirmed. A hold records the patient and their enquiry at the practice even if they never finish.
const eventId = crypto.randomUUID(); // keep it, and send it again on a retry
const res = await fetch(`${API}/booking/${KEY}/hold`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
eventId,
appointmentTypeId: type.id,
locationId: location.id,
practitionerId: slot.practitionerId,
startsAt: slot.startsAt,
patient: {
firstName: "Amelia",
lastName: "Example",
phoneMobile: "07700 900123",
},
}),
});
const hold = await res.json();
// { uid, holdExpiresAt, startsAt, endsAt, timezone, requiresConfirmation, deposit }- Send
startsAtandpractitionerIdexactly as the slot gave them. eventIdis a fresh UUID for each booking attempt. It makes a retry safe: the same request with the sameeventIdanswers the same hold.- The answer's
uidis what you complete.holdExpiresAtis when the hold lapses. - If the answer is
{ "status": "request_received" }instead, the practice could not reserve the time online but has the request. There is nothing to complete: tell the patient the practice will be in touch. - When the practice asks questions of its own, add
answers: see Send the answers.
4. Complete the booking
const { status } = await fetch(`${API}/booking/${KEY}/complete`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ uid: hold.uid }),
}).then((r) => r.json());status | What to show the patient |
|---|---|
booked | The appointment is booked. |
pending | The request is with the practice, which reviews and confirms it. |
received | "We've got your request." The practice's own system has not taken the booking yet, and the practice confirms it. Never show "You're booked". |
What to ask the patient
A first name, a last name and either a mobile number or an email address are enough.
The practice chooses what its form asks under Settings → Online booking → Patient details. Those choices are in config.config.fields. It is absent until the practice saves them for the first time; until then, ask for the name and a contact, as above.
{
"phoneMobile": "required",
"email": "hidden",
"dateOfBirth": "optional",
"sex": "hidden",
"addressLine1": "hidden",
"postalCode": "hidden",
"note": "optional",
"marketingConsent": "hidden",
"questions": [
{
"key": "insurance_provider_3f9a",
"label": "Insurance provider",
"kind": "text",
"required": false
}
]
}phoneMobile,email,dateOfBirth,sex,addressLine1andpostalCodeare eachhidden(don't ask),optionalorrequired, and are sent inpatient. The two contacts are never bothhidden; when one is, require the other.noteandmarketingConsentarehiddenoroptional: the patient's own message, sent asnote, and a tick box for news and offers, sent aspatient.marketingConsent(trueorfalse).questionsare the practice's own, in the order to show them.kindistext(one line),textarea(several lines) orcheckbox(a tick box).
required is for your form to enforce: the API never refuses a booking because an answer is missing.
Whatever fields says, a location that books into a practice system may need more to open a new patient's record. Read newPatientFields on the chosen location in config and ask for each one it lists:
| Field | Send in patient as |
|---|---|
title | title — one of that location's titles |
sex | sex — male or female |
dateOfBirth | dateOfBirth — YYYY-MM-DD |
addressLine1 | addressLine1 |
postalCode | postalCode |
A booking sent without one of them is still taken, but it waits for the practice to fill the gap. You can also send note, the patient's own message, up to 1,000 characters.
Send the answers
Send the answers to the practice's own questions in the hold request as answers: an object with one entry per answered question, named by the question's key.
body: JSON.stringify({
eventId,
// …the rest of the hold request
answers: {
insurance_provider_3f9a: "Bupa",
i_have_dental_insurance_7c21: "Yes",
},
}),- A ticked box is
"Yes". Leave an unticked box, and any question the patient skipped, out. - An answer is at most 1,000 characters, and one request carries at most 30 answers.
- A question's
keystays the same when the practice rewords it. An answer whose question the practice has removed since is still kept.
The practice finds the answers and the patient's message on the appointment note and on the patient's timeline, and the answers on the lead.
The design the practice chose
The practice chooses how Smileline's own page looks, on its hosted link and in the embed, under Settings → Online booking → Design. That choice is in config.config.design:
design | The hosted page and the embed show |
|---|---|
| absent | The standard design: one step at a time |
"onePage" | The one-page design: the visit, the times, the details and one button on one card |
"custom" | The practice's own published design, around the one-page form |
It describes Smileline's page, not yours. The four calls work the same whichever is saved: follow it on your page or ignore it.
Whenever the practice has published a design of its own, whichever design is saved, the config reply also carries it in a top-level design object: its theme, its areas and its css. It is there for Smileline's own page; your page may ignore it.
To see a design without saving it, add design to the address of the Hosted booking page:
https://widget-eu.smileline.io/book/?key=YOUR_KEY&design=onePagedesign=onePageshows the one-page design,design=standardthe standard one anddesign=customthe practice's own published design, whichever is saved. Any other value is ignored, and the page shows the saved design.- It changes only the page opened with that address: nothing is saved.
- The embed snippet does not take it: the embed always shows the saved design.
How long a time is held
A hold lasts 30 minutes, or 60 minutes when the appointment type takes a deposit. Nobody else can book the time meanwhile. Completing after holdExpiresAt answers 410 with HOLD_EXPIRED: load the free times again.
Appointment types with a deposit
When the type has a depositAmountCents, the hold's deposit carries a checkoutUrl. Send the patient there to pay. Payment completes the booking, so do not call complete: until the deposit is paid it answers 402 with DEPOSIT_UNPAID. After paying, the patient returns to the practice's hosted Smileline booking page, which shows whether the booking is confirmed.
When config.depositCheckoutAvailable is false, do not offer types with a deposit: their hold is refused, and no free booking is made in its place.
Errors and limits
An error answers JSON with a message in error and, for the cases below, a code.
| Answer | From | What to do |
|---|---|---|
409 SLOT_TAKEN | hold, complete | Someone else took the time. Load the free times again and offer others. |
409 IDEMPOTENCY_KEY_REUSED | hold | The eventId was already used for different details. Use a new one. |
410 HOLD_EXPIRED | complete | The hold ran out. Start again from the free times. |
503 PMS_AVAILABILITY_RETRY | availability | The practice's system could not be read in full. Try again shortly; never show a partial list. |
503 BOOKING_RETRY | hold | A momentary fault. Send the same request again with the same eventId. |
429 | any | Too many requests. Wait the number of seconds in the Retry-After header. |
404 | any | The key is unknown, online booking is paused, or the link was regenerated. |
The limits are per practice and shared with its hosted page and embed:
| Call | Steady rate | Burst |
|---|---|---|
| Config | 4 a second | 120 |
| Availability | 2 a second | 120 |
| Hold | 1 a second | 60 |
| Complete | 1 a second | 60 |
Each visitor's address is also limited to 300 requests a minute. See Rate limits.
If the key changes
Regenerate link under Settings → Online booking replaces the key at once. The old key answers 404, so your page stops taking bookings until you put the new key in it.
Get found and booked
Put a Book button on your Google Business Profile, let AI assistants find your practice, and send patients links that open the booking page on the right location, visit and time.
Set up the referral programme
Configure rewards for both sides, the qualification rules and the terms that make the offer compliant, then switch the programme on.