Urogram HL7v2 API (1.4.1)

Integration guide and API reference for hospital CIS/EMR systems connecting to the Urogram HL7v2 API for real-time urine monitoring data.

Transport: Pull over HTTP Today, MLLP Push on Request

This API is pull-based: your system authenticates with OAuth2 and polls the ORU endpoints over HTTPS, and Urogram returns the ORU^R01 message as an ER7 payload in the HTTP response body. There is no listener to configure on your side, and no message is sent to you unsolicited. See Recommended Polling Strategy for the polling pattern we recommend.

Traditional IHE PCD-01 is push-based — a Device Observation Reporter opens an MLLP connection to the consumer's listener (Mirth Connect / Open Integration Engine, Rhapsody, or similar) and sends each ORU^R01 with ACK handling.

Capability on request: Push delivery of ORU^R01 over MLLP is not part of the product today — the endpoints described in this document are the whole of the shipped HL7v2 interface. We can implement MLLP push against your listener if your integration requires it. It is a scoped engagement rather than a configuration switch (TCP connection management, retry/backoff, ACK^R01 parsing, and per-hospital endpoint configuration), so please raise it with us early — see Support — and we will confirm feasibility and timeline before you commit to a design.

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 — endpoints, message formats, OAuth2 flow — is identical, so the only thing that should change when you cut over is the base URL and the client secret.

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 /hl7v2/v1/generic/ORU/?date_from=2026-01-01T00:00:00Z&date_to=2026-01-02T00:00:00Z HTTP/1.1
Host: app.htgmedical.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...

Token Reuse

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

import time
import requests

BASE_URL = "https://app.htgmedical.com"

class UrogramHL7Client:
    def __init__(self, client_id, client_secret):
        self.client_id = client_id
        self.client_secret = client_secret
        self.token = None
        self.token_expires_at = 0.0

    def _fetch_token(self):
        response = requests.post(
            f"{BASE_URL}/oauth/v1/token/",
            data={
                "grant_type": "client_credentials",
                "client_id": self.client_id,
                "client_secret": self.client_secret,
                "scope": "m2m.read",
            },
            timeout=30,
        )
        response.raise_for_status()
        data = response.json()
        self.token = data["access_token"]
        self.token_expires_at = time.monotonic() + data["expires_in"]

    def get_oru(self, profile, params):
        # Reuse the cached token; renew it 5 minutes before it expires
        if not self.token or time.monotonic() >= self.token_expires_at - 300:
            self._fetch_token()
        url = f"{BASE_URL}/hl7v2/v1/{profile}/ORU/"
        response = requests.get(
            url, params=params, headers={"Authorization": f"Bearer {self.token}"}, timeout=60
        )
        if response.status_code == 401:  # revoked or expired early: renew once, retry once
            self._fetch_token()
            response = requests.get(
                url, params=params, headers={"Authorization": f"Bearer {self.token}"}, timeout=60
            )
        response.raise_for_status()  # 429/5xx: back off and retry, see requirements 4-6
        return response.text

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.

Message Structure

A single message covers every device in the result set.

MSH  (v2.6, ORU^R01^ORU_R01, IHE OID in MSH-21)
PID  (patient_id param or "UNKNOWN" placeholder; PID-5 = unknown-name form)
PV1  (patient class "U")
[Per device, volume measurements]:
  OBR  (OBR-4 = MDC_VOL_URINE_COL)
  OBX*  (measurements: MDC_VOL_URINE_COL, device serial in OBX-18)
[Per device, diuresis]:
  OBR  (OBR-4 = MDC_VOL_URINE_BAL_PD)
  OBX*  (diuresis: MDC_VOL_URINE_BAL_PD, device serial in OBX-18)

Note on segment grouping: Volume and diuresis observations are not mixed inside one OBR group. All volume groups (one OBR per device) are emitted first, followed by all diuresis groups (again one OBR per device). OBR-1 and OBX-1 set IDs increment continuously across the whole message — OBX-1 does not restart at 1 inside each OBR group.

Supported Observations

MDC codes are full 32-bit context-free codes — (partition << 16) | term, with metrics in partition 2 and units in partition 4 — and the OBX-3/OBX-6 coding-system component is the HL7 v2 designator MDC. (urn:iso:std:iso:11073:10101 is the FHIR system URI for the same code system; it is not valid inside a v2 message.) Every code above was verified against the IEEE 11073-10101 code system.

Both observations are volumes in mL. A diuresis record is the urine volume accumulated between two consecutive valid measurements, so it is reported as a volume over its stored interval, not as a flow rate. OBX-14 carries the interval start only; this profile does not expose the interval end or duration. Do not infer mL/h from this timestamp alone. Obtain the full interval through FHIR or REST.

