Morru
Home
Packages & Pricing
User Manual
FAQs
Contact
Login
For Individuals→
THAENG
˄ Scroll up
Scroll down ˅
Login||THAENG
Morru
Home
Packages & Pricing
Features
  • •All features
  • •Specialty modules
  • •Orthopedic Module
  • •Physical Therapy Module
  • •Dental Module
  • •Patient CRM via LINE
User Manual
FAQs
Contact
For Individuals →
Home›Booking API

For clinic web developers

Booking API: take appointments on your own website, straight into MORRU HIS

Build a booking page in your clinic's own design and send requests into the HIS request inbox. Services, providers, free times and approval rules are the same as MORRU's hosted booking page.

Download the OpenAPI spec ↓OpenAPI 3.1 file for Postman, Insomnia or client code generators
Plans
Starter and up
Auth
Secret key
Format
JSON · HTTPS
Updates
Webhooks

On this page

  1. Getting started
  2. Keys and security
  3. Booking flow
  4. Available days in a month
  5. Display fields
  6. Booking modes
  7. Create a request
  8. Status and cancelling
  9. Webhooks
  10. Verifying signatures
  11. Errors

Getting started

  • A Starter plan or higher, with web booking turned on for the branch in HIS › Settings › Branches › Booking page
  • Create an API key on the same page under "API for your clinic website". The key is shown once; store it on your web server.
  • Add a webhook URL to be told when a request is approved, declined, expires or is cancelled.

Services, providers, free times, manual or automatic approval and hold times all come from each branch's booking settings, so the API behaves exactly like MORRU's hosted page.

Keys and security

Send the key in the Authorization header on every call.

HTTP
Authorization: Bearer mbk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Call from your server only. Requests carrying an Origin header (from a browser) get 403. Never put the key in a web page or app.
  • A wrong or revoked key gets 401. Revoking in HIS takes effect immediately.
  • Rate limits per key: 300 reads/min and 60 writes/min. Over the limit returns 429.
  • Under PDPA your clinic is the data controller: collect the patient's consent on your site before sending a request. MORRU is the processor.

Booking flow

StepCallReturns
1 BranchesGET /configBranches taking bookings (id), verify methods, approval mode, days ahead
2 ServicesGET /services?branch={id}[{ id, name, nameEn, … }] (display fields below)
3 ProvidersGET /staff?branch={id}&service={id}{ allowAny, staff: [{ id, name, … }] }; allowAny means staffId 0 is allowed. Skip this step when the service mode is slot or day
4 TimesGET /slots?branch=&service=&staff=&date=YYYY-MM-DD{ date, times: ["09:00", …] }, only times that are free and early enough to approve. For a day-mode service, times is empty and day is { from, to }
5 RequestPOST /requests201 + request status
6 Follow upwebhook · GET /requests/{ref}Once approved: appointmentId and HN

All paths start with https://api2.morru.com/v1/booking. Appointment times are clinic local time (no time zone); other timestamps are UTC.

Available days in a month

Clinics can take bookings up to 365 days ahead (maxDaysAhead in GET /config). To show a calendar, send month=YYYY-MM instead of date to learn which days in that month still have room, then fetch the times for the day the patient picks with date as before.

HTTP
GET /slots?branch={id}&service={id}&staff={id|0}&month=2026-11
JSON
{
  "month": "2026-11",
  "available": ["2026-11-02", "2026-11-03", "2026-11-05"]
}
  • available lists only days inside the booking window (today to today + maxDaysAhead) that have at least one free time, in date order; an empty array when none.
  • Day-mode services: the days the patient can come (the days where GET /slots?date= returns a non-null day).
  • Send either date or month. Ask one month at a time and cache the result per month, branch, service and provider.

Display fields

What the clinic sets in HIS › Booking page and staff profiles, for showing on your own booking page. Every field may be null unless noted; when an …En field is empty, fall back to the Thai field.

