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, nextFrom } = await fetch(
`${API}/booking/${KEY}/availability?${query}`,
).then((r) => r.json());
// days: [{ date: "2026-12-01", slots: [{ startsAt, practitionerId }] }]
// nextFrom: "2027-01-12", null, or absent (see below)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.- An answer may carry
nextFrom, from Smileline's copy of the practice's diary. A date: start the next window there, the days between have no times.null: no later day up to the end of the 54 weeks has any, so stop. Absent: start the next window the day afterto. - 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. - When the practice confirms the mobile with a code, send the code before the hold, and the hold with its proof: see Confirm the mobile with a code.
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).phoneCheck, when present ("sms"), means the patient confirms their mobile with a code before booking, andphoneMobileis thenrequired: see Confirm the mobile with a code.
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.
Confirm the mobile with a code
When config.config.fields.phoneCheck is "sms", the practice texts the patient a 6-digit code before the booking. Once the patient has typed their details, and before the hold, send the code and check it. Use the hold's own eventId for both.
1. Get a security check token. Frame Smileline's check page in your form, with config.phoneCheckSiteKey as key and your page's own origin as origin (use widget-us for a widget-us snippet). It posts a token to your page:
<iframe
title="Security check"
src="https://widget-eu.smileline.io/turnstile/#origin=https%3A%2F%2Fwww.example.com&key=SITE_KEY&action=booking_code"
></iframe>let turnstileToken = "";
window.addEventListener("message", (event) => {
if (event.origin !== "https://widget-eu.smileline.io") return;
if (event.data?.type === "sl-turnstile") turnstileToken = event.data.token ?? "";
});A token works once: reload the frame for each new send.
2. Send the code.
const sendId = crypto.randomUUID(); // one per press of Send or Resend
const sent = await fetch(`${API}/booking/${KEY}/phone-code`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
eventId, // the hold's own
sendId,
phone: "07700 900123",
locationId: location.id,
turnstileToken,
client: "web",
}),
}).then((r) => r.json());If the request gets no answer, a server error (5xx), a 429 or an answer you can't read, send it again with the same sendId: the patient never gets a second text for one press. Make a new sendId only after a clear answer.
status | What to do |
|---|---|
sent | Ask for the code. Keep challenge. Offer to send a new code after resendAfter seconds. |
skipped | No code could be sent, for a reason on Smileline's side, or the practice stopped asking for one. Keep proof and go on to the hold: where the page still asks, the booking is marked as not confirmed. |
invalid_number | Ask the patient to correct the mobile. |
too_many | Too many codes went to this number. Ask the patient to try again in retryAfter seconds. |
3. Check the code.
const checked = await fetch(`${API}/booking/${KEY}/phone-code/check`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ challenge: sent.challenge, code: "123456" }),
}).then((r) => r.json());status | What to do |
|---|---|
confirmed | Keep proof and go on to the hold. |
wrong | The code is wrong; triesLeft says how many tries remain. |
expired | 15 minutes have passed or the tries ran out. Send a new code. |
skipped | The code couldn't be checked, for a reason on Smileline's side. Keep proof and go on to the hold: the booking is marked as not confirmed. |
Sent without code (a "Didn't get it?" link), the check says what became of the text: sent (still on its way: offer a new code), undeliverable (the number can't take a text: ask for another) or skipped with a proof (go on to the hold).
4. Hold with the proof. Send it in the hold's Authorization header, never in its body:
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${proof}`,
},The proof holds for 30 minutes, and only for that eventId, mobile and location. Keep it in memory, and send a new code if the patient changes their mobile or location.
Until you have a proof, send Authorization: Bearer none. Without a valid proof, the hold answers 409 with PHONE_CODE_REQUIRED: send a new code with the same eventId, then hold again. Its details say what the page asks now (phoneCheck), in case the practice turned the code on after your page loaded. A hold sent with no Authorization header at all is treated as a page that can't show the code step, and is passed to the practice to follow up.
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. |
409 PHONE_CODE_REQUIRED | hold | The practice confirms the mobile and the proof is missing, expired or for other details. Send a new code with the same eventId. details.phoneCheck says how the page confirms it now. |
403 TURNSTILE_FAILED | phone-code | The security check failed. Reload the check frame for a new token and send again. |
503 PHONE_CODE_UNAVAILABLE | phone-code | Codes can't be sent right now. Try again shortly. |
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.