Example Message

One device (serial number 908W) with one volume measurement and one diuresis record:

MSH|^~\&|UROGRAM|Example Hospital|||20260315143000+0000||ORU^R01^ORU_R01|a1b2c3d4e5f6a7b8c9d0|P|2.6|||||||||IHE_PCD_001^IHE PCD^1.3.6.1.4.1.19376.1.6.1.1.1^ISO
PID|||UNKNOWN^^^UROGRAM||^^^^^^U||||||||||||||||||||||||||Y
PV1||U
OBR|1|||157744^MDC_VOL_URINE_COL^MDC
OBX|1|NM|157744^MDC_VOL_URINE_COL^MDC||150|263762^MDC_DIM_MILLI_L^MDC|||||F|||20260315143000+0000||||908W
OBR|2|||157732^MDC_VOL_URINE_BAL_PD^MDC
OBX|2|NM|157732^MDC_VOL_URINE_BAL_PD^MDC||63|263762^MDC_DIM_MILLI_L^MDC|||||F|||20260315133000+0000||||908W

Notes on the segments above:

• OBX-18 (Equipment Instance Identifier) carries the device serial number.
• OBR-4 (Universal Service Identifier) repeats the group's OBX-3 code, so an OBR group is self-describing.
• PID-5 uses the HL7 "no name available" form — empty name components with name type code U (unspecified). PID-31 is Y when no patient_id was supplied, so you can distinguish "identity not known" from "identity not sent".
• MSH-15/MSH-16 (accept/application acknowledgement) and MSH-18 (character set) are not populated on this profile; the message is UTF-8 encoded.

One Message Per Device

Consuming systems route on PV1-3 (Assigned Patient Location), which carries the Urogram device serial number. A message therefore describes exactly one device.

A response covering N devices contains N ORU^R01 messages, concatenated in the response body. Each message begins with its own MSH segment, so consumers split the body on MSH| — the same framing integration engines (Mirth Connect / Open Integration Engine, Rhapsody) already apply to an HL7 batch.

This assumes a device stays at one bed. PV1-3 identifies the device, and your CIS maps that string to a bed. If a Urogram is physically moved to another bed, the mapping must be updated on your side — otherwise data continues to land at the old location. Request a single device per call with device_serial_number if you prefer to manage the mapping request-side.

Message Structure

Per device, one message:

MSH  (v2.3, MSH-15=AL, MSH-16=NE)
PID  (no patient identity — PID-5 uses the "unknown name" form)
PV1  (patient class "I", PV1-3 = device serial number → bed location)
[Volume measurements]:
  OBR  (OBR-4 = "UrineVolume", OBR-7 = timestamp, OBR-10 = device serial number)
  OBX*  (measurements: "UrineVolume")
[Diuresis]:
  OBR  (OBR-4 = "UrineOutput", OBR-7 = timestamp, OBR-10 = device serial number)
  OBX*  (diuresis: "UrineOutput")

Note on segment grouping: volume and diuresis observations occupy separate OBR groups within the device's message — volume first, then diuresis. OBX-1 set IDs increment across the message rather than restarting inside each OBR group.

Note on OBR-10: OBR-10 also carries the device serial number, and remains populated for consumers that read it. PV1-3 is the routing key.

Supported Observations

Both are volumes in mL. UrineOutput is the volume accumulated between two consecutive valid measurements, not a rate. OBX-14 carries the interval start only; this profile does not expose the end or duration. Obtain the full interval through FHIR or REST before calculating mL/h.

The existing Generic profile leaves OBX-6 empty; its numeric unit is mL by this contract. Adding explicit units requires receiver compatibility testing and an opt-in/versioned profile. Both profiles expose urine volume OBX-5 values as whole mL without a decimal suffix, rounded to nearest with ties away from zero. OBX-2 remains NM; codes and units remain unchanged. Measurement grams are subtracted before conversion using 1.015 g/mL and then rounded; diuresis is rounded from the stored mL value without converting again. Stored values and internal calculations do not change. Summing rounded observations can differ from rounding their unrounded total. Historical diuresis records require a deployment-specific unit audit; this release does not rewrite them or apply another conversion on export.

Example Message

Two devices (908W with a volume measurement and a diuresis record, 95CK with a volume measurement only) — so the response body holds two messages:

MSH|^~\&|UROGRAM|Example Hospital|||20260315143000+0000||ORU^R01|a1b2c3d4e5f6a7b8c9d0|P|2.3|||AL|NE
PID|||UNKNOWN^^^UROGRAM||^^^^^^U
PV1||I|908W
OBR|1|||UrineVolume^UrineVolume^UROGRAM|||20260315143000.000+0000|||908W|||||||||||||||||^^^^^R
OBX|1|NM|UrineVolume^UrineVolume^UROGRAM||150||||||F|||20260315143000+0000
OBR|2|||UrineOutput^UrineOutput^UROGRAM|||20260315133000.000+0000|||908W|||||||||||||||||^^^^^R
OBX|2|NM|UrineOutput^UrineOutput^UROGRAM||63||||||F|||20260315133000+0000
MSH|^~\&|UROGRAM|Example Hospital|||20260315143000+0000||ORU^R01|b2c3d4e5f6a7b8c9d0e1|P|2.3|||AL|NE
PID|||UNKNOWN^^^UROGRAM||^^^^^^U
PV1||I|95CK
OBR|1|||UrineVolume^UrineVolume^UROGRAM|||20260315143000.000+0000|||95CK|||||||||||||||||^^^^^R
OBX|1|NM|UrineVolume^UrineVolume^UROGRAM||197||||||F|||20260315143000+0000

Notes on the segments above:

• OBX-18 is not populated on this profile: the Equipment Instance Identifier field was introduced in HL7 v2.5, so on v2.3 the device is identified by PV1-3 and OBR-10.
• OBR-27 (Quantity/Timing) carries the minimal routine-priority value ^^^^^R. It is a required field up to v2.3; it is absent from the v2.6 PCD-01 profile, where timing moved to the TQ1 segment.
• PID-31 is not set here — the field was introduced in HL7 v2.4.

Timestamps

All emitted timestamps are UTC and carry an explicit +0000 offset, so no timezone has to be inferred:

Convert to your local zone on receipt. Note that Czech local time is UTC+1 in winter and UTC+2 under daylight saving, so a fixed one-hour adjustment is not correct year-round — use the offset.

OBX-11 Status Mapping

Measurement Validity

The API returns all measurements, including those flagged as invalid (requirements 14–15). An invalid measurement has OBX-11 = "X" (Cannot obtain), mapped from the internal entered-in-error status; any other OBX-11 value is valid.

Hardware-invalid readings and inactive heartbeats are included with OBX-11 X. Both profiles can emit one optional NTE immediately after a measurement's OBX, with the same English clinical label used by the dashboard and FHIR: Inactive (No clip detected), Invalid (Tilt exceeds the reading limit), Manually hidden, or Flagged as anomaly. The grammar is OBX → optional NTE for each measurement; valid measurements and calculated diuresis do not receive diagnostic NTE segments.

NTE-1 is 1 within each observation, NTE-2 is O (other source), and NTE-3 contains the label. Reasons are ordered and deduplicated, unknown codes appear as Unspecified reason, and admin-only forced inactivity details are omitted. An Inactive note describes measurement mode at the heartbeat time while the device is communicating. Failed measurement attempts are not observations. Legacy heartbeat markers contain protocol flags instead of weights, so their OBX-5 is empty and OBX-11 is X.

OBX|1|NM|UrineVolume^UrineVolume^UROGRAM||0||||||X|||20260315143000+0000
NTE|1|O|Inactive (No clip detected)

The diuresis observations (MDC_VOL_URINE_BAL_PD / UrineOutput) are calculated from valid measurements only, so if you display those, as requirement 16 recommends, no further filtering is needed. A measurement that becomes invalid is delivered again by updated_since with OBX-11 = X; update the stored observation by the key described under Data Synchronization.

Step 1: Discover Available Wards

GET /hl7v2/v1/wards/ HTTP/1.1
Authorization: Bearer {token}

Response:

{
  "hospital_id": "12345678-abcd-ef01-2345-6789abcdef01",
  "hospital_name": "General Hospital",
  "wards": [
    { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "ICU Ward A" },
    { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "General Ward B" }
  ]
}

Step 2: Filter by Ward

Pass the ward id as the ward_id parameter on any ORU endpoint:

GET /hl7v2/v1/pcd01/ORU/?date_from=2026-03-01T00:00:00Z&date_to=2026-03-02T00:00:00Z&ward_id=550e8400-e29b-41d4-a716-446655440000
GET /hl7v2/v1/generic/ORU/?date_from=2026-03-01T00:00:00Z&date_to=2026-03-02T00:00:00Z&ward_id=550e8400-e29b-41d4-a716-446655440000

The ward_id parameter can be combined with all other query parameters (device_serial_number, device_id, include_diuresis, updated_since).

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 /hl7v2/v1/wards/ to see available ward IDs and names
4. Check capabilities — GET /hl7v2/v1/{profile}/metadata/ to verify supported observations
5. Pull data — GET /hl7v2/v1/{profile}/ORU/?date_from=...&date_to=... with optional ward_id, device_serial_number, device_id, include_diuresis, and updated_since parameters

Data Synchronization

Understanding Timestamps

Each observation has two important timestamps:

Server-update time (requirement 9) is the updated_since parameter. It is not emitted in the message, so keep your own cursor. A poll on date_from alone misses readings that an offline device uploads late with an old OBX-14, and misses validity changes.

Recommended Polling Strategy

1. poll_started = now - 1 minute            (requirement 10: overlap)
2. GET /hl7v2/v1/{profile}/ORU/?date_from=<30 days ago>&date_to=<now>
       &updated_since=<cursor>
3. On timeout, 429 or 5xx: back off and retry from step 1 with the
   SAME cursor; never give up (requirements 4-6)
4. Split the body on MSH|, upsert each OBX by its key (below)
5. Only after step 4 succeeded: cursor = poll_started
6. Wait 5-15 minutes, repeat

Keep date_from wide (30 days) during steady-state polling: updated_since narrows the date-bounded result, so a late upload is only returned if its OBX-14 is inside the window.

Identifying a Stored Observation

HL7v2 messages carry no per-observation identifier: MSH-10 is new on every response, and OBR-1/OBX-1 are positions within the message. Key each stored observation (requirement 12) on device, observation type and OBX-14:

OBX-14 is the measurement time for a volume and the period start for a diuresis. A re-delivered measurement (for example newly OBX-11 = X) has the same key, so replace the stored copy. This is the best key the messages allow, not a guaranteed one: OBX-14 has whole-second precision, so two readings from one device within the same second would share it.

When a measurement is invalidated, the diuresis records before and after it are usually removed and, where the valid neighbours allow, replaced by one record spanning them. That record starts where the first removed one did, so it overwrites it under this key; a removed record that nothing replaces is never re-sent and stays in your store until you reconcile. For the diuresis reconciliation in requirement 13, re-query with date_from/date_to around the recent window and replace the stored diuresis whose period lies wholly inside that window: only those are returned (see the note under Query Parameters).

Data Volumes and Sizing

Use this to size your first sync and your storage. There is no pagination — a query returns every matching observation in one response — so the numbers matter.

Observation count per device per day:

measurements = 86400 / measurement_interval_seconds
observations = measurements x 2   (roughly, when include_diuresis=true:
                                   one diuresis per consecutive valid pair)

The measurement interval is configured per device, so ask us for the value used in your deployment rather than assuming one. Diuresis records are only created between measurements no more than 62 minutes apart, so sparse or interrupted data yields proportionally fewer of them.

Measured payload sizes (UTF-8 bytes on the wire):

PCD-01 is larger per observation because the MDC codes and units are long coded triplets rather than short strings.

Worked example — 20 devices on a 5-minute interval, diuresis included:

288 measurements + ~288 diuresis  = ~576 observations/device/day
x 20 devices                       = ~11,500 observations/day
Generic:  ~11,500 x 80 B           = ~0.9 MB/day
30-day backfill in one response    = ~28 MB

A 30-day backfill across every ward is therefore a tens-of-megabytes single response. Bound your initial sync (requirement 11): loop day by day over date_from/date_to without updated_since, or filter with ward_id / device_serial_number. Then switch to updated_since for steady-state polling, where each response is normally small or empty.

Device-to-Patient Pairing

Requirement 18 applies: your system maps the device serial number to a patient or bed.

For Generic ORU consumers (MetaVision, etc.):

• PV1-3 (also in OBR-10) contains the device's serial number (e.g., 908W)
• Configure your CIS to map this string to a virtual bed location
• The patient assigned to that bed receives the data

For PCD-01 consumers:

• Pass the patient_id query parameter if your system knows the patient
• Without patient_id, the PID segment contains a placeholder (UNKNOWN)

Authentication Errors

Validation Errors

Returned as JSON with an error field:

{
  "error": "Both date_from and date_to query parameters are required."
}

Server Errors

{
  "error": "HL7v2 message conversion failed.",
  "profile": "PCD-01"
}

I get an empty body (or a message with no OBX segments)

An empty response body means "no observations matched" — it is a valid answer, not an error, and it is the normal steady state when polling with updated_since. If you expected data, work down this list:

Not a cause: invalid measurements are still returned, flagged with OBX-11 = "X". They are never silently dropped, so anomaly detection cannot empty your response.

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 the application — see Support.

Timestamps look an hour or two out

All emitted timestamps are UTC with an explicit +0000 offset. Parse the offset rather than assuming local time: Czech local time is UTC+1 in winter and UTC+2 under daylight saving, so a fixed adjustment is wrong for part of the year.

My parser rejects the message

Check that you are splitting a multi-message body correctly: the Generic profile returns one message per device, concatenated, each starting with MSH|. A parser that assumes a single message will see trailing garbage.