Paste one tag and patients book a phone consult without leaving your site, in your colours and your fonts. Want to build every pixel yourself? The same booking runs on a small public API.
Replace the slug with yours from Booking page in your portal. A slug is the last part of your booking link, after /book/.
For clinics: do you need an API key?
For the usual setup, you do not need an API key. Patients pay at checkout and use Consulta's questionnaire. The embed or booking link is enough.
You only need a key for custom API calls if your clinic pays for website bookings instead of the patient, or your server submits Consulta questionnaire answers. An API key is a secret that gives your website permission to make those calls.
Create the key in your clinic portal. It is shown once. Keep it server-side, meaning on the website's server. Never email it or paste it into an AI chat or browser code. If your developer has their own secure link for receiving keys, use it.
You have been asked to add Consulta booking to a clinic's website. Read this section, then the reference below for detail. A plain-text version is at /llms.txt and the machine-readable API spec at /api/v1/openapi.json. Replace your-page-slug in every snippet and change nothing else.
Ask the clinic first
The clinic's booking page slug: the last part of its booking link, https://consultahealth.com.au/book/<slug>, shown under Settings, How patients book in the clinic's Consulta portal.
Whether the patient or the clinic pays. GET /api/v1/pages/<slug> answers with mode patient_paid or clinic_paid.
For the embed, the website address saved on the booking page (website_url in the same answer). The embed only loads on that host or its www form.
Only for API calls that need a key: ask the clinic to create it under Settings, How patients book, For developers, API keys, and add it to the website server's secret settings. Never ask them to paste it into an AI chat or email.
Path 1: the booking link, works on any site
Use this on any page, or wherever the embed cannot load.
A plain link, style it like the site's own buttons
<a href="https://consultahealth.com.au/book/your-page-slug">Book a consult</a>
Path 2: the embed, the full booking page inside the site
Paste exactly this where booking should appear, on a page of the clinic's saved website. It needs no key and works whoever pays. The patient picks a topic and time, answers our questionnaire and signs consent (when the clinic uses them) and pays, all inside the frame. Payment opens in the full window and comes back.
Read the page and its times, then book. No key is needed on a page where the patient pays. A page the clinic pays for, and sending questionnaire answers, need the clinic's key, from a server only, as Authorization: Bearer cx_live_....
Page, times, book, then pay or confirm
// Plain fetch, no library. Replace your-page-slug with the clinic's slug.
const api = "https://consultahealth.com.au/api/v1"
const slug = "your-page-slug"
// 1. The page (topics, mode, questions) and the next 7 days of times
const { page } = await (await fetch(api + "/pages/" + slug)).json()
const tz = Intl.DateTimeFormat().resolvedOptions().timeZone
const { days } = await (await fetch(api + "/pages/" + slug + "/availability?days=7&tz=" + encodeURIComponent(tz))).json()
const slot = days.flatMap((d) => d.slots)[0]
// 2. Book. page.booking_requires_key true means clinic_paid: call this
// from your server with Authorization: Bearer <the clinic's key>
const res = await fetch(api + "/pages/" + slug + "/bookings", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
slot: { start: slot.start, ref: slot.ref },
topics: [page.topics[0].slug],
patient: { name: "Alex Example", email: "alex@example.com", phone: "0412 345 678", dob: "1990-01-31" },
terms_accepted: true,
// The all-false screener values are a fictional passing test fixture only, never defaults for a real patient. Derive under18 from date of birth and collect the other four answers explicitly.
screener: { under18: false, pregnancy: false, cancer: false, symptoms: false, glandOrTransplant: false },
timezone: tz,
return_url: "https://yourclinic.com.au/booked",
}),
})
const result = await res.json()
// 3. Status only: a payment link, or a reference and a time
if (!result.ok) showError(result.error.code, result.error.message)
else if (result.status === "payment_required") window.location.assign(result.checkout_url)
else showConfirmation(result.booking.reference, result.booking.start, result.next)
The light option, a row of next times, is the widget, for pages where the patient pays.
Mistakes to avoid
Putting the embed on any address other than the clinic's saved website. A preview, staging or site builder address, another subdomain or localhost gets a blank frame. Use the booking link there.
Expecting patient details or the patient's appointment link back. Every booking and checkout answer is status only: reference, start, end and next. The patient gets their link by email.
Putting the API key in browser code. It belongs on a server. The API refuses the Authorization header from browsers, so the call fails.
Using the widget on a page the clinic pays for. It shows times but every booking is refused with use_booking_page. Use the embed or the link.
Sending a field named website in a booking body. It is a spam trap: the answer looks like a confirmed booking (reference BK-CONFIRMED) and nothing is booked.
Building your own consent step or inventing question keys. Consent is never accepted over the API, and answers must use the keys and options from GET /api/v1/pages/<slug>.
Copying embed.js or widget.js to your own server, wrapping the embed in another iframe, or opening checkout_url inside a frame. Load the scripts from consultahealth.com.au and send the patient to checkout_url in the full window.
Build on the demo sandbox first. Then test on the clinic's real page using Test mode from the developer status link the clinic sends you. See the sandbox.
Developer status and test bookings
Ask the clinic to use Send to your developer in Settings, How patients book. Your private status link lasts 30 days. If a key is needed, reveal it once within 72 hours and store it on your server. Never put it in email, browser code or an AI chat.
Enable Test mode on that status page for a token valid for 24 hours. Use data-test="TOKEN" on the embed or widget, or add ?consulta_test=TOKEN to the clinic booking page or the page hosting your embed. With the SDK, pass testToken in the book options, or test in mount options. API calls accept X-Consulta-Test: TOKEN. The token only works with its matching clinic page.
Use fictional details and your own email. Complete the questionnaire and consent on the page or through the TEST email link. No payment is taken, no practitioner is assigned and no slot is held. API bookings return test_confirmed. Check the receipt and questionnaire status on your developer status page. Test receipts and TEST emails are deleted after 7 days. API outcomes are kept for 30 days.
API keys remain required for clinic-paid API bookings and questionnaire submissions. Remove test mode before launch. Invalid, expired or cancelled test tokens are refused and never become real bookings. Renew a test token from the status page, or ask the clinic to renew an expired status link.
Choose how much of the booking screen you want to build. You do not need a contract to start. Reading a page and its open times needs no key or server. Neither does an API booking where the patient pays and uses our questionnaire. To make API bookings the clinic pays for, use its API key from your server. You also need that key to send questionnaire answers.
Your site never sees a card number or the patient's private appointment link. The embed keeps questionnaire answers on Consulta. Do not build a health questionnaire. Consulta asks it after booking. Show the service suitability screener before booking. Bookings appear in your portal like every other booking.
While practising use https://demo.consultahealth.com.au for every API, embed and SDK URL. Use developer-sandbox as the slug. Replace live-host URLs in other examples for this exercise.
For developer-sandbox, use the published sandbox API key below. No private key reveal, developer status link or clinic account is needed for this sandbox exercise. Private handover links apply only when integrating a clinic's own page.
Public sandbox bookings use simulated payment and return confirmed. No real payment is taken and no clinician calls anyone. Do not add an X-Consulta-Test token for this exercise. The public developer-sandbox page shows the demo clinic name Northbank Health in the embed and API settings.
The public sandbox uses normal booking notifications: a patient confirmation with the private manage link, clinic email when enabled, clinical team email when an address exists, and a consent request when needed. Email delivery depends on the configured provider. Mock email is recorded only. Addresses at consulta.dev, example.com, example.org and example.net are recorded only even with the real email provider. Appointment and outstanding-questionnaire reminders use the configured SMS provider. Mock SMS is recorded only, but the sandbox has no separate SMS suppression if real SMS is enabled. Confirmation does not prove delivery.
Build on the demo sandbox at https://demo.consultahealth.com.au first. You do not need an account or help from Consulta. Use fictional patient details and your own email. No real payment is taken and no clinician calls anyone.
Open the public sandbox page,developer-sandbox. It uses clinic-paid bookings with simulated payments. Load the SDK from the demo, or call Consulta.configure({ host }).
Use developer-sandbox in your embed. This one demo page loads on any website, including localhost and preview sites. Set data-host="https://demo.consultahealth.com.au" or load embed.js from the demo.
To test patient checkout, use page northbank-health on the demo. Pay with the test card 4242 4242 4242 4242, any future expiry date, any three-digit CVC and any postcode.
Use an email address you can read. The patient's appointment link only ever arrives by email, on the demo too.
For clinic-paid API bookings and questionnaire answers, use the public sandbox key cx_live_consulta_demo_sandbox_public_001. Send it from your server asAuthorization: Bearer cx_live_consulta_demo_sandbox_public_001. It only works on the demo against developer-sandbox and bookings made on that page. Read the questions and answer options fromGET /api/v1/pages/developer-sandbox. Use the same booking and questionnaire calls documented below. The normal request limits apply. This published demo key is the only key you can share publicly.
Separate Test mode on a clinic page
Test mode uses a renewable 24-hour token and returns test_confirmed. It sends a TEST email, but no SMS, takes no payment, holds no slot and assigns no clinician.
Next, test on the clinic's real page. Open the developer status link the clinic sends you and enable Test mode. Follow the test booking steps. Use the clinic's own key for calls that need one. Remove test mode before launch.
The embed places your full Consulta booking page inside your own page. It adjusts its height and uses your colour, font and corner settings. It hides its border to fit your site. The patient answers our questionnaire and signs consent before paying. The questionnaire step is skipped if your clinic collects its own. Consent is skipped if your clinic has switched it off. We email the patient a link to finish any unanswered steps. We send a text reminder while the questionnaire is unfinished.
Nothing to set up. When an ad link brings a patient to your page with utm tags (utm_source, utm_medium, utm_campaign, utm_content, utm_term) or your own ref, the embed and the widget read them from your page's address and store them with the booking. Our hosted booking page reads its own address the same way. Each tag is plain text up to 100 characters and the patient never sees it. Your clinic sees them in Insights and its download, and webhooks carry them as booking.campaign. Over the API, send them as metadata.
Make it yours
Add each setting as a data attribute, an option on the HTML element. Values are checked on our side, so an unknown value simply falls back to the default.
Your booking page slug, the last part of your booking link (/book/<slug>), 3 to 60 lowercase letters, digits and hyphens. The embed mounts inside this element
data-accent#rrggbb
Buttons, selected times and focus rings. Defaults to the brand colour set on your booking page
data-fontfont name
One of the fonts listed below. inherit uses a system font stack that sits well on most sites
data-radius0 to 24
Corner radius in pixels for buttons, time pills and fields. Larger values are capped at 24
data-topictopic slug
Preselect one consult topic and skip the topic step. A topic the page does not offer is ignored
data-hide-headertrue
Hides the clinic logo and headline, for a page that already shows its own
data-themelight
Reserved. Read but not used yet, the embed is light only
data-hostURL
Where the booking page lives. Defaults to the address embed.js was loaded from. https only (http is allowed for localhost). Set it to the demo host to test with nothing real charged
Attribute
Value
What it does
data-consulta-booking
slug, required
Your booking page slug, the last part of your booking link (/book/<slug>), 3 to 60 lowercase letters, digits and hyphens. The embed mounts inside this element
data-accent
#rrggbb
Buttons, selected times and focus rings. Defaults to the brand colour set on your booking page
data-font
font name
One of the fonts listed below. inherit uses a system font stack that sits well on most sites
data-radius
0 to 24
Corner radius in pixels for buttons, time pills and fields. Larger values are capped at 24
data-topic
topic slug
Preselect one consult topic and skip the topic step. A topic the page does not offer is ignored
data-hide-header
true
Hides the clinic logo and headline, for a page that already shows its own
data-theme
light
Reserved. Read but not used yet, the embed is light only
data-host
URL
Where the booking page lives. Defaults to the address embed.js was loaded from. https only (http is allowed for localhost). Set it to the demo host to test with nothing real charged
Fonts for data-font: inheritInterPoppinsLatoMontserratOpen SansNunitoDM Sans
Events
The embed tells your page what is happening so you can fire your own analytics or change the page around it. Each event is dispatched as a DOM CustomEvent on your element (it bubbles), with the data in event.detail. The frame also posts each one to your window as a message of the form { type, ...data }. consulta:ready, consulta:resize and consulta:step go to any page holding the frame. consulta:checkout and consulta:booked carry the payment address and the booking time, so they are only ever sent to your clinic's own website.
consulta:ready{ }
The booking page has loaded inside the frame
consulta:resize{ height }
The content height changed. embed.js resizes the frame for you, so you only need this for your own layout
consulta:step{ step }
The patient moved to a new step: topic, time, details, health (our questionnaire), consent or confirm. topic is skipped when the page has one topic or data-topic is set, health is completed after booking, consent when its consent form is off. embed.js scrolls the frame back into view if needed
consulta:checkout{ url }
Just before the page goes to the secure payment page. Only sent to your clinic's own website
consulta:booked{ reference, start }
The booking is confirmed. start is an ISO 8601 time. Only sent to your clinic's own website
consulta:escape{ }
The patient pressed Escape inside the frame. embed.js closes the pop-up for you when booking opens from a Book now button
Event
Data
When
consulta:ready
{ }
The booking page has loaded inside the frame
consulta:resize
{ height }
The content height changed. embed.js resizes the frame for you, so you only need this for your own layout
consulta:step
{ step }
The patient moved to a new step: topic, time, details, health (our questionnaire), consent or confirm. topic is skipped when the page has one topic or data-topic is set, health is completed after booking, consent when its consent form is off. embed.js scrolls the frame back into view if needed
consulta:checkout
{ url }
Just before the page goes to the secure payment page. Only sent to your clinic's own website
consulta:booked
{ reference, start }
The booking is confirmed. start is an ISO 8601 time. Only sent to your clinic's own website
consulta:escape
{ }
The patient pressed Escape inside the frame. embed.js closes the pop-up for you when booking opens from a Book now button
Card payment cannot run inside a frame, so when the patient pays, the secure Stripe payment page opens in the full window. Afterwards Stripe sends the patient back to the page they booked from, with ?consulta_checkout= added to the address. embed.js sees it and the frame shows a short confirmation: the reference, the date and time and, if anything is still outstanding, that we have emailed them a link to finish it. Leaving the payment page returns them to the same page with ?consulta_checkout_cancelled=1, and the frame reopens on the times with a note that nothing was charged.
Set your website address first
Your booking page only loads inside the website address saved under Booking page in your portal, for example https://yourclinic.com.au. Both the www and non-www forms work, over https, on any page of that site. Any other address, including another subdomain, a preview or staging address and localhost, is refused by the browser and the frame stays blank, so a copied snippet cannot put your booking page on someone else's site. Use your hosted page link there instead. The page must also be switched on, and a newly saved website address can take a minute to apply.
embed.js and the SDK themselves can be loaded from any site. It is only the booking page inside the frame that checks where it is.
Single-page apps
embed.js finds elements when it loads. If your framework renders the element later, call window.ConsultaEmbed.scan() after it appears, or mount it with the SDK as the React example does. Consulta.mount takes the same settings in camel case and gives you a handle with destroy() for when the component unmounts.
The widget is the compact option: a calendar of your next open times, inline on your page, in each visitor's own timezone. The patient picks a time, enters their details and books right there. It uses HTML inside a shadow root, a separate part of the page. Consulta typography loads by default. Set data-font to inherit to use your own font without loading ours. Your other styles cannot break its layout. If times cannot load it becomes a plain booking button, and a failed submission shows an inline error so nobody loses what they typed. Paid pages hand off to Stripe's hosted payment page.
Pages where the patient pays only
The widget runs in public browser code and cannot hold your API key, so it books pages where the patient pays. On a page your clinic pays for, it still shows times but the booking is refused with use_booking_page. Use the embed or your booking link there. The widget never asks the questionnaire or consent. Both follow by the link we email the patient.
The widget finds its elements once, when the script loads. On a single-page app, load it on the page that shows it, or use the embed.
Attributes
data-fontinherit, system or false
Omit for Consulta typography. inherit uses the host font. system or false uses system fonts. These options load no font files
data-consulta-bookingslug, required
Your booking page slug
data-topictopic slug
Scope the widget to one consult topic
data-limit1 to 12
How many times to show (default 6). Values outside the range are clamped
data-labelstring
Text for the fallback button if times cannot load
data-accent#rrggbb
Override the brand colour set in the portal, e.g. #0e1935
Attribute
Value
What it does
data-font
inherit, system or false
Omit for Consulta typography. inherit uses the host font. system or false uses system fonts. These options load no font files
data-consulta-booking
slug, required
Your booking page slug
data-topic
topic slug
Scope the widget to one consult topic
data-limit
1 to 12
How many times to show (default 6). Values outside the range are clamped
data-label
string
Text for the fallback button if times cannot load
data-accent
#rrggbb
Override the brand colour set in the portal, e.g. #0e1935
Styling it your way
The widget uses Afacad and Alexandria by default. Set data-font="inherit" to use your page's font, or data-font="system" to use system fonts. Both skip font downloads. Everything else is yours to restyle from your own stylesheet. The custom properties cover the common cases in one line each, and every element carries a part name, so a ::part() rule on the host element reaches it through the shadow root. Anything you do not target keeps our defaults.
In your own stylesheet
<style>
[data-consulta-booking] {
--cx-accent: #0e1935; /* buttons, selected time, focus ring */
--cx-accent-text: #ffffff; /* text on the accent colour */
--cx-radius: 8px; /* time pills and buttons (default 999px) */
--cx-input-radius: 8px; /* form fields (default 10px) */
--cx-font-size: 15px; /* base size (default 14px) */
--cx-max-width: 560px; /* width cap (default 460px) */
}
[data-consulta-booking]::part(time) { text-transform: uppercase; }
[data-consulta-booking]::part(button) { box-shadow: 0 2px 0 #0e1935; }
[data-consulta-booking]::part(heading) { display: none; }
</style>
--cx-bordercolour
Card, field and calendar borders
--cx-focuscolour
Keyboard focus outline
--cx-headercolour
Clinic identity header background
--cx-header-textcolour
Clinic identity header text
--cx-hovercolour
Time and date hover background
--cx-selectioncolour
Selected time and date background
--cx-selection-textcolour
Selected time and date text
--cx-fontfont stack
Body and controls, default Afacad
--cx-displayfont stack
Headings, default Alexandria
--cx-card-radiuslength
Outer card, default 24px or 20px on phones
--cx-mutedcolour
Secondary text
--cx-slot-surfacecolour
Available times and confirmation background
--cx-on-accentcolour
Automatically derived foreground, used unless --cx-accent-text is set
--cx-surfacecolour
Field background, also used by the dark colour scheme
--cx-inkcolour
Field text, also used by the dark colour scheme
--cx-accentcolour
Buttons, selected time, focus ring
--cx-accent-textcolour
Override the readable text colour derived from the accent
--cx-radiuslength
Time chips and buttons (default 10px)
--cx-input-radiuslength
Form fields (default 10px) and the booked panel (default 14px)
--cx-font-sizelength
Base size for times and fields (default 17px)
--cx-max-widthlength
The widget's width cap (default 460px)
Property
Value
Controls
--cx-border
colour
Card, field and calendar borders
--cx-focus
colour
Keyboard focus outline
--cx-header
colour
Clinic identity header background
--cx-header-text
colour
Clinic identity header text
--cx-hover
colour
Time and date hover background
--cx-selection
colour
Selected time and date background
--cx-selection-text
colour
Selected time and date text
--cx-font
font stack
Body and controls, default Afacad
--cx-display
font stack
Headings, default Alexandria
--cx-card-radius
length
Outer card, default 24px or 20px on phones
--cx-muted
colour
Secondary text
--cx-slot-surface
colour
Available times and confirmation background
--cx-on-accent
colour
Automatically derived foreground, used unless --cx-accent-text is set
--cx-surface
colour
Field background, also used by the dark colour scheme
--cx-ink
colour
Field text, also used by the dark colour scheme
--cx-accent
colour
Buttons, selected time, focus ring
--cx-accent-text
colour
Override the readable text colour derived from the accent
--cx-radius
length
Time chips and buttons (default 10px)
--cx-input-radius
length
Form fields (default 10px) and the booked panel (default 14px)
--cx-font-size
length
Base size for times and fields (default 17px)
--cx-max-width
length
The widget's width cap (default 460px)
logo::part
Clinic logo image
brand::part
Clinic identity row
avatar::part
Clinic initial
clinic::part
Clinic name
description::part
Consultation format and duration
month::part
Month and week navigation
previous::part
Previous week button
next::part
Next week button
week::part
Seven day strip
day::part
One date button
selecteddate::part
Selected day label
timezone::part
Timezone label
powered::part
Powered by Consulta attribution
wrap::part
The outer container
heading::part
The line above the times, and the chosen time above the form
notice::part
The booked-out notice when the next time is beyond tomorrow
times::part
The row of times
time::part
One selectable time
ghost::part
A placeholder pill while times load
button::part
The primary button: confirm, continue to payment, and the fallback booking button
link::part
The quiet links: see all times, change time
form::part
The details form
field::part
A labelled field (label and input inside)
label::part
A field's label
input::part
A text input
terms::part
The agreement tick and its sentence
error::part
The inline error line
confirmation::part
The booked panel
title::part
The bold line of the booked panel
text::part
The body line of the booked panel
note::part
The small line on the booked panel saying what was emailed to the patient
Part
Selector
Element
logo
::part
Clinic logo image
brand
::part
Clinic identity row
avatar
::part
Clinic initial
clinic
::part
Clinic name
description
::part
Consultation format and duration
month
::part
Month and week navigation
previous
::part
Previous week button
next
::part
Next week button
week
::part
Seven day strip
day
::part
One date button
selecteddate
::part
Selected day label
timezone
::part
Timezone label
powered
::part
Powered by Consulta attribution
wrap
::part
The outer container
heading
::part
The line above the times, and the chosen time above the form
notice
::part
The booked-out notice when the next time is beyond tomorrow
times
::part
The row of times
time
::part
One selectable time
ghost
::part
A placeholder pill while times load
button
::part
The primary button: confirm, continue to payment, and the fallback booking button
link
::part
The quiet links: see all times, change time
form
::part
The details form
field
::part
A labelled field (label and input inside)
label
::part
A field's label
input
::part
A text input
terms
::part
The agreement tick and its sentence
error
::part
The inline error line
confirmation
::part
The booked panel
title
::part
The bold line of the booked panel
text
::part
The body line of the booked panel
note
::part
The small line on the booked panel saying what was emailed to the patient
What you cannot change: the steps, the agreement tick, the Stripe payment page, and the confirmation email and text. Those carry your terms and the clinical record. A live preview is on the embed page.
The SDK is a small JavaScript library for calling the API and loading the embed. It is an ES module and needs no other libraries. Import it straight from our site. Loading it also sets window.Consulta for code on the page that is not a module. TypeScript types are at /sdk/consulta.d.ts. Every call resolves with the API's own response, so the fields below are the same as in the API reference.
The SDK can be loaded from any site and talks to the address it was loaded from. Load it from the demo host to test, or call Consulta.configure({ host }).
Consulta.page(slug)Promise
Your booking page, as { page }. Same shape as GET /pages/{slug}
Consulta.availability(slug, opts)Promise
Open times. opts: from, days, topic, tz. tz defaults to the browser's own zone
Consulta.book(slug, body, opts)Promise
Book a time. Same body and result as POST /pages/{slug}/bookings. opts.apiKey overrides the configured key, server-side only
Point every call at another host, such as the demo, and set a default apiKey for book() and submitQuestionnaire(). apiKey is server-side only, never set it where this runs in a browser
Method
Returns
What it does
Consulta.page(slug)
Promise
Your booking page, as { page }. Same shape as GET /pages/{slug}
Consulta.availability(slug, opts)
Promise
Open times. opts: from, days, topic, tz. tz defaults to the browser's own zone
Consulta.book(slug, body, opts)
Promise
Book a time. Same body and result as POST /pages/{slug}/bookings. opts.apiKey overrides the configured key, server-side only
Send questionnaire answers for a booking that stands, same shape as POST /bookings/{token}/questionnaire. Needs an apiKey, server-side only
Consulta.checkout(sessionId)
Promise
Payment status on your return page
Consulta.booking(token)
Promise
A booking's status, as { booking }, from the token in the patient's own emailed link
Consulta.mount(el, options)
Promise
The embed, mounted from code. options: slug, accent, font, radius, topic, hideHeader, host. Resolves with { iframe, destroy }
Consulta.configure({ host, apiKey })
{ host, apiKey: boolean }
Point every call at another host, such as the demo, and set a default apiKey for book() and submitQuestionnaire(). apiKey is server-side only, never set it where this runs in a browser
A custom booking flow
Fetch the page and its times, draw your own screens, then book. When the page asks the patient to pay, send them to checkout_url. Otherwise the booking is already confirmed, and next is a sentence you can show the patient as it is.
Topic, time, details, book
import Consulta from "https://consultahealth.com.au/sdk/consulta.js"
const slug = "your-page-slug"
const tz = Intl.DateTimeFormat().resolvedOptions().timeZone
// 1. Your page and its open times
const { page } = await Consulta.page(slug)
const { days } = await Consulta.availability(slug, { days: 7, tz })
const slot = days.find((d) => d.slots.length > 0).slots[0]
// 2. Book it
const result = await Consulta.book(slug, {
slot: { start: slot.start, ref: slot.ref },
topics: [page.topics[0].slug],
patient: {
name: "Alex Example",
email: "alex@example.com",
phone: "0400 000 000",
dob: "1990-01-31",
},
timezone: tz,
terms_accepted: true,
// The all-false screener values are a fictional passing test fixture only, never defaults for a real patient. Derive under18 from date of birth and collect the other four answers explicitly.
screener: { under18: false, pregnancy: false, cancer: false, symptoms: false, glandOrTransplant: false },
return_url: "https://yourclinic.com.au/booked",
})
// 3. Pay, or show the confirmation
if (result.status === "payment_required") {
window.location.assign(result.checkout_url)
} else {
showConfirmation(result.booking.reference, result.booking.start, result.next)
}
Your return page
After payment the patient lands on your return_url with consulta_checkout in the address. Ask for its status and show the reference and time. The answer is status only. Card payments are usually paid within seconds. refunded and attention come with a message you can show the patient as it is.
return_url
// On https://yourclinic.com.au/booked
const session = new URLSearchParams(location.search).get("consulta_checkout")
if (session) {
const result = await Consulta.checkout(session)
if (result.status === "paid") showConfirmation(result.booking.reference, result.booking.start, result.next)
else if (result.status === "pending") setTimeout(checkAgain, 2000)
else if (result.status === "expired") showMessage("That payment link expired. Please book again")
else showMessage(result.message)
}
After booking
The patient's appointment link stays with the patient. We email it to them straight after booking (and after payment), and text a reminder while the questionnaire is outstanding. That link opens their questionnaire, consent, and moving or cancelling the booking.
A privacy feature, by design
No API response, SDK result or embed event ever carries that link. Anything your page receives can be read by every script on it, analytics and chat tools included, so the one key to a patient's booking only ever goes to the patient's own inbox. You never need to build or host a clinical form.
A refused call rejects with a ConsultaError carrying the API's stable code, a message you can show the patient, the HTTP status, fields on invalid_request, and retryAfter in seconds when you were rate limited. Two codes come from the SDK itself: network_error when the connection fails, and unsupported for mount outside a browser. Codes are listed under errors and limits.
Handling a refusal
try {
await Consulta.book(slug, body)
} catch (error) {
if (error.code === "slot_taken") return refreshTimes()
if (error.code === "rate_limited") return retryLater(error.retryAfter)
if (error.code === "invalid_request") {
for (const { field, message } of error.fields ?? []) showFieldError(field, message)
return
}
showMessage(error.message)
}
Start every API address with https://consultahealth.com.au/api/v1. Read your page and its open times from the browser without a key. You can also book without a key if the patient pays and you do not send answers. Use your server and the clinic's key for bookings the clinic pays for. Do the same when sending questionnaire answers on any page. Send and receive JSON, a text format for named fields and values. Times use ISO 8601 format in UTC, the shared time reference before conversion to a local timezone. Every response carries ok.
The machine-readable spec is at /api/v1/openapi.json (OpenAPI 3.1). Import it into Postman or Insomnia, or generate a client from it.
Clinic API keys
Create a key under Settings, How patients book, For developers, API keys, in your portal (a clinic manager can). It is shown once, in full, as cx_live_..., so copy it straight into your own server's environment. Send it as:
Server booking for a clinic-paid page. Fictional passing test fixture, with the questionnaire emailed by Consulta.
// Server-side only. Never run this in a browser, the key belongs on
// your own server, in an environment variable such as CONSULTA_API_KEY.
import Consulta from "https://consultahealth.com.au/sdk/consulta.js"
Consulta.configure({ apiKey: process.env.CONSULTA_API_KEY })
const result = await Consulta.book("your-page-slug", {
slot: { start: "2026-11-01T22:00:00.000Z", ref: "8f2c..." },
topics: ["weight-management"],
patient: {
name: "Alex Example",
email: "alex@example.com",
phone: "0400 000 000",
dob: "1990-01-31",
},
terms_accepted: true,
// The all-false screener values are a fictional passing test fixture only, never defaults for a real patient. Derive under18 from date of birth and collect the other four answers explicitly.
screener: { under18: false, pregnancy: false, cancer: false, symptoms: false, glandOrTransplant: false },
// Leave questionnaire out so Consulta emails the patient its hosted form.
})
HeaderAuthorization: Bearer cx_live_...
On every call that needs a key. The key is cx_live_ followed by 32 letters, digits, hyphens or underscores. Anything else reads as unauthorized
CreatedSettings, How patients book, For developers, API keys, in your portal
Shown once, in full, at creation. Only its first characters are shown again afterwards
ScopeOne clinic
A key only works for the pages of the clinic that created it. Used to book on another clinic's page, it reads as forbidden. Used to send answers for another clinic's booking, it reads as not_found
Where it belongsYour server's secret settings
Never in a browser page or an app a patient loads. Browsers cannot send Authorization to this API from another website. Anyone who gets the key can still use it from a server
If exposedRevoke it, then create a new one
A revoked key stops working at once, and reads the same as a key that never existed
Field
Value
Notes
Header
Authorization: Bearer cx_live_...
On every call that needs a key. The key is cx_live_ followed by 32 letters, digits, hyphens or underscores. Anything else reads as unauthorized
Created
Settings, How patients book, For developers, API keys, in your portal
Shown once, in full, at creation. Only its first characters are shown again afterwards
Scope
One clinic
A key only works for the pages of the clinic that created it. Used to book on another clinic's page, it reads as forbidden. Used to send answers for another clinic's booking, it reads as not_found
Where it belongs
Your server's secret settings
Never in a browser page or an app a patient loads. Browsers cannot send Authorization to this API from another website. Anyone who gets the key can still use it from a server
If exposed
Revoke it, then create a new one
A revoked key stops working at once, and reads the same as a key that never existed
Keep the key on your server
Keep the key on your website's server. Never put it in a web page or app a patient loads. Anyone who gets the key can use it from another server. Browser checks cannot stop that. A key for another clinic returns forbidden. An unknown or cancelled key returns unauthorized. The response does not say which problem occurred. The API blocks browsers from sending the Authorization header from another website. The browser checks this before sending the call.
If a key is ever exposed, revoke it in your portal and create a new one. The other booking options work without a key.
Tell patients what you collect, why you need it and where you send it. Get any consent required to collect it. Send only what is needed. You and your developer are responsible for protecting answers while your website collects, stores and sends them to Consulta. This applies to Consulta questionnaire answers. Keep health details out of booking notes sent without a key. Keep keys out of settings with a public prefix, such as NEXT_PUBLIC_CONSULTA_API_KEY. Those settings can appear in browser code.
The patient's manage link stays with the patient
No response hands your site the patient's manage or questionnaire link. We email it to the patient, with a text reminder while the questionnaire is outstanding, so it can only be opened from their own inbox, and consent is never accepted over the API, only there. A booking or payment answer tells you the reference and the time, which is all a confirmation screen needs.
{
"ok": true,
"page": {
"slug": "your-page-slug",
"clinic_name": "Northbank Health",
"logo_url": "https://.../logo.png",
"brand_color": "#176276",
"headline": "Book a phone consult with Northbank Health",
"intro": "Pick a topic and a time. One of our clinical team calls you.",
"website_url": "https://northbank.example",
"timezone": "Australia/Brisbane",
"mode": "patient_paid",
"price": { "cents": 14900, "currency": "AUD", "formatted": "$149" },
"topics": [
{ "slug": "weight-management", "label": "Weight management" },
{ "slug": "sleep-and-stress", "label": "Sleep and stress" }
],
"cancellation_terms": "Cancel with 24 hours notice for a full refund...",
"terms_url": "https://consultahealth.com.au/terms",
"privacy_url": "https://consultahealth.com.au/privacy",
"hosted_url": "https://consultahealth.com.au/book/your-page-slug",
"booking_requires_key": false,
"questionnaire": {
"source": "consulta",
"collected": "by_consulta",
"questions": [
{ "key": "area", "label": "Which area would you like help with?", "required": true,
"options": ["Weight management", "Sleep and stress", "Something else"],
"multi": true, "help": "Pick as many as you like. One consult covers them.",
"unit": null, "none_option": false, "section": "goal" },
{ "key": "height", "label": "Height", "required": false,
"options": null, "multi": false, "help": null, "unit": "cm",
"none_option": false, "section": "about" }
],
"acknowledgements": [
{ "key": "ack_1", "label": "I understand this is a phone consult" }
]
}
}
}
price is set only when the patient pays (mode is patient_paid). On a page your clinic pays for it is null and the patient sees no price. questionnaire.collected is always by_consulta. Consulta asks the questionnaire after booking. Show screener.questions before booking and send its boolean answers in screener. The list is empty when no screen is needed.
GET/api/v1/pages/{slug}/availability
Every open time in a date range, grouped by day in the timezone you ask for.
slugpath, required
Your booking page slug
fromquery, YYYY-MM-DD
First day to return. Defaults to today in tz
daysquery, 1 to 28
How many days to return. Defaults to 7. from plus days must stay within 28 days of today, or the request is refused
topicquery, topic slug
Only times for this topic, a slug from the page's topics
tzquery, IANA zone
Group days in this zone, e.g. Australia/Perth. Defaults to the page's own zone
Parameter
Type
Description
slug
path, required
Your booking page slug
from
query, YYYY-MM-DD
First day to return. Defaults to today in tz
days
query, 1 to 28
How many days to return. Defaults to 7. from plus days must stay within 28 days of today, or the request is refused
topic
query, topic slug
Only times for this topic, a slug from the page's topics
tz
query, IANA zone
Group days in this zone, e.g. Australia/Perth. Defaults to the page's own zone
start and end are UTC. date is the day in the zone you asked for, and every day in the range is listed, empty or not. Times reach 28 days ahead, so a from and days that run past that are refused with invalid_request. Send ref back unchanged. Do not read or change its contents. Times are live, so one can be taken between your fetch and the booking. When that happens the booking call returns slot_taken.
POST/api/v1/pages/{slug}/bookings
Book a time. Either confirms at once or returns a secure payment link to send the patient to. On a page your clinic pays for, this call needs your clinic's own API key.
slot{ start, ref }, required
Both values exactly as returned by availability
topicsstring[]
Up to six topic slugs from the page's topics. Send at least one. Left out, or none the page offers, the booking is filed under the page's general topic
patient{ name, email, phone, dob }, required
All four required. name at least 2 characters. dob is YYYY-MM-DD, in the past, from 1900. phone is an Australian mobile (0412 345 678 or +61 412 345 678) or + and 8 to 15 digits. Spaces, brackets, dots and dashes are ignored
screenerobject, required when page.screener.questions is non-empty
Send all five booleans: under18 derived from date of birth, plus pregnancy, cancer, symptoms and glandOrTransplant from explicit patient answers. All-false examples are fictional passing test fixtures, never defaults
terms_acceptedtrue, required
The patient ticked your page's terms and privacy policy (terms_url, privacy_url)
questionnaireobject, needs an API key
Answers to send with the booking. See Sending the questionnaire over the API, below
notesstring
Optional note from the patient for the care team, up to 1,000 characters (longer is cut)
timezoneIANA zone
Patient-facing times in emails and texts render in it
return_urlhttps URL
Where the patient lands after paying. Must be https, no port, on your page's website host or its www form
cancel_urlhttps URL
Where the patient lands if they leave the payment page. Same rule. Defaults to return_url
Optional campaign tags, text up to 100 characters each, stored on the booking. source to term are your ad's utm tags, lead_ref is your own lead or customer record id. They come back in webhooks and in the clinic's Insights download, never shown to the patient. Any other key is refused
websitenever send
A spam trap. Any non-empty value makes the call answer like a confirmed booking (reference BK-CONFIRMED) while nothing is booked
Body field
Type
Description
slot
{ start, ref }, required
Both values exactly as returned by availability
topics
string[]
Up to six topic slugs from the page's topics. Send at least one. Left out, or none the page offers, the booking is filed under the page's general topic
patient
{ name, email, phone, dob }, required
All four required. name at least 2 characters. dob is YYYY-MM-DD, in the past, from 1900. phone is an Australian mobile (0412 345 678 or +61 412 345 678) or + and 8 to 15 digits. Spaces, brackets, dots and dashes are ignored
screener
object, required when page.screener.questions is non-empty
Send all five booleans: under18 derived from date of birth, plus pregnancy, cancer, symptoms and glandOrTransplant from explicit patient answers. All-false examples are fictional passing test fixtures, never defaults
terms_accepted
true, required
The patient ticked your page's terms and privacy policy (terms_url, privacy_url)
questionnaire
object, needs an API key
Answers to send with the booking. See Sending the questionnaire over the API, below
notes
string
Optional note from the patient for the care team, up to 1,000 characters (longer is cut)
timezone
IANA zone
Patient-facing times in emails and texts render in it
return_url
https URL
Where the patient lands after paying. Must be https, no port, on your page's website host or its www form
cancel_url
https URL
Where the patient lands if they leave the payment page. Same rule. Defaults to return_url
Optional campaign tags, text up to 100 characters each, stored on the booking. source to term are your ad's utm tags, lead_ref is your own lead or customer record id. They come back in webhooks and in the clinic's Insights download, never shown to the patient. Any other key is refused
website
never send
A spam trap. Any non-empty value makes the call answer like a confirmed booking (reference BK-CONFIRMED) while nothing is booked
# The all-false screener values are a fictional passing test fixture only, never defaults for a real patient. Derive under18 from date of birth and collect the other four answers explicitly.
curl -X POST https://consultahealth.com.au/api/v1/pages/your-page-slug/bookings \
-H "Content-Type: application/json" \
-d '{
"slot": { "start": "2026-11-01T22:00:00.000Z", "ref": "8f2c..." },
"topics": ["weight-management"],
"patient": {
"name": "Alex Example",
"email": "alex@example.com",
"phone": "0400 000 000",
"dob": "1990-01-31"
},
"timezone": "Australia/Sydney",
"terms_accepted": true,
"screener": { "under18": false, "pregnancy": false, "cancer": false, "symptoms": false, "glandOrTransplant": false },
"return_url": "https://yourclinic.com.au/booked",
"cancel_url": "https://yourclinic.com.au/book",
"metadata": { "source": "facebook", "medium": "paid_social", "campaign": "spring", "lead_ref": "CRM-1042" }
}'
SDK: Consulta.book(slug, body, opts)
Response: Payment required
// 200: the patient pays, send them to the secure payment page
{
"ok": true,
"status": "payment_required",
"checkout_url": "https://checkout.stripe.com/c/pay/cs_live_..."
}
Response: Confirmed
// 201: no payment step, booked straight away
{
"ok": true,
"status": "confirmed",
"booking": {
"reference": "BK-8A3101",
"start": "2026-11-01T22:00:00.000Z",
"end": "2026-11-01T22:15:00.000Z"
},
"next": "Booked. The patient has been emailed a link to manage the booking, and to complete anything still outstanding (the questionnaire, Medicare details, consent), with a text reminder while the questionnaire is outstanding."
}
On a page where the patient pays you get checkout_url with status 200. The time is not held while the patient pays: the booking is made when payment succeeds, and if the time was taken meanwhile the payment is refunded and the checkout reads refunded. Stripe returns the patient to your return_url with consulta_checkout added. Without a return_url they finish on your hosted Consulta page. On a page your clinic pays for, booking_requires_key is true and this call needs your clinic's API key, or it is refused with key_required. That booking is confirmed at once, with status 201, and your clinic's card is charged.
The response is status only: the reference, the time and next, a sentence to show the patient, never an appointment link. Without questionnaire in the body, we email the patient their own link to the questionnaire, Medicare details and consent, and text a reminder while the questionnaire is outstanding. With your clinic's API key you can send answers here instead, see sending the questionnaire over the API. Consent is never accepted on this call.
POST/api/v1/bookings/{token}/questionnaire
Send questionnaire answers for a booking that already stands. Always needs your clinic's own API key. Despite the path, send the booking's reference here, for example BK-1A2B3C, never a patient's manage token.
tokenpath, required
The booking's reference, for example BK-1A2B3C, from the booking or checkout response
source"consulta", required
Which question set the answers are for
answersarray, required
See Sending the questionnaire over the API, below, for the shape under each source
acknowledgedstring[]
source consulta only: the acknowledgement keys ticked, every one listed on the page
prescribingobject
The Medicare details needed for a script, in either shape
consentnever accepted
Refused with invalid_request. The patient signs consent at the link they are emailed
Body field
Type
Description
token
path, required
The booking's reference, for example BK-1A2B3C, from the booking or checkout response
source
"consulta", required
Which question set the answers are for
answers
array, required
See Sending the questionnaire over the API, below, for the shape under each source
acknowledged
string[]
source consulta only: the acknowledgement keys ticked, every one listed on the page
prescribing
object
The Medicare details needed for a script, in either shape
consent
never accepted
Refused with invalid_request. The patient signs consent at the link they are emailed
For a booking already made. Despite the path, send the booking reference here, for example BK-1A2B3C, never a patient's manage token: this path is named token to match GET /bookings/{token}, but it is a different value. Answers are taken once only, within two hours of booking and before the consult starts. After that, window_closed is returned and the patient can still complete it at the link they were emailed. See sending the questionnaire over the API for the body shape.
GET/api/v1/checkout/{session_id}
For your return page after payment. Status only: whether the payment went through and, once it has, the booking's reference and time.
session_idpath, required
The consulta_checkout value added to your return_url
Parameter
Type
Description
session_id
path, required
The consulta_checkout value added to your return_url
{
"ok": true,
"status": "paid",
"booking": {
"reference": "BK-8A3101",
"start": "2026-11-01T22:00:00.000Z",
"end": "2026-11-01T22:15:00.000Z"
},
"next": "Booked. The patient has been emailed a link to complete their questionnaire and manage the booking, and is texted a reminder while the questionnaire is outstanding."
}
status is paid, pending, expired, refunded or attention. Once it is paid you get the booking's reference and time and next, never an appointment link. A pending payment usually settles within seconds, so poll every couple of seconds before showing a message. refunded means the time was taken while the patient paid and the money is on its way back. Both it and attention carry a message to show the patient.
GET/api/v1/bookings/{token}
A booking's status by the token in the patient's own emailed link: the reference, the times and the status, nothing more. Your integration never receives this token. It is for tools the patient opens from that link.
tokenpath, required
The last path segment of the patient's appointment link, a UUID
Parameter
Type
Description
token
path, required
The last path segment of the patient's appointment link, a UUID
The token is the last part of the appointment link we email the patient. Your integration never receives it, so this endpoint is for tools the patient opens from their own link. Anyone holding the token can see this status, which is why it carries only the reference, the times and status: confirmed, completed, no_answer or a cancelled state such as cancelled_by_patient. Cancelling and moving a booking happen on the appointment page itself.
Sending the questionnaire over the API
With your clinic's API key, questionnaire answers go either with the booking (questionnaire in the body of POST /pages/{slug}/bookings) or afterwards, through POST /bookings/{token}/questionnaire, within two hours of booking and before the consult starts. Either way the shape is the same: source plus answers, and an optional prescribing. Without a key, leave questionnaire out of the booking, and the patient completes it themselves at the link they are emailed. Consent is never accepted over the API, in either shape, the patient always signs it at the link they are emailed.
The API question list does not include conditional visibility rules. Do not infer applicability from labels or section names. Use Consulta's hosted questionnaire, which Consulta emails to the patient, unless your integration truly needs server-submitted answers and has a verified applicability mapping. A required answer that applies means a question visible under the server's rules for the submitted answers. Missing required visible answers return invalid_questionnaire. Missing hidden conditional answers are accepted, and supplied hidden answers are ignored. The server also requires at least one non-empty visible answer and every acknowledgement.
source: "consulta"
Answers the page's own question set, from GET /pages/{slug}'s questionnaire.questions, checked the same way the patient's own form is: every required visible question answered, a choice question answered with one of its options, and every acknowledgement in questionnaire.acknowledgements ticked in acknowledged. Every clinic uses this set plus its extra questions. Sources clinic and clinic_form are retired and return questionnaire_source_retired.
Abbreviated shape only. Not a complete valid request. Required visible answers follow the server rules explained above. Prefer Consulta's hosted form.
{
"source": "consulta",
"answers": [{ "key": "goal", "answer": "I would like to sleep better" }],
"acknowledged": ["ack_in_australia"]
}
keystring
Send the answer under this key, from the page's own questionnaire.questions
labelstring
The question text, for your own display only
requiredboolean
Required only when visible under the server rules for submitted answers. Missing visible answers return invalid_questionnaire. Missing hidden answers are accepted. Conditional visibility rules are not included in this question list
optionsstring[] or null
Present only for a choice question. The answer must equal one option exactly, or (with multi) the ticked options joined with ", "
multiboolean
true when more than one option may be chosen
helpstring or null
A quiet explanatory line under the label
unitstring or null
Present for a measurement question, for example cm. Answer as "178 cm"
none_optionboolean
true when the hosted form offers a one tap None shortcut for this question
sectionstring or null
A grouping key such as goals, shared by consecutive questions. Cosmetic only, safe to ignore
Field
Type
Notes
key
string
Send the answer under this key, from the page's own questionnaire.questions
label
string
The question text, for your own display only
required
boolean
Required only when visible under the server rules for submitted answers. Missing visible answers return invalid_questionnaire. Missing hidden answers are accepted. Conditional visibility rules are not included in this question list
options
string[] or null
Present only for a choice question. The answer must equal one option exactly, or (with multi) the ticked options joined with ", "
multi
boolean
true when more than one option may be chosen
help
string or null
A quiet explanatory line under the label
unit
string or null
Present for a measurement question, for example cm. Answer as "178 cm"
none_option
boolean
true when the hosted form offers a one tap None shortcut for this question
section
string or null
A grouping key such as goals, shared by consecutive questions. Cosmetic only, safe to ignore
Build each control from options and multi, never a plain text box for a question that has options, or a correctly filled form can still be refused. Answer formats:
no optionsfree text
Any string. Longer than 2000 characters is cut to 2000
options, not multiexact match
The answer must equal exactly one of options, case and spacing included
options, multijoined list
The ticked options joined with ", " (comma, space). Every part must be one of options. Keep the order of options for a tidy record
none_option: truethe literal word
The hosted form writes exactly "None" (capital N) for its shortcut. Any other free text is also accepted
unit setnumber and unit
The number, a space and the unit exactly as given, e.g. "178 cm" for a field with unit "cm". Not checked, but this is how the hosted form writes it
unknown keyignored
An answer whose key is not in the page's questions is dropped without an error, so check your keys against GET /pages/{slug}
Question shape
Format
Rule
no options
free text
Any string. Longer than 2000 characters is cut to 2000
options, not multi
exact match
The answer must equal exactly one of options, case and spacing included
options, multi
joined list
The ticked options joined with ", " (comma, space). Every part must be one of options. Keep the order of options for a tidy record
none_option: true
the literal word
The hosted form writes exactly "None" (capital N) for its shortcut. Any other free text is also accepted
unit set
number and unit
The number, a space and the unit exactly as given, e.g. "178 cm" for a field with unit "cm". Not checked, but this is how the hosted form writes it
unknown key
ignored
An answer whose key is not in the page's questions is dropped without an error, so check your keys against GET /pages/{slug}
Before payment: service suitability
Do not build a health questionnaire. Consulta asks it. Show the screener questions from GET /pages/{slug} and send the answers with the booking. Derive under18 from the date of birth. All answers are booleans. A yes stops booking with screener_stopped and patient guidance. Nothing is held or charged. Do not store stopped answers. Missing answers return screener_required. An empty question list means the screen is not needed.
prescribing
The Medicare details a script needs, with source consulta. Any field left out is simply not stored. Send it prefilled from your own patient records if you have them, or ask the patient for it on your own form.
medicare_numberstring
The 10 digits on the Medicare card
medicare_irnstring
The single digit beside the patient's name on the card, 1 to 9
medicare_expirystring, YYYY-MM
The card's expiry month
sexfemale, male, intersex or not_stated
For the Medicare and eScript identity check
treatment_addressstring
Where the patient will be when dispensing, for the script
any other fieldrefused
An unknown field in prescribing is refused with invalid_request, so a typo is never silently dropped
Field
Type
Notes
medicare_number
string
The 10 digits on the Medicare card
medicare_irn
string
The single digit beside the patient's name on the card, 1 to 9
medicare_expiry
string, YYYY-MM
The card's expiry month
sex
female, male, intersex or not_stated
For the Medicare and eScript identity check
treatment_address
string
Where the patient will be when dispensing, for the script
any other field
refused
An unknown field in prescribing is refused with invalid_request, so a typo is never silently dropped
Errors and limits
A refused request returns a 4xx or 5xx status and the same body every time: ok is false and error carries a stable code to branch on, a message you can show the patient and, for invalid_request, fields naming each problem. Validation refusals happen before payment. A timeout or an unknown error can occur after payment or confirmation. Do not resubmit automatically. Follow the recovery steps below. Do not assume nothing was charged.
POST bookings is not idempotent, even for the same slot and patient. Retrying a confirmed clinic-paid booking normally returns slot_taken, not the original receipt. Earlier validation or limits can also refuse the retry. slot_taken does not identify the patient holding the slot and is not proof your booking succeeded. There is no receipt lookup by booking reference and API key. After a timeout or booking_failed, do not resubmit automatically or choose another slot. Ask the patient to check their emailed link, or ask the clinic to check its Bookings using the request time, patient details and any reference received. For patient checkout, use GET /api/v1/checkout/{session_id} when you have consulta_checkout from the return URL. A repeated patient-paid POST can create another checkout, so do not repeat payment blindly. Use the private developer status page for token-based test receipts.
A refused booking
HTTP/1.1 400 Bad Request
Content-Type: application/json
Access-Control-Allow-Origin: *
{
"ok": false,
"error": {
"code": "invalid_request",
"message": "Some fields need attention. See error.fields.",
"fields": [
{ "field": "patient.phone", "message": "Enter an Australian mobile like 0412 345 678, or an international number starting with +." },
{ "field": "terms_accepted", "message": "The patient must accept the terms. Send terms_accepted: true." }
]
}
}
screener_required422
Show the questions from GET /pages/{slug} and send all five boolean answers with the booking
screener_stopped422
Show the returned guidance. Nothing was held, charged or rostered. Do not store the answers
questionnaire_source_retired422
Use Consulta questionnaire questions plus the clinic's optional extras
payments_unavailable503
Payments are temporarily unavailable. Try again shortly
invalid_request400
Check error.fields for missing or incorrectly formatted values. Each field has a message explaining the problem
invalid_return_url400
return_url or cancel_url is not an https address on your page's website
invalid_questionnaire400
Read error.message and fix the answers. A required answer may be missing or a choice may not match the options. Use source consulta for every clinic
page_closed403
The page is switched off, or not taking bookings right now
forbidden403
Use a key for this clinic. The key sent does not allow access to this page
unauthorized401
Check the key in your server settings. It may be incorrectly formatted, unknown or cancelled. All three return the same error
key_required401
Send the clinic's key as Authorization: Bearer cx_live_... from your server. None was sent. A key is required for a clinic_paid booking, a booking with questionnaire answers, and every POST /bookings/{token}/questionnaire
payload_too_large413
The request body is over its size limit: 32 KB, or 512 KB when a valid API key is sent. A real booking is well under 2 KB
not_found404
Check the page slug or reference. No open page, checkout or booking matches. A keyed questionnaire call only finds bookings in the key's clinic
slot_taken409
That time was just booked, or is no longer bookable. Fetch availability again and let the patient pick
already_answered409
This booking already has questionnaire answers. Contact the clinic to correct them
window_closed409
Ask the patient to use their emailed questionnaire link. The API only takes answers within 2 hours of booking, before the consult starts and while the booking is confirmed
rate_limited429
Wait the number of seconds in Retry-After before trying again. Too many requests were sent
daily_cap_reached429
Ask the clinic to raise its daily booking cap, or try tomorrow. This clinic_paid page has reached its cap. Retry-After is 3600
booking_failed500
The booking outcome could not be confirmed. Do not resubmit automatically. Ask the patient to check their emailed link or the clinic to check its Bookings
unavailable503
Try again shortly. Nothing was booked or charged. If the request limit could not be checked, Retry-After says how many seconds to wait
Code
Status
Meaning
screener_required
422
Show the questions from GET /pages/{slug} and send all five boolean answers with the booking
screener_stopped
422
Show the returned guidance. Nothing was held, charged or rostered. Do not store the answers
questionnaire_source_retired
422
Use Consulta questionnaire questions plus the clinic's optional extras
payments_unavailable
503
Payments are temporarily unavailable. Try again shortly
invalid_request
400
Check error.fields for missing or incorrectly formatted values. Each field has a message explaining the problem
invalid_return_url
400
return_url or cancel_url is not an https address on your page's website
invalid_questionnaire
400
Read error.message and fix the answers. A required answer may be missing or a choice may not match the options. Use source consulta for every clinic
page_closed
403
The page is switched off, or not taking bookings right now
forbidden
403
Use a key for this clinic. The key sent does not allow access to this page
unauthorized
401
Check the key in your server settings. It may be incorrectly formatted, unknown or cancelled. All three return the same error
key_required
401
Send the clinic's key as Authorization: Bearer cx_live_... from your server. None was sent. A key is required for a clinic_paid booking, a booking with questionnaire answers, and every POST /bookings/{token}/questionnaire
payload_too_large
413
The request body is over its size limit: 32 KB, or 512 KB when a valid API key is sent. A real booking is well under 2 KB
not_found
404
Check the page slug or reference. No open page, checkout or booking matches. A keyed questionnaire call only finds bookings in the key's clinic
slot_taken
409
That time was just booked, or is no longer bookable. Fetch availability again and let the patient pick
already_answered
409
This booking already has questionnaire answers. Contact the clinic to correct them
window_closed
409
Ask the patient to use their emailed questionnaire link. The API only takes answers within 2 hours of booking, before the consult starts and while the booking is confirmed
rate_limited
429
Wait the number of seconds in Retry-After before trying again. Too many requests were sent
daily_cap_reached
429
Ask the clinic to raise its daily booking cap, or try tomorrow. This clinic_paid page has reached its cap. Retry-After is 3600
booking_failed
500
The booking outcome could not be confirmed. Do not resubmit automatically. Ask the patient to check their emailed link or the clinic to check its Bookings
unavailable
503
Try again shortly. Nothing was booked or charged. If the request limit could not be checked, Retry-After says how many seconds to wait
Rate limits. These limits cap how many requests you can send in a set time. Each calling IP address can make 240 reads every 5 minutes. Booking and questionnaire calls share 30 requests every 10 minutes. Browsing times also uses the booking page's limit of 120 every 5 minutes. Real booking attempts have two more limits: 5 every 10 minutes per calling address and 30 an hour per booking page. A clinic_paid page also has a daily booking cap. It is 20 by default. The clinic can set it from 1 to 500 in its portal. A server booking for many patients shares one calling address limit. Calls that write data with a key share 30 requests per key and 60 per clinic every 10 minutes. Each page allows 12 checkout starts per 35 minutes, with 3 per patient email. Unfinished checkouts count until they expire. A request over a limit returns 429. Read Retry-After, the response header that says how many seconds to wait. Wait that long before trying again.
Browser access (CORS). CORS tells a browser which calls it may send to another website. Every endpoint allows calls from any website and answers the browser's checks before a call. The exception is theAuthorization header used for API keys. Send calls with that header from your server.
Double bookings. A time can only be booked once. The slot guard prevents overlapping bookings, but does not return the original receipt or make POST bookings idempotent. A slot_taken response does not establish which patient booked the time.
Versioning. Fields may be added to responses within v1. Nothing is removed or renamed without a new version.
Coming later, not in v1
Rescheduling and cancelling over the API (the patient's emailed appointment link does both)
Idempotency keys (the slot guard already stops a double booking)
The widget runs on two older endpoints, which keep working unchanged. New builds should use v1, whose questionnaire over the API now covers the same case, a clinic sending its own answers with the booking, with the same shape as sending them afterwards, and with a key rather than an open route.
GET /api/embed/slots and POST /api/embed/book›
GET /api/embed/slots
GET https://consultahealth.com.au/api/embed/slots?slug=your-page-slug&limit=6
&topic=optional-topic
Cached at the edge for 60 seconds (public, s-maxage=60, stale-while-revalidate=300), so times can be up to a minute old. If a booking comes back slot_taken, fetch the feed again. It returns clinicName, accent, bookUrl, mode, priceCents, payOnline, defaultTopic, slots[] as { start, doctorId }, and questionnaire: its source, questions[] and acknowledgements[] (a page that collects its own returns Consulta questions). limit is 1 to 12, default 5. An unknown or closed page answers 404 with { ok: false }. The questions are for display only, since this route no longer takes answers.
keystring
The question's key, the same key source consulta answers use on API v1
labelstring
The question text
requiredboolean
Must be answered when answers are sent over API v1
placeholderstring or null
Hint text for a free-text field
optionsstring[] or null
Present only for a choice question
multiboolean
true when more than one option may be chosen
helpstring or null
A quiet explanatory line under the label
unitstring or null
Present for a measurement question, for example cm
noneOptionboolean
true when the hosted form offers a one-tap "None" shortcut for this question
sectionstring or null
A grouping key such as goals. Cosmetic only, safe to ignore
Field
Type
Notes
key
string
The question's key, the same key source consulta answers use on API v1
label
string
The question text
required
boolean
Must be answered when answers are sent over API v1
placeholder
string or null
Hint text for a free-text field
options
string[] or null
Present only for a choice question
multi
boolean
true when more than one option may be chosen
help
string or null
A quiet explanatory line under the label
unit
string or null
Present for a measurement question, for example cm
noneOption
boolean
true when the hosted form offers a one-tap "None" shortcut for this question
section
string or null
A grouping key such as goals. Cosmetic only, safe to ignore
This route runs in public browser code and cannot hold your API key, so since 20 October 2026 it books patient-paid pages only and takes no questionnaire answers. A request carrying intake or acknowledgements is refused with intake_not_accepted, and a page your clinic pays for is refused with use_booking_page. The patient completes the questionnaire at the link they are emailed. To send answers, or to book a page your clinic pays for, use API v1 from your server with your key.
Responses
// patient pays on your page's terms: redirect the visitor here
{ "ok": true, "checkout": true, "checkoutUrl": "https://checkout.stripe.com/..." }
// no online payment step (a test environment): booked at once, status only
{ "ok": true, "statusOnly": true, "reference": "BK-8A3101",
"slotStart": "...", "slotEnd": "...", "doctorName": "", "priceLabel": "$149",
"manageUrl": null }
// refused: nothing was booked or charged
{ "ok": false, "code": "slot_taken", "message": "..." }
bad_request400
The body is not a JSON object
slot_taken400
That time was just booked, refresh the feed
invalid_details / invalid_phone / invalid_dob400
Check the patient's details, phone number or date of birth
terms_required400
termsAccepted was not true
intake_not_accepted400
intake or acknowledgements was sent. This route takes no answers, send them with your key over API v1
use_booking_page403
Your clinic pays for this page's bookings, so this key-less route cannot book it. Use the embed, your booking link, or API v1 with your key
payload_too_large413
The request body is over 32 KB
closed400
The page is not taking bookings
lookup_failed503
Your booking page could not be read. Temporary, retry
too_many_requests429
Rate limit reached, wait for Retry-After
unavailable503
The request budget could not be checked. Temporary, retry. Nothing was booked
unknown400
Outcome uncertain: payment or booking may have succeeded. Do not resubmit automatically. Ask the patient to check their emailed link or the clinic to check its Bookings
Code
Status
Meaning
bad_request
400
The body is not a JSON object
slot_taken
400
That time was just booked, refresh the feed
invalid_details / invalid_phone / invalid_dob
400
Check the patient's details, phone number or date of birth
terms_required
400
termsAccepted was not true
intake_not_accepted
400
intake or acknowledgements was sent. This route takes no answers, send them with your key over API v1
use_booking_page
403
Your clinic pays for this page's bookings, so this key-less route cannot book it. Use the embed, your booking link, or API v1 with your key
payload_too_large
413
The request body is over 32 KB
closed
400
The page is not taking bookings
lookup_failed
503
Your booking page could not be read. Temporary, retry
too_many_requests
429
Rate limit reached, wait for Retry-After
unavailable
503
The request budget could not be checked. Temporary, retry. Nothing was booked
unknown
400
Outcome uncertain: payment or booking may have succeeded. Do not resubmit automatically. Ask the patient to check their emailed link or the clinic to check its Bookings
A webhook is a message Consulta sends to your system when a booking changes. Set one up in your portal under Settings, How patients book, For developers, Webhooks. Enter an https URL with a public domain name, not an IP address. Consulta creates a signing secret so your system can check each message. It sends a POST request for the ten events below, for bookings from any channel. Use these messages to connect a customer records system, Mailchimp, Zapier or Make without custom development on either side.
booking.createdevent
A booking is made, any channel
booking.rescheduledevent
The appointment is moved
booking.cancelled_by_patientevent
The patient cancelled
booking.cancelled_by_clinicevent
Your clinic cancelled
booking.cancelled_by_doctorevent
The practitioner cancelled (the event name is fixed)
consult.completedevent
The clinician confirms the consult happened
consult.no_answerevent
The clinician could not reach the patient
consult.script_returnedevent
A script comes back to the booking
booking.questionnaire_completedevent
The questionnaire is submitted, by the patient or over the API
booking.patient_documentevent
The patient shares a document (adds booking.file_name)
payment.refundedevent
Money on the booking is refunded, in full or in part. Adds refund: amount_refunded_cents (this refund), total_refunded_cents, amount_charged_cents, type (full or partial) and paid_by (patient or clinic)
Event
Kind
When
booking.created
event
A booking is made, any channel
booking.rescheduled
event
The appointment is moved
booking.cancelled_by_patient
event
The patient cancelled
booking.cancelled_by_clinic
event
Your clinic cancelled
booking.cancelled_by_doctor
event
The practitioner cancelled (the event name is fixed)
consult.completed
event
The clinician confirms the consult happened
consult.no_answer
event
The clinician could not reach the patient
consult.script_returned
event
A script comes back to the booking
booking.questionnaire_completed
event
The questionnaire is submitted, by the patient or over the API
booking.patient_document
event
The patient shares a document (adds booking.file_name)
payment.refunded
event
Money on the booking is refunded, in full or in part. Adds refund: amount_refunded_cents (this refund), total_refunded_cents, amount_charged_cents, type (full or partial) and paid_by (patient or clinic)
What messages leave out: questionnaire answers, clinical notes, outcome detail, prescriptions and Consulta's fees never appear in the message body, called the payload. Only the listed fields are included. Messages do carry the patient's contact details, the consult topic and, for patient documents, the file name, so treat every payload as personal information. Send webhooks only to systems allowed to hold it.
Campaign tags:booking.campaign carries the source, medium, campaign, content and term from the ad link that brought the booking, and your own lead_ref. Every key is present and is null when the booking had no tag. booking.amount_paid_cents is what the patient paid on your booking page when they booked, before any refund, or null when no patient payment was taken.
Verifying and retries
Every request carries X-Consulta-Event, X-Consulta-Delivery and X-Consulta-Signature. Use the delivery id to ignore duplicates. Retries use the same id. The signature has the form sha256=<hex>. Check it with HMAC-SHA256, which combines the unchanged message body with your signing secret. Reject messages that fail this check. Return a success status, 2xx, within 6 seconds. Redirects are not followed. Otherwise Consulta makes up to five attempts in total: the immediate send, then retries about 5 minutes, 25 minutes, 105 minutes and 7 hours after the event. Your portal shows the most recent deliveries and their status.
Export your records from Settings > Data in your portal whenever you need them. The download is a CSV file you can open in a spreadsheet. It includes every consult with its practitioner, times, outcome and price. It also includes your patient list with contact details and references, every questionnaire answer and every prescription with its eScript link. Download attached documents and the printable consult record from each booking's records.
Patient fields Consulta holds
full namestring
Required at booking
emailstring
Required at booking
mobilestring
Required, the clinician calls it
date of birthdate
Required on API v1 bookings, optional through the widget
your referencestring
Your own patient identifier, optional
questionnaire answersper your page
Whatever questions your page asks, saved as answered
Field
Type
Notes
full name
string
Required at booking
email
string
Required at booking
mobile
string
Required, the clinician calls it
date of birth
date
Required on API v1 bookings, optional through the widget
your reference
string
Your own patient identifier, optional
questionnaire answers
per your page
Whatever questions your page asks, saved as answered
Consulta removes contact details from old bookings on a schedule to keep less personal information. The clinical record is kept.
Patient and clinic records are stored in Australia (Sydney). Payments are processed by Stripe, and card details never touch Consulta's servers or yours. Anything you point a webhook at is hosted wherever that system lives.
Every clinic and practitioner account must set up multi-factor authentication, an extra sign-in check, before using the portal. Database rules let each clinic access only its own records. Only managers can change billing, booking page settings and webhooks.
The public API and the embed only ever expose what your booking page already shows a visitor. They never return questionnaire answers, notes, another patient's details or a patient's appointment link, which goes only to the patient by email. Your booking page only loads inside your own website. The public demo sandbox is the only exception. Every booking uses the same checks as your hosted page. Consulta checks the terms, calculates the price on its server and checks that the time is still available.