Smileline
Online booking

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-key value. 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.io when it starts widget-eu, https://api-us.smileline.io when it starts widget-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

StepCallWhat it does
1GET /booking/{key}/configWhat the practice offers online
2GET /booking/{key}/availabilityFree times for one appointment type at one location
3POST /booking/{key}/holdReserves the chosen time and records the patient
4POST /booking/{key}/completeTurns 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.practice

Show 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 }] }]
  • from and to are 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 practitionerId for one clinician's times. Leave it out for anyone: each slot then names the clinician it is with.
  • Show times in the timezone the answer names, not the visitor's.
  • At a location that books into a practice system with more than 10 linked practitioners, a request without practitionerId answers 400 with PRACTITIONER_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 startsAt and practitionerId exactly as the slot gave them.
  • eventId is a fresh UUID for each booking attempt. It makes a retry safe: the same request with the same eventId answers the same hold.
  • The answer's uid is what you complete. holdExpiresAt is 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());
statusWhat to show the patient
bookedThe appointment is booked.
pendingThe 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, addressLine1 and postalCode are each hidden (don't ask), optional or required, and are sent in patient. The two contacts are never both hidden; when one is, require the other.
  • note and marketingConsent are hidden or optional: the patient's own message, sent as note, and a tick box for news and offers, sent as patient.marketingConsent (true or false).
  • questions are the practice's own, in the order to show them. kind is text (one line), textarea (several lines) or checkbox (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:

FieldSend in patient as
titletitle — one of that location's titles
sexsex — male or female
dateOfBirthdateOfBirth — YYYY-MM-DD
addressLine1addressLine1
postalCodepostalCode

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 key stays 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:

designThe hosted page and the embed show
absentThe 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=onePage
  • design=onePage shows the one-page design, design=standard the standard one and design=custom the 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.

AnswerFromWhat to do
409 SLOT_TAKENhold, completeSomeone else took the time. Load the free times again and offer others.
409 IDEMPOTENCY_KEY_REUSEDholdThe eventId was already used for different details. Use a new one.
410 HOLD_EXPIREDcompleteThe hold ran out. Start again from the free times.
503 PMS_AVAILABILITY_RETRYavailabilityThe practice's system could not be read in full. Try again shortly; never show a partial list.
503 BOOKING_RETRYholdA momentary fault. Send the same request again with the same eventId.
429anyToo many requests. Wait the number of seconds in the Retry-After header.
404anyThe 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:

CallSteady rateBurst
Config4 a second120
Availability2 a second120
Hold1 a second60
Complete1 a second60

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.

On this page