For clinic web developers
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.
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.
Send the key in the Authorization header on every call.
Authorization: Bearer mbk_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx| Step | Call | Returns |
|---|---|---|
| 1 Branches | GET /config | Branches taking bookings (id), verify methods, approval mode, days ahead |
| 2 Services | GET /services?branch={id} | [{ id, name, nameEn, … }] (display fields below) |
| 3 Providers | GET /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 Times | GET /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 Request | POST /requests | 201 + request status |
| 6 Follow up | webhook · 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.
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.
GET /slots?branch={id}&service={id}&staff={id|0}&month=2026-11{
"month": "2026-11",
"available": ["2026-11-02", "2026-11-03", "2026-11-05"]
}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.
| Field | In | Meaning |
|---|---|---|
clinic.nameEn · branches[].nameEn · addressEn | GET /config | English clinic name, branch name and address; null means use the original |
clinic.accent | GET /config | Booking page color "#rrggbb"; null means use themeColor |
clinic.coverUrl | GET /config | Cover image URL, 3:1 |
clinic.welcome · welcomeEn | GET /config | Welcome message |
clinic.notice · noticeEn | GET /config | Announcement; becomes null after the end date the clinic set |
clinic.cancelPolicy · cancelPolicyEn | GET /config | Cancellation policy; show it before the patient confirms |
branches[].photos | GET /config | Branch photo URLs, up to 5 (an empty array when none, never null) |
branches[].mapUrl | GET /config | The clinic's Google Maps link, or one built from coordinates; null when neither exists |
branches[].note · noteEn | GET /config | Directions and parking |
branches[].currency | GET /config | Currency for prices (ISO 3 letters, never null, default "THB") |
icon | GET /services | Material Symbols icon name (for example stethoscope) |
imageUrl | GET /services | Square service image URL; prefer it over icon |
description · descriptionEn | GET /services | Service description |
durationMinutes | GET /services | Approximate length (5–600 minutes), for display only; it does not change /slots |
price | GET /services | Starting price; null when the clinic hides prices; currency from branches[].currency |
prep · prepEn | GET /services | Preparation instructions (for example fasting) |
staff[].specialty · specialtyEn | GET /staff | Specialty |
staff[].languages | GET /staff | Spoken language codes such as ["th", "en"] (an empty array when unset) |
staff[].bio · bioEn | GET /staff | Short bio |
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.
| mode | Steps | Request |
|---|---|---|
doctor | Choose a provider (GET /staff), then a time (GET /slots). The default | The chosen staffId or 0, plus time |
slot | No doctor visit and no provider step. Pick a time from GET /slots (staff=0); each slot lasts slotMinutes and can take several people | staffId 0, plus time |
day | No 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 available | staffId 0, and time empty ("") or left out |
| Field | In | Meaning |
|---|---|---|
mode | GET /services | "doctor" | "slot" | "day"; treat a missing value as doctor |
window | GET /services | { from, to }, the service hours for slot/day ("HH:mm"); null means the branch opening hours |
slotMinutes | GET /services | Minutes per slot for slot mode; null means 30 |
day | GET /slots | Day mode only: { from, to } for that date, or null when the date is closed or full |
mode · dayFrom · dayTo | GET /requests/{ref} | The request's mode. Day requests add dayFrom/dayTo (the arrival window), and appointmentAt is that date at dayFrom |
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" }
}'{
"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 | Meaning |
|---|---|
pending | Waiting for the clinic (manual) or being confirmed (auto); the slot is held until holdUntil |
approved | On the calendar, with appointmentId and hn |
rejected | Declined by the clinic, with rejectReason |
expired | The hold ran out before approval; the slot is free again |
cancelled | Cancelled |
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.
| type | When |
|---|---|
request.created | A new request arrives (from the API or MORRU's hosted page) |
request.approved | Approved into an appointment |
request.rejected | Declined by the clinic |
request.expired | The hold ran out |
request.cancelled | Cancelled |
ping | The test button in HIS (data is null) |
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": ""
}
}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.
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
// $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
Failures return JSON { reason, message } (plus field when an input is wrong).
| HTTP | reason | What to do |
|---|---|---|
400 | invalid | Fix the input named in field |
400 | verify_expired | The OTP proof expired or was used; request a new code |
401 | unauthorized | Wrong or revoked key |
403 | server_only | Called from a browser; call from your server |
404 | booking_off | Web booking is not turned on (an unknown branch or service also returns 404) |
409 | taken | The time was just taken (or the slot or day is full); let the patient choose again |
400 · 409 | staff_service | The chosen provider no longer offers this service (or a staffId was sent for a slot/day service); let the patient choose a provider again |
409 | too_soon | Too soon for the clinic to approve |
429 | | Rate limited; wait and retry |
503 | unavailable | Retry with the same Idempotency-Key |
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