FieldInMeaning
clinic.nameEn · branches[].nameEn · addressEnGET /configEnglish clinic name, branch name and address; null means use the original
clinic.accentGET /configBooking page color "#rrggbb"; null means use themeColor
clinic.coverUrlGET /configCover image URL, 3:1
clinic.welcome · welcomeEnGET /configWelcome message
clinic.notice · noticeEnGET /configAnnouncement; becomes null after the end date the clinic set
clinic.cancelPolicy · cancelPolicyEnGET /configCancellation policy; show it before the patient confirms
branches[].photosGET /configBranch photo URLs, up to 5 (an empty array when none, never null)
branches[].mapUrlGET /configThe clinic's Google Maps link, or one built from coordinates; null when neither exists
branches[].note · noteEnGET /configDirections and parking
branches[].currencyGET /configCurrency for prices (ISO 3 letters, never null, default "THB")
iconGET /servicesMaterial Symbols icon name (for example stethoscope)
imageUrlGET /servicesSquare service image URL; prefer it over icon
description · descriptionEnGET /servicesService description
durationMinutesGET /servicesApproximate length (5–600 minutes), for display only; it does not change /slots
priceGET /servicesStarting price; null when the clinic hides prices; currency from branches[].currency
prep · prepEnGET /servicesPreparation instructions (for example fasting)
staff[].specialty · specialtyEnGET /staffSpecialty
staff[].languagesGET /staffSpoken language codes such as ["th", "en"] (an empty array when unset)
staff[].bio · bioEnGET /staffShort bio

Booking modes

Clinics set a booking mode per service in HIS › Booking page. Every service in GET /services has a mode that tells your page what to ask for.

modeStepsRequest
doctorChoose a provider (GET /staff), then a time (GET /slots). The defaultThe chosen staffId or 0, plus time
slotNo doctor visit and no provider step. Pick a time from GET /slots (staff=0); each slot lasts slotMinutes and can take several peoplestaffId 0, plus time
dayNo appointment time: the patient picks a day only. GET /slots (staff=0) returns day: { from, to }, the window to arrive in; day is null when that date is not availablestaffId 0, and time empty ("") or left out
FieldInMeaning
modeGET /services"doctor" | "slot" | "day"; treat a missing value as doctor
windowGET /services{ from, to }, the service hours for slot/day ("HH:mm"); null means the branch opening hours
slotMinutesGET /servicesMinutes per slot for slot mode; null means 30
dayGET /slotsDay mode only: { from, to } for that date, or null when the date is closed or full
mode · dayFrom · dayToGET /requests/{ref}The request's mode. Day requests add dayFrom/dayTo (the arrival window), and appointmentAt is that date at dayFrom
  • Services merged across branches (GET /services without branch) carry the first branch's mode. Modes are set per branch, so once a branch is chosen, read the mode from GET /services?branch={id}.
  • Doctor-mode services list only the providers the clinic allows for that service. Sending a staffId who does not offer it is refused with reason staff_service.

Create a request

Terminal · curl
curl -X POST https://api2.morru.com/v1/booking/requests \
  -H "Authorization: Bearer $MORRU_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "branch": "a8eqdoh0gggp",
    "serviceId": 65,
    "staffId": 0,
    "date": "2026-10-24",
    "time": "10:00",
    "firstName": "สมใจ",
    "lastName": "ใจดี",
    "phone": "0812345678",
    "email": "somjai@example.com",
    "note": "ปวดหลัง 2 สัปดาห์",
    "consent": true,
    "externalRef": "WEB-1001",
    "verify": { "method": "clinic" }
  }'
  • verify.method = "clinic": your site has already verified the patient (for example a logged-in member). The phone you send is recorded as verified.
  • Or use MORRU's OTP: POST /otp { branch, channel: "email"|"sms", target } → the patient receives a 6-digit code → POST /otp/verify { branch, channel, target, code } returns a proof → send verify { method, target, proof } within 30 minutes
  • consent must be true. externalRef is your own reference (up to 100 chars) and comes back in status and webhooks.
  • Idempotency-Key (8–64 chars A-Z a-z 0-9 _ . : -): retrying with the same key returns 200 and the original request instead of a duplicate.
201 response, same shape as GET /requests/{ref}
JSON
{
  "ref": "4pomwjm1iqh4",
  "externalRef": "WEB-1001",
  "source": "api",
  "status": "pending",
  "approveMode": "manual",
  "branch": { "id": "a8eqdoh0gggp", "name": "สาขาหลัก" },
  "service": { "id": 65, "name": "นัดมาพบแพทย์ครั้งแรก", "nameEn": "First visit" },
  "staff": null,
  "appointmentAt": "2026-10-24T10:00",
  "durationMinutes": 15,
  "mode": "doctor",
  "patient": {
    "firstName": "สมใจ", "lastName": "ใจดี", "phone": "0812345678",
    "email": "somjai@example.com", "note": "ปวดหลัง 2 สัปดาห์", "verifiedBy": "clinic"
  },
  "holdUntil": "2026-10-22T02:05:47Z",
  "createdAt": "2026-10-21T14:05:47Z",
  "decidedAt": "",
  "appointmentId": null,
  "hn": "",
  "rejectReason": ""
}

Status and cancelling

statusMeaning
pendingWaiting for the clinic (manual) or being confirmed (auto); the slot is held until holdUntil
approvedOn the calendar, with appointmentId and hn
rejectedDeclined by the clinic, with rejectReason
expiredThe hold ran out before approval; the slot is free again
cancelledCancelled

POST /requests/{ref}/cancel cancels for the patient. Pending requests are cancelled at once. Approved appointments follow the same rules as LINE self-cancel (unpaid, not checked in, and early enough for the branch setting); otherwise you get result: "asked", meaning the clinic is asked to call the patient and the appointment stays.

Webhooks

typeWhen
request.createdA new request arrives (from the API or MORRU's hosted page)
request.approvedApproved into an appointment
request.rejectedDeclined by the clinic
request.expiredThe hold ran out
request.cancelledCancelled
pingThe test button in HIS (data is null)
HTTP
POST /hooks/morru HTTP/1.1
Content-Type: application/json
User-Agent: MORRU-Webhooks/1.0
Morru-Event-Id: evt_dba40d57c29e42228edd
Morru-Signature: t=1761055547,v1=5f0c…

{
  "id": "evt_dba40d57c29e42228edd",
  "type": "request.approved",
  "createdAt": "2026-10-21T14:10:02Z",
  "data": {
    "ref": "4pomwjm1iqh4",
    "externalRef": "WEB-1001",
    "source": "api",
    "status": "approved",
    "branch": "a8eqdoh0gggp",
    "appointmentAt": "2026-10-24T10:00",
    "appointmentId": 48213,
    "hn": "SKV2600123",
    "rejectReason": ""
  }
}
  • Reply 2xx within 10 seconds and process afterwards. Otherwise we retry after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, then give up.
  • You may receive an event twice; dedupe on id (Morru-Event-Id). Delivery order is not guaranteed; when in doubt fetch GET /requests/{ref}.
  • The URL must be https on port 443 on a public domain. Redirects are not followed.
  • data has no patient name or contact details; get them from GET /requests/{ref}.

Verifying signatures

Every webhook has Morru-Signature: t={unix time},v1={HMAC-SHA256 of "t.body" with your secret}. Get the secret (whsec_…) from the API card in HIS. Compute it over the raw body before parsing JSON, and reject a t more than 5 minutes off.

Node.js
import crypto from "node:crypto";

// rawBody = ตัว body ดิบ (string) ก่อน JSON.parse · secret = whsec_… จาก HIS
export function verifyMorru(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!parts.t || !parts.v1 || age > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
PHP
<?php
// $raw = file_get_contents('php://input') · $secret = whsec_… จาก HIS
function verify_morru(string $raw, string $header, string $secret): bool {
    parse_str(str_replace(',', '&', $header), $p);
    if (empty($p['t']) || empty($p['v1']) || abs(time() - (int)$p['t']) > 300) return false;
    $expected = hash_hmac('sha256', $p['t'] . '.' . $raw, $secret);
    return hash_equals($expected, $p['v1']);
}

Test vector: secret whsec_test, t 1700000000, body {"a":1} → t=1700000000,v1=38877139021993b830af32feea6e18a8da83eb2f6e49ee50bd9e4cf4ca4d3789

Errors

Failures return JSON { reason, message } (plus field when an input is wrong).

HTTPreasonWhat to do
400invalidFix the input named in field
400verify_expiredThe OTP proof expired or was used; request a new code
401unauthorizedWrong or revoked key
403server_onlyCalled from a browser; call from your server
404booking_offWeb booking is not turned on (an unknown branch or service also returns 404)
409takenThe time was just taken (or the slot or day is full); let the patient choose again
400 · 409staff_serviceThe chosen provider no longer offers this service (or a staffId was sent for a slot/day service); let the patient choose a provider again
409too_soonToo soon for the clinic to approve
429Rate limited; wait and retry
503unavailableRetry with the same Idempotency-Key

No developer?

Use MORRU's hosted booking page instead: share a link or QR code, embed it, or add a floating button. No code needed.

Hosted booking page guide →
  • •Home
  • •Packages & Pricing
  • •Features
  • •User Manual
  • •FAQs
  • •Contact
  • •Terms of Service
  • •Privacy Policy
  • •Security & PDPA
  • •Help centre
Morru

Crazy Code Co., Ltd.

300/45 Soi Lat Phrao 84 (Sangkhom Songkhro Tai 1)

Wang Thonglang, Bangkok 10310

Morru

Crazy Code Co., Ltd.

300/45 Soi Lat Phrao 84 (Sangkhom Songkhro Tai 1)

Wang Thonglang, Bangkok 10310

Home
Packages & Pricing
Features
User Manual
FAQs
Contact

2026 © All Rights Reserved

Terms of ServicePrivacy PolicySecurity & PDPAHelp centre