Server-side API

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
}
  • page is zero-based, default 0.
  • size defaults to 20 and goes up to 100. Asking for more is a 400, not a silent clamp, so a short page always means you reached the end.
  • page and size in 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

ThingShapeExample
Patient, prescription, document, locationInteger4821
AppointmentSCHEDULED:<integer> string"SCHEDULED:91234"
Practitioner / staff memberMDU_ + 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

KindFormatExample
Calendar dateYYYY-MM-DD2026-11-18
InstantISO-8601 with offset2026-11-18T10:30:00+05:30, 2026-11-18T05:00:00Z
TimezoneIANA nameAsia/Kolkata
  • Appointment times (fromDateTimeIso, toDateTimeIso) carry the clinic's offset, and appointmentDate is 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 a 400.

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_FIELD naming it. workspaceId is 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, with errors[] 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 Allowed with an Allow header when a documented path is called with a method it does not have, e.g. DELETE /v1/patients/4821.
  • 415 Unsupported Media Type when a body is sent with a Content-Type other than JSON. Any +json type is fine.
  • 406 Not Acceptable when Accept allows neither application/json nor application/pdf. Leave Accept unset if in doubt.
  • 201 Created on a new patient carries a Location header.
  • Responses over 1 KB are compressed with gzip or brotli when you send Accept-Encoding.

On this page