Conventions
The rules every Developer API route shares, covering paging, ids, dates, money, nulls and strict parameters.
These hold on every route, so each endpoint page can skip them.
Paging
Every list comes back in one envelope:
{
"content": [],
"page": 0,
"size": 20,
"totalElements": 0,
"totalPages": 0
}pageis zero-based, default0.sizedefaults to20and goes up to100. Asking for more is a400, not a silent clamp, so a short page always means you reached the end.pageandsizein the response echo what you asked for.
Vitals is the one exception: it
returns a bare array bounded by limit, because a vitals series is read whole.
Medical history and the
single-record reads return one object.
Ids
| Thing | Shape | Example |
|---|---|---|
| Patient, prescription, document, location | Integer | 4821 |
| Appointment | SCHEDULED:<integer> string | "SCHEDULED:91234" |
| Practitioner / staff member | MDU_ + 12 of [A-Z0-9] string | "MDU_A1B2C3D4E5F6" |
Appointment references carry their system as a prefix. system is always
SCHEDULED today. The prefix stays so the refs you store keep one spelling. A
bare number is accepted wherever a ref is, and means SCHEDULED. The prefix is
case-insensitive. Any other prefix is a 400.
Practitioners are named by their public staff id, in both directions.
practitioner.id on an appointment, visit or prescription, and id on
GET /v1/doctors, are the same MDU_…
string. ?doctorId=, the search's doctorIds and the X-Acting-User-Id header
take that value and nothing else. Internal Medos user ids are not part of the API
at all. An MDU_… id this workspace does not know is a 400 naming the field,
not an empty result.
A practitioner reference with no person behind it has id and name both
null. You will never get a name without an id.
Nulls
Every field in a response is always present. A value Medos does not hold is
null, never omitted, so your parser can rely on the shape. Lists are [],
never null.
Dates and times
| Kind | Format | Example |
|---|---|---|
| Calendar date | YYYY-MM-DD | 2026-11-18 |
| Instant | ISO-8601 with offset | 2026-11-18T10:30:00+05:30, 2026-11-18T05:00:00Z |
| Timezone | IANA name | Asia/Kolkata |
- Appointment times (
fromDateTimeIso,toDateTimeIso) carry the clinic's offset, andappointmentDateis the date in the clinic's timezone. - Date filters (
fromDate,toDate) are inclusive calendar dates. On appointment search they are read as the location's days. - An instant you send (
updatedSince) must include an offset. Without one it cannot say which instant it means, so it is a400.
Money
Amounts are decimal strings: "amount": "800", "1234.56". They are never JSON
numbers, because most JSON parsers turn a number into a binary float, and money you
reconcile must not pass through one. Parse it with a decimal type. currency beside
it names the currency, e.g. INR.
Phone numbers
A patient carries the split pair Medos stores (countryCode: "+91",
phoneNumber: "9811100001") and the joined phoneNumberE164:
"+919811100001". The joined form is null unless the pair makes a valid E.164
number, so a number that is present there is safe to dial.
Parameters are strict
- A query parameter a route does not list is a
400 UNKNOWN_FIELDnaming it.workspaceIdis never accepted: the workspace is always your key's. - The search body is strict in the same way. The upsert body accepts the documented patient fields.
- A malformed value is a
400 INVALID_PARAMETER, witherrors[]naming each field.
A parameter that was silently ignored would look like a filter that works, so the API never ignores one.
HTTP behaviour
405 Method Not Allowedwith anAllowheader when a documented path is called with a method it does not have, e.g.DELETE /v1/patients/4821.415 Unsupported Media Typewhen a body is sent with aContent-Typeother than JSON. Any+jsontype is fine.406 Not AcceptablewhenAcceptallows neitherapplication/jsonnorapplication/pdf. LeaveAcceptunset if in doubt.201 Createdon a new patient carries aLocationheader.- Responses over 1 KB are compressed with gzip or brotli when you send
Accept-Encoding.