List staff at a clinic location

GET /v1/users

Lists the staff attached to one location — practitioners, receptionists, administrators. Use it to mirror the clinic's roster into your own system, or to find the roleId and user ids you need elsewhere.

Query parameters

Name	Type	Required	Description
`addressId`	number	Yes	The clinic location. Omitting it is a `400` upstream, despite reading as optional.
`roleId`	number	No	Narrow to one role.
`page`	number	No	Zero-based. Defaults to `0`.
`size`	number	No	Defaults to `10`.

Try it

GET/v1/users

API key*

Sent as x-api-key. Shared by every Try block on this page.

Query

Address IDA clinic location, from GET /v1/addresses.Role IDPageZero-based.Page size

Request

GET /v1/users?page=0&size=20

to https://api.medos.one

Use a dedicated test key, and put your browser's address on its allowlist

A Developer API key authenticates on its own, so it only works from the addresses registered against it — and this page calls from your browser, not your servers. Unless your own public address is on the list you get a 403 naming it, which is the allowlist doing its job. Your browser may also reach us over IPv6 even when your server does not, so the address in the error is often not the one you expected. The key here is kept in memory only and never written to storage, but create a test key for it and deactivate that key when you are done.

Request

curl -sG "https://api.medos.one/v1/users" \
  -H "x-api-key: $MEDOS_API_KEY" \
  --data-urlencode "addressId=1" \
  --data-urlencode "page=0" \
  --data-urlencode "size=25"

Response

{
  "count": 14,
  "list": [
    {
      "id": 4,
      "name": "Dr. Meera Rao",
      "prefix": "Dr.",
      "status": "ACTIVE",
      "email": "meera@clinic.example.com",
      "countryCode": "+91",
      "phoneNumber": "9812345678",
      "specialization": "Physiotherapy",
      "profilePicUrl": "https://…/meera.jpg",
      "roleNames": ["DOCTOR"],
      "roles": [{ "name": "DOCTOR", "displayName": "Doctor" }],
      "appointmentSystemType": "SCHEDULED",
      "isVerified": true,
      "lastActive": "2026-09-10T18:22:04"
    }
  ],
  "extras": {
    "configuredRoles": [
      { "name": "DOCTOR", "displayName": "Doctor" },
      { "name": "RECEPTIONIST", "displayName": "Receptionist" }
    ]
  }
}

Field	Meaning
`count`	Total staff matching the filter, for paging. `list` holds one page.
`list[].id`	The user id. For a practitioner this is the same value as `doctorId` on the booking routes.
`list[].status`	Active, inactive, invited. Inactive staff still appear.
`list[].appointmentSystemType`	`SCHEDULED` or `QMS` for a practitioner — which booking flow they run.
`list[].roles[]` / `roleNames`	What they are allowed to do in Medos.
`extras.configuredRoles`	The roles this workspace has, by name.

Role names, not role ids

configuredRoles gives names and display names — it does not give the numeric roleId that the ?roleId= filter and creating a staff user take. Read those from the dashboard, under Workspace Settings → Roles.

Common failures

Status	Cause
`400`	`addressId` missing.

List staff

Query parameters

Try it

Request

Response

Common failures

On this page