# Consulta booking for clinic websites ## Questionnaire and pre-payment screener Do not build a health questionnaire. Consulta asks it after booking and collects consent. Every clinic uses the standard questions plus its optional extra questions. Before booking, show the screener questions from GET /pages/{slug}. Derive under18 from the date of birth and send all five boolean answers as screener with POST /pages/{slug}/bookings. A yes returns screener_stopped before any time is held, payment is taken or roster entry is created. Use the patient's actual responses, never default answers to No. Show the returned guidance and do not store stopped answers. Missing answers return screener_required. If the questions list is empty, omit the screen. 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. ## 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. ## Developer handover and test mode The clinic can email a brief and private developer status link from Settings, How patients book. Status lasts 30 days. Reveal an API key once within 72 hours and store it only on your server, never in browser code, email or an AI chat. Enable Test mode there for a renewable 24-hour token. Use data-test="TOKEN" on embed or widget, ?consulta_test=TOKEN on a booking page or embedding page, SDK book options { testToken: "TOKEN" }, SDK mount options { test: "TOKEN" }, or the API header X-Consulta-Test: TOKEN. It only works with its matching clinic page. API keys remain required where documented. Use fictional details and your own email. Complete questionnaire and consent on the page or the TEST email link. Test bookings return test_confirmed, never charge or reserve a slot, never assign a practitioner, and send no SMS. Test receipts and TEST emails are deleted after 7 days. API outcomes are kept 30 days. Check receipt and questionnaire status on the developer status page. Remove test mode before launch. > Consulta runs phone consults with verified clinicians for Australian clinics. Every clinic has a booking page at https://consultahealth.com.au/book/. A slug is the last part of that booking link. Follow these steps to add booking to a clinic's website. There are three ways to add booking: the booking link, the embed, and the API (a clinic API key is needed for some calls). A lighter widget also exists for pages where the patient pays. ## Ask the clinic first - The clinic's booking page slug: the last part of its booking link, https://consultahealth.com.au/book/, shown under Settings, How patients book in the clinic's Consulta portal. - Whether the patient or the clinic pays. GET /api/v1/pages/ 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 website, any page, with no rules. Use it wherever the embed cannot load. Book a consult ## Path 2: the embed (recommended) The clinic's full booking page inside its own site: topic, time, details, the suitability screen, Consulta's questionnaire and payment. Paste exactly this, with the slug filled in, on a page of the clinic's saved website.
- Loads only on the website address saved on the clinic's booking page, over https, on that host or its www form. Anywhere else the frame is blank. - The booking page must be switched on. A newly saved website address can take a minute to apply. - Optional attributes on the div: data-accent="#rrggbb", data-font (inherit, Inter, Poppins, Lato, Montserrat, Open Sans, Nunito, DM Sans), data-radius (0 to 24), data-topic (a topic slug), data-hide-header="true", data-host (https://demo.consultahealth.com.au to test). - Events dispatched on the div as CustomEvents: consulta:ready, consulta:resize { height }, consulta:step { step }, consulta:checkout { url }, consulta:booked { reference, start }. - In a single-page app, call window.ConsultaEmbed.scan() after the div appears, or use Consulta.mount from the SDK. ## Path 3: the API For a booking flow drawn in the clinic's own screens. Base URL https://consultahealth.com.au/api/v1. JSON in and out, times in UTC ISO 8601, every answer has ok. - GET /pages/ returns the page: topics, mode (patient_paid or clinic_paid), booking_requires_key, website_url, and questionnaire (source, collected, questions, acknowledgements). - GET /pages//availability?days=7&tz= returns days, each with slots { start, end, ref }. Up to 28 days ahead. - POST /pages//bookings with { slot: { start, ref }, topics, patient: { name, email, phone, dob }, terms_accepted: true, screener, return_url }. Answers 200 { status: "payment_required", checkout_url } or 201 { status: "confirmed", booking: { reference, start, end }, next }. - GET /checkout/ on the return page, with the consulta_checkout value Stripe adds to return_url. Answers paid, pending, expired, refunded or attention. - POST /bookings//questionnaire sends questionnaire answers for a booking made in the last 2 hours. Needs the clinic's key. - Errors are { ok: false, error: { code, message, fields } }. A 429 response means a request limit was reached. Read Retry-After, the response header that says how many seconds to wait before trying again. No key is needed to read a page, read times, or book a page where the patient pays. The clinic's API key is needed to book a page the clinic pays for and to send questionnaire answers. Send it as Authorization: Bearer cx_live_... from a server only. const res = await fetch("https://consultahealth.com.au/api/v1/pages//bookings", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body), }) const result = await res.json() if (result.status === "payment_required") window.location.assign(result.checkout_url) A JavaScript SDK wraps the same calls: import Consulta from "https://consultahealth.com.au/sdk/consulta.js" (types at https://consultahealth.com.au/sdk/consulta.d.ts). ## The widget (patient-paid pages only) A row of the next open times, inline, for pages where the patient pays.
Restyle it with the --cx- custom properties and ::part() rules listed in the developer guide. On a page the clinic pays for, every booking is refused with use_booking_page, so use the embed or the link there. ## Rules an integrator must respect - The questionnaire and consent stay on Consulta's pages. Hosted bookings use the private link emailed after booking. The embed also offers the same questionnaire in its flow after screening. Consent is never accepted over the API. Questionnaire answers go over the API only with the clinic's key, from a server. - Receipts are status only: reference, start, end and next. No answer ever carries patient details or the patient's appointment link. That link goes to the patient by email only. - The embed runs only on the clinic's saved website. The public demo sandbox page below is the only exception. - Questionnaire and prescribing fields require the clinic's key. Keep health details out of notes sent without a key. Notes and topic selections can still contain health information. Collect only what you need. Tell patients what you collect, why you need it and where you send it. Get any consent required to collect it. You and your developer must protect answers while your website collects, stores and sends them. Only source consulta is accepted. The clinic and clinic_form sources return questionnaire_source_retired. Keep keys out of public settings such as NEXT_PUBLIC_CONSULTA_API_KEY. Anyone who gets a key can use it from another server. Browser checks cannot stop that. Never put the key in a browser or an app a patient loads. - Load embed.js, widget.js and the SDK from https://consultahealth.com.au, unmodified. Send the patient to checkout_url in the full window, never in a frame. - Send slot.start and slot.ref back exactly as availability gave them. Read question keys and options from GET /pages/, never invent them. ## Mistakes AI agents commonly make - 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/. - 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. ## Public sandbox for practice 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 first. No account or help from Consulta is needed. Use fictional details and your own email. No real payment is taken and no clinician calls anyone. - Public page: https://demo.consultahealth.com.au/book/developer-sandbox. This page uses clinic-paid bookings with simulated payments. - Embed: use data-consulta-booking="developer-sandbox" and data-host="https://demo.consultahealth.com.au", or load embed.js from the demo. This one page loads on any website, including localhost and preview sites. - Public sandbox API key: cx_live_consulta_demo_sandbox_public_001. Send Authorization: Bearer cx_live_consulta_demo_sandbox_public_001 from your server. It only works on the demo against developer-sandbox and bookings made on that page. This published demo key is the only key you can share publicly. - Read GET https://demo.consultahealth.com.au/api/v1/pages/developer-sandbox for questions and answer options. Use the booking and questionnaire calls above. The normal request limits apply. - To test patient checkout, use demo page northbank-health. Pay with 4242 4242 4242 4242, any future expiry date, any three-digit CVC and any postcode. ## Separate Test mode on a clinic page Then 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 above. Use the clinic's own key for calls that need one. Remove test mode before launch. ## Uncertain booking results 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. ## Request limits A rate limit caps 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 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 page. A clinic_paid page also has a daily cap of 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. Requests over a limit return 429. Retry-After is the response header that says how many seconds to wait. Wait that long before trying again. A webhook is a message Consulta sends to your system when a booking changes. Follow the webhook guide below to set one up and check its signing secret. ## Full reference - [Developer guide](https://consultahealth.com.au/developers): every attribute, event, endpoint, field, error code and limit - [For AI agents](https://consultahealth.com.au/developers#for-ai-agents): the short version of this file, with copy-paste snippets - [OpenAPI 3.1 spec](https://consultahealth.com.au/api/v1/openapi.json): the API, machine readable - [Errors and limits](https://consultahealth.com.au/developers#errors) - [Webhooks](https://consultahealth.com.au/developers#webhooks): signed booking events for the clinic's own systems - [JavaScript SDK](https://consultahealth.com.au/sdk/consulta.js) and [its types](https://consultahealth.com.au/sdk/consulta.d.ts) - Questions: bookings@consultahealth.com.au