Urogram FHIR R4 API (1.7.1)

Integration guide and API reference for hospital EHR/EMR systems connecting to the Urogram FHIR R4 API.

Available Endpoints

Base URL

Getting a Test Environment

Validate your integration against the Test environment before you go near production. It is not self-service: we have to create a hospital tenant for you there and issue credentials scoped to it, so ask us first — see Support. Tell us roughly how many devices you want to see and we will seed the tenant accordingly.

Test credentials are separate from production credentials and are not interchangeable. Everything else is identical, so cutting over means changing the base URL and the client secret and nothing else.

Quickstart

Two calls. Substitute your credentials; the token is valid for 10 hours.

TOKEN=$(curl -sS -X POST https://app.htgmedical.com/oauth/v1/token/ \
  -d grant_type=client_credentials -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET -d scope=m2m.read | jq -r .access_token)

curl -sS -H "Authorization: Bearer $TOKEN" -H "Accept: application/fhir+json" \
  "https://app.htgmedical.com/fhir/R4/Observation/?code=9187-6&date=gt2026-03-15T00:00:00Z"

The response is a searchset Bundle. Filter entry by search.mode == "match" to skip the included Organization. total: 0 with no matching entries is a valid answer — see Troubleshooting.

Credentials

You will receive from HTG:

• client_id — Your application identifier
• client_secret — Your secret key (keep this secure!)

Step 1: Request an Access Token

POST /oauth/v1/token/ HTTP/1.1
Host: app.htgmedical.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=m2m.read

cURL example:

curl -X POST https://app.htgmedical.com/oauth/v1/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=m2m.read"

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "expires_in": 36000,
  "token_type": "Bearer",
  "scope": "m2m.read"
}

Step 2: Use the Access Token

Include the token in the Authorization header for all API requests:

GET /fhir/R4/Device/ HTTP/1.1
Host: app.htgmedical.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
Accept: application/fhir+json

Token Reuse

Tokens expire after 10 hours (expires_in: 36000 seconds). Cache the token and reuse it for every request; request a new one shortly before expiry, or once after a 401 (requirement 2 under Integration Requirements):

import requests
from datetime import datetime, timedelta

class UrogramClient:
    def __init__(self, client_id, client_secret, base_url):
        self.client_id = client_id
        self.client_secret = client_secret
        self.base_url = base_url
        self.token = None
        self.token_expires_at = None

    def get_token(self):
        # Refresh if token is missing or expires within 5 minutes
        if not self.token or datetime.now() >= self.token_expires_at - timedelta(minutes=5):
            response = requests.post(
                f"{self.base_url}/oauth/v1/token/",
                data={
                    "grant_type": "client_credentials",
                    "client_id": self.client_id,
                    "client_secret": self.client_secret,
                    "scope": "m2m.read"
                }
            )
            data = response.json()
            self.token = data["access_token"]
            self.token_expires_at = datetime.now() + timedelta(seconds=data["expires_in"])
        return self.token

    def get_devices(self):
        return requests.get(
            f"{self.base_url}/fhir/R4/Device/",
            headers={"Authorization": f"Bearer {self.get_token()}"}
        ).json()

Credentials and tokens

1. MUST keep the client_secret in a secret store, never in source control, logs or URLs. It grants read access to your hospital's data.
2. MUST cache the access token and reuse it for every request until shortly before expires_in elapses (for example, renew 5 minutes early). On a 401, request one new token and retry once. MUST NOT request a new token for every poll. Each token request creates a server-side token; tokens last 10 hours. See Authentication for a caching example.
3. MUST NOT retry a 403 in a loop. It means the token lacks the m2m.read scope or the application is not linked to a hospital, which only a configuration change fixes; contact us.

Errors, retries and staying alive

4. MUST treat network errors, timeouts, 429 and every 5xx as temporary: retry with exponential backoff and jitter (for example 30 s, 1 min, 2 min, 4 min, then every 10–15 min). When a response carries Retry-After, wait at least that long.
5. MUST NOT stop polling because of an error, however many in a row. Keep retrying until the service answers, then continue from your last successful cursor. During a past outage, an integration that gave up after a single 500 stopped receiving data entirely.
6. MUST advance the sync cursor only after a response has been received in full and stored. A failed poll then costs nothing: the next one fetches the same data.
7. MUST alert your own operations staff when no poll has succeeded for a set time (we suggest three polling intervals, for example 30 minutes). An empty response is a success. We cannot see that your side has stopped polling.
8. SHOULD log and alert on any other 4xx instead of retrying it unchanged. It points to a bug in the request or a configuration problem.

Synchronisation

9. MUST poll incrementally by server-update time, not by measurement time, every 5–15 minutes (see Data Synchronization). Devices that were offline upload old readings late, and a reading's validity can change after it was first sent; both appear only by server-update time.
10. SHOULD take the next cursor from the time the request was sent, minus an overlap of about a minute, rather than from when processing finished. Records updated while your poll runs, or hidden by clock differences, are then fetched again rather than missed; requirement 12 makes the repeats harmless.
11. SHOULD run the initial backfill by measurement time, at most 30 days back, in bounded chunks (day by day, or per ward or device), then switch to incremental polling. Responses are not paginated: one unbounded query returns everything at once.
12. MUST store records keyed by their stable identifier (see Data Synchronization) and replace the stored copy when a record arrives again, rather than adding a second one. Status changes and corrections arrive as the same record with new content.
13. SHOULD periodically (for example hourly) re-fetch the diuresis of a recent window by measurement time, such as the last 24 hours, and replace your stored diuresis for that window with the response. Invalidating a measurement replaces the diuresis records that used it with one recalculated record; incremental polling delivers that record but never reports a removal.

Validity

14. MUST check every measurement's validity status, and exclude invalid measurements from clinical calculations or show them distinctly (see Measurement Validity). Anomaly detection, device hardware checks and clinical staff all flag readings, and flagged readings are still returned.
15. MUST expect validity to change after a measurement was first delivered, and update the stored copy (requirement 12).

Diuresis

16. SHOULD use our pre-calculated diuresis rather than recomputing it from measurements. Our calculation applies the A-NA (Anomaly–Non Anomaly) rule during anomaly runs, which cannot be reproduced from the measurements alone; your figures would differ during those periods.
17. MUST NOT treat a diuresis value as a rate. It is the urine volume in mL accumulated over its interval; a rate needs the interval's length.

Devices and patients

18. MUST own the mapping from device to patient or bed. Urogram data is device-centric and carries no patient identity of its own. Key the mapping on the device serial number printed on the device label, and update it when a device moves, or new data keeps arriving under the old patient or bed. See Device-to-Patient Pairing.

Health monitoring

19. SHOULD monitor service health with the public readiness check GET https://www.app.htgmedical.com/web/health/ready/ (200 = ready, 503 = a backend dependency failed) together with the API-specific check under Health Monitoring. A healthy service does not prove your data is fresh, so requirement 7 still applies.

Rate limits

20. MUST stay within 100 requests per minute per source IP on the data endpoints, and on 429 wait for Retry-After (60 seconds). Monitors and pollers sharing an IP share the limit. Endpoint-specific details are under Rate Limits. The 5–15 minute polling interval sits far below the limit.

Versioning and support

21. SHOULD pin to the API's own version tag (fhir-v… or hl7v2-v…), not the application version, and read the Changelog before upgrading. We announce breaking changes before they ship.
22. SHOULD validate the integration against the Test environment before production, and contact us through Support about credentials, outages or unexpected data.

Clinical use

23. The data provided through this API is intended to support clinical decision-making but MUST NOT be the sole basis for clinical actions. Always correlate it with other clinical observations and exercise professional judgment.

Recommended Setup Steps

1. Get credentials — Receive client_id and client_secret from HTG
2. Obtain token — POST /oauth/v1/token/ with scope=m2m.read
3. Discover wards — GET /fhir/R4/Location/ to see available ward IDs and names
4. Check capabilities — GET /fhir/R4/metadata/ returns the CapabilityStatement listing the supported resources, search parameters and auth scheme (no auth required)
5. Fetch devices — GET /fhir/R4/Device/ with optional location ward filter
6. Pull observations — GET /fhir/R4/Observation/ with optional location, code, date, and _lastUpdated parameters
7. Set up incremental sync — Poll GET /fhir/R4/Observation/?_lastUpdated=gt{last_sync} every 5–15 minutes

Step 1: Discover Available Wards

GET /fhir/R4/Location/ HTTP/1.1
Authorization: Bearer {token}

Response:

{
  "hospital_id": "12345678-abcd-ef01-2345-6789abcdef01",
  "hospital_name": "General Hospital",
  "wards": [
    { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "ICU" },
    { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Cardiology" }
  ]
}

Response fields:

Only active wards are listed: a ward that has been deactivated disappears from this list. Device and Observation data already filtered by its UUID is unaffected.

/Location/ is a convenience endpoint, not a FHIR search. It returns the plain JSON object above rather than a Bundle of FHIR Location resources, which is why it is not declared in the CapabilityStatement. Use it to discover ward UUIDs for the location parameter; do not point a generic FHIR client at it.

Step 2: Filter by Ward

Pass the ward id as the location parameter:

GET /fhir/R4/Device/?location=a1b2c3d4-e5f6-7890-abcd-ef1234567890
GET /fhir/R4/Observation/?location=a1b2c3d4-e5f6-7890-abcd-ef1234567890&code=9187-6

The location parameter can be combined with all other query parameters (code, device, device:identifier, date, _lastUpdated).

Bundle Entries

The entry array contains:

1. Organization entry (always first) — an included reference to the HTG Medical organization that produced the data. Has search.mode: "include".
2. Resource entries — the actual Device or Observation resources. Each has search.mode: "match".

Each entry object contains:

When parsing results, filter entries by search.mode == "match" or by resource.resourceType to skip the Organization entry.

Example:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 2,
  "timestamp": "2026-03-20T12:00:00+00:00",
  "entry": [
    { "resource": { "resourceType": "Organization", ... }, "search": { "mode": "include" } },
    { "resource": { "resourceType": "Device", ... }, "search": { "mode": "match" } },
    { "resource": { "resourceType": "Device", ... }, "search": { "mode": "match" } }
  ]
}

Fetching a Single Observation

To retrieve a single observation, use its prefixed ID in the URL path:

GET /fhir/R4/Observation/m-550e8400-e29b-41d4-a716-446655440000/
GET /fhir/R4/Observation/d-e5f6g7h8-1234-5678-abcd-ef1234567890/

The ID must include the type prefix (m- for measurements, d- for diuresis). The response is a Bundle containing the single matching observation (or an empty bundle if not found).

Device Identifiers

Each device always has a device-id identifier, and may also have a serial-number:

The serial-number corresponds to the label physically printed on each device, making it easy to match API data with devices at the bedside. Check the identifier array length before accessing it.

Measurement Fields (LOINC 28009-9)

Both observation types expose whole numeric mL (for example, 98.5 becomes 99), rounded to nearest with ties away from zero. Measurement grams are subtracted before conversion and rounding; diuresis is rounded from its stored mL value. The FHIR Quantity remains a decimal with unchanged coding and units. Only response precision changes; stored values and internal calculations are unchanged. Sums of individually rounded observations can differ from a total rounded after summation. Clients must not apply the density conversion again. Historical records predating volume conversion require a deployment-specific audit; this release does not rewrite or silently convert them.

Diuresis Fields (LOINC 9187-6)

Diuresis records represent the change in urine volume between two consecutive valid measurements. They are calculated server-side and only include validated data.

Measurement Validity

The API returns all measurements, including those flagged as invalid (requirements 14–15). Invalid measurements have status: "entered-in-error" per the FHIR Observation status value set. Valid measurements have status: "final".

Diagnostic heartbeats remain available as measurement observations with status: "entered-in-error". Their note describes the measurement state at the time of the heartbeat, such as Inactive (Negative net weight, No clip detected). Ordinary rejected readings use Invalid and their available reasons. Notes follow the dashboard's clinical presentation: reasons are deduplicated and ordered, unknown codes appear as Unspecified reason, and admin-only forced inactivity details are omitted. The note is explanatory free text; use status to determine clinical validity. Failed measurement attempts are not observations. Legacy rejected heartbeat markers whose stored fields contain protocol flags instead of weights omit valueQuantity and include dataAbsentReason: error. Measurements without an exportable numeric volume always use entered-in-error, even when a historical row was not hidden.

The pre-calculated diuresis observations (LOINC 9187-6) are calculated from valid measurements only, so if you display those, as requirement 16 recommends, no further filtering is needed. When a measurement's status changes, its meta.lastUpdated changes too: _lastUpdated sync delivers it again under the same id, and you replace your stored copy (see Data Synchronization).

Understanding Timestamps

Each Observation has two important timestamps:

Server-update time (requirement 9) is meta.lastUpdated, queried with _lastUpdated. Use date only for the initial backfill:

# WRONG - misses late uploads from offline devices and status changes
url = f"/fhir/R4/Observation/?date=gt{last_sync_time}"

# CORRECT - catches every record the server added or changed since the cursor
url = f"/fhir/R4/Observation/?_lastUpdated=gt{last_sync_time}"

Recommended Sync Strategy

Initial Sync

1. Fetch all devices: GET /fhir/R4/Device/
2. Fetch recent observations by clinical date in bounded chunks (requirement 11), for example one day at a time: GET /fhir/R4/Observation/?date=gt{day_start}&date=lt{day_end}, optionally per location

Incremental Sync

Poll every 5–15 minutes:

GET /fhir/R4/Observation/?_lastUpdated=gt{last_sync_timestamp}

Identifying a Stored Observation

Key stored observations on id (m-{uuid} for a measurement, d-{uuid} for a diuresis), which is also identifier[0].value (requirement 12). A measurement keeps its id when its status changes.

A recalculated diuresis gets a new id, and the record it replaces stops being returned (requirement 13). To reconcile, query code=9187-6 with a date range and replace the stored diuresis whose effectivePeriod overlaps that range: date matches a diuresis by overlap (see Query Parameters Reference).

Example Sync Script (Python)

import requests
from datetime import datetime, timedelta, timezone

class UrogramSync:
    def __init__(self, client):
        self.client = client
        self.last_sync = None

    def sync_observations(self, store):
        url = f"{self.client.base_url}/fhir/R4/Observation/"
        # Cursor from when the request was sent, with a 1-minute overlap (requirement 10)
        poll_started = datetime.now(timezone.utc) - timedelta(minutes=1)

        params = {}
        if self.last_sync:
            # Use _lastUpdated for incremental sync to catch late-arriving data
            params["_lastUpdated"] = "gt" + self.last_sync.strftime("%Y-%m-%dT%H:%M:%SZ")

        response = requests.get(
            url,
            params=params,
            headers={"Authorization": f"Bearer {self.client.get_token()}"},
            timeout=60,
        )
        # On 429/5xx/timeout this raises: back off, retry with the same cursor,
        # and keep polling (requirements 4-6)
        response.raise_for_status()

        # Store (upsert by id) first; advance the cursor only once that succeeded.
        # Skip the included Organization entry: only "match" entries are Observations.
        entries = response.json().get("entry", [])
        store([e for e in entries if e.get("search", {}).get("mode") == "match"])
        self.last_sync = poll_started

Consuming Diuresis Data

Requirement 16: display the pre-calculated diuresis observations (LOINC 9187-6) rather than recomputing them. Each is a volume over its effectivePeriod (requirement 17).

GET /fhir/R4/Observation/?code=9187-6&_lastUpdated=gt{last_sync}

Calculating Diuresis from Raw Measurements

If you must calculate diuresis independently (e.g., for custom aggregation windows), you can derive it from the raw measurement observations (LOINC 28009-9). Your results will differ from ours during anomaly runs, where our calculation applies the A-NA rule (requirement 16).

Basic diuresis calculation rules:

1. Filter by status: Only use measurements with status: "final". Skip all "entered-in-error" measurements.
2. Sort by time: Order valid measurements by effectiveDateTime ascending.
3. Calculate deltas: For each consecutive pair of valid measurements from the same device, calculate the volume difference.
4. Time window: Only calculate deltas between measurements that are within 62 minutes of each other. Gaps larger than this indicate the container was likely emptied or replaced.
5. Positive deltas only: Only include positive volume changes (increasing urine volume). Negative changes indicate container emptying.
6. Group by device: Calculate diuresis per-device, not across devices.

Device-to-Patient Pairing

The FHIR API does not include patient references in observations (requirement 18). Your system should:

1. Fetch devices via GET /fhir/R4/Device/
2. Use the serial-number identifier (the physical label on the device, e.g., "D-1009") to match devices to patients in your EHR
3. All observations reference the device that produced them via the device field

Authentication Errors

Validation Errors

Validation errors return a FHIR OperationOutcome with HTTP 400 or 404:

A filter that is well-formed but matches nothing — an unknown device, or a serial number that does not exist — is not an error: it returns 200 with an empty Bundle (total: 0). The same applies to GET /Observation/{id}/ for an ID that is valid in form but not present in your hospital.

All validation errors are returned as FHIR OperationOutcome resources:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Invalid location parameter: not-a-uuid. Must be a valid UUID."
    }
  ]
}

Server Errors and Throttling

General service health

The readiness check GET https://www.app.htgmedical.com/web/health/ready/ covers the database connection, Redis, a Celery worker and the beat heartbeat. Public /health/ only checks nginx and can remain green when Django is unavailable.

Authenticated FHIR health

GET https://www.app.htgmedical.com/fhir/health/ uses the same bearer token, m2m.read scope and hospital link as your data requests. Staging uses https://www.staging.app.htgmedical.com/fhir/health/ with staging credentials. The path is outside /fhir/R4/ and accepts application/json.

curl --silent --show-error --fail-with-body --max-time 10 \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Accept: application/json' \
  'https://www.app.htgmedical.com/fhir/health/'

Example response:

{
  "status": "ok",
  "checks": {
    "database": {"status": "ok"},
    "device": {"status": "ok"},
    "measurement": {"status": "ok"},
    "diuresis": {"status": "skipped", "detail": "no records"}
  }
}

The endpoint performs real database queries and selects at most one record of each type from your hospital, ordered by primary key. It exercises the shared Device/Observation converters, Bundle serializer and FHIR JSON renderer. The records, their identifiers, counts and clinical values never appear in the response. No records are created or modified.

ok means that check completed successfully; down means it failed; skipped means it was not exercised. An empty hospital returns overall ok with skipped resource checks: that verifies database/access availability, not clinical serialization. Show skipped checks as incomplete coverage in the dashboard.

Poll every 30–60 seconds, use a 10-second timeout and alert after repeated failures. The limit is 100 GET requests/minute per source IP, shared by monitors using that IP for this endpoint. Authentication is checked each time; results are not cached. Responses include Cache-Control: no-store. Limits bound rows returned, not database work or request duration.

Celery and Redis health are not probed here, although the request rate limiter uses Redis. A Redis limiter failure returns 503, overall down, with all checks skipped and detail: "checks unavailable". A database outage during authentication or the initial database probe returns database down and resource checks skipped with detail: "database unavailable". A database error during a resource query marks database and that resource down and skips subsequent checks. Processing errors report detail: "check failed" without exception text.

Stronger external integration check

The dedicated check does not traverse the public Device/Observation routes or every search filter, and uses representative records rather than your current query. For stronger coverage, run a small real Observation request from the consumer's network, using its actual OAuth credentials.

1. Obtain a token through POST /oauth/v1/token/ with client credentials and scope=m2m.read, following the authentication instructions. Store credentials in your monitor's secret store. Reuse tokens until their expiry approaches and test token refresh as part of normal monitoring.
2. Query an existing observation belonging to your hospital. This API returns a Bundle, including for an observation ID; an absent ID returns an empty Bundle.
3. Check the response is a searchset Bundle and contains the expected matching Observation. Do not count an HTTP 200 or an included Organization as proof of successful observation retrieval. Keep clinical response bodies out of logs.

Example (Bash with jq; OBSERVATION_ID is a retained, known m-UUID or d-UUID):

set -o pipefail
curl --silent --show-error --fail --max-time 10 \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Accept: application/fhir+json' \
  "https://www.app.htgmedical.com/fhir/R4/Observation/$OBSERVATION_ID/" \
  | jq -e --arg id "$OBSERVATION_ID" \
      '.resourceType == "Bundle" and .type == "searchset" and
       any(.entry[]?; .search.mode == "match" and
           .resource.resourceType == "Observation" and .resource.id == $id)' \
  > /dev/null

Exit zero means this particular read worked. Choose a stable record retained by your integration; legitimate record removal makes this monitor fail and requires updating the reference. It does not check incoming data freshness.

GET /fhir/R4/metadata/ returns a predefined CapabilityStatement describing the API version, operations, search parameters and authentication. It proves metadata routing/reachability, but does not query the database or validate your token.

Freshness needs a separate check against expected device activity, ideally using server receipt/modification time (_lastUpdated) as well as clinical time. Agree thresholds per device/use case: an idle device is not automatically an outage, and a fresh received reading can have an older clinical timestamp.

Provider-operated external monitoring

The application provides two checks with separate execution paths:

• FHIR integration: an optional GitLab hosted-runner job runs every five minutes once provisioned and scheduled. It obtains a fresh OAuth client-credentials token and reads a fixed synthetic Observation, verifying identity, timestamp, final status, device, LOINC 28009-9, UCUM mL and volume. It reports to internal Sentry Cron Monitoring.
• Production TTI webhook health: a Sentry Uptime monitor calls TTI directly every minute for application hardwario-testing, webhook urogram-app. It alerts after one failed check and resolves after two successful checks. Paused, uplink-disabled, unhealthy, missing or unknown health fails the check, as do API authentication/network failures. Staging webhook urogram-staging is not monitored by this check.

The FHIR fixture uses a dedicated synthetic hospital, device and OAuth application. Operators must provision it, configure its protected GitLab schedule and Sentry routing, then prove error, missed-run and recovery notifications. A code deployment alone does not activate the FHIR monitor. The TTI monitor uses a dedicated read-only TTI application API key stored in Sentry; it needs no GitLab runner or TTI CI variables. Neither check submits measurements or changes webhook settings. No recurring synthetic-data pruning is needed.

A healthy TTI snapshot and a readable fixed Observation do not prove fresh end-to-end ingestion, payload decoding, sensor/radio transmission, ML inference, derived diuresis or WebSocket delivery. A through-TTI canary is a separate follow-up. Consumers should monitor their own credentials, hospital link, expected measurement freshness and receiving-system processing. Internal Sentry monitoring does not provide a public status dashboard.

I get an empty Bundle (total: 0)

That is a valid answer, not an error, and it is the normal steady state when polling with _lastUpdated. If you expected data:

A malformed date/_lastUpdated gives a 400 with an OperationOutcome, not an empty Bundle — so if you get total: 0 your parameters were accepted.

Not a cause: invalid measurements are still returned, with status: "entered-in-error". They are never silently dropped.

I get a 403 rather than data

Your token is valid but the OAuth2 application behind it is not linked to a hospital, or the m2m.read scope was not requested. Contact us to link it — see Support.

The response is much larger than expected

There is no pagination — see the note under Response Format. Bound broad queries with date and location, then use _lastUpdated for steady-state polling.