BiliTool EMR |

BiliTool EMR allows an electronic health record system to create a prebuilt URL containing the required data elements needed to query BiliTool directly without the manual entry of age, bilirubin, gestational weeks, etc. This document describes the BiliTool Open API (Application Programming Interface) to render that resource via a simple hyperlink or "infobutton".

This API provides that endpoint, however proper variable gathering from one or more components of your EHR, configuration and formatting must be performed by appropriate personnel (e.g. an analyst or system administrator) at your organization or your EHR provider.

Required data elements

All of the following five (5) data elements are required to successfully render the BiliTool results page. Their datatype is described below (e.g. integer, float or string), however variables are loosely typed so use of a string value, instead of an integer for example, may be ok. Please test accordingly.

Each data element in the URL must be separated by an '&' (ampersand). Their order is not important.

An example URL (more details about the URL below):

https://emr.bilitool.org/results.php?ageHours=22&totalBilirubin=11.3&bilirubinUnits=US&gestationalWeeks=38&neuroRiskFactors=No


ageHours

The age of the newborn (hours) at the time a total serum bilirubin (TSB) or transcutaneous bilirubin (TcB) sample was taken (not necessarily analyzed, especially if there's latency between collection and laboratory analysis beyond an hour).

  • An integer datatype.
  • Range is 1-336 hours. Server-side validation will throw an error if outside this range.

Example: ageHours=22


totalBilirubin

The resulted total bilirubin (TSB or TcB). May be in either US units (mg/dL) or SI units (µmol/L) which are specified separately in the "bilirubinUnits" variable (see below).

  • A float datatype
  • Rounded, regardless of what is entered, to a precision of one decimal (e.g. 12.3).

Example: totalBilirubin=8.4


bilirubinUnits

The bilirubin unit of measure, in either US units (mg/dL) or SI units (µmol/L).
  • A text string
  • Values are either "US" or "SI" (no quotes).
Example: bilirubinUnits=US

gestationalWeeks

The best obstetric estimate of the newborns' gestational age in weeks. The 2022 AAP Management of Hyperbilirubinemia Guideline is limited to 35 or more weeks of gestation.

  • Also, an integer datatype
  • Value set: 35, 36, 37, 38, 39 or 40. An entry of "40" is considered as 40+ weeks gestation.
Example: gestationalWeeks=36

neuroRiskFactors

  • Describes the presence or absence of any hyperbilirubinemia neurotoxicity risk factors, other than gestational age, as described in the 2022 AAP Guideline (see a list in the sidebar to the left)
  • A text string of either "Yes" or "No" (no quotes)
Example: neuroRiskFactors=Yes

URL formatting

The template URL:

https://emr.bilitool.org/results.php?ageHours=[value(s)]&totalBilirubin=[value(s)]&bilirubinUnits=[value]&gestationalWeeks=[value]&neuroRiskFactors=[value]

  • Use "https"
  • Separate each variable with "&".
  • Validate and test that the data elements (variables) and their values are properly formed per the descriptions above.
  • Single vs. sequential data. You may submit two data pairs using the newborn age at sampling (ageHours) and bilirubin (totalBilirubin) to evaluate the bilirubin trend or rate of change, by separating each value with a comma (","). Datasets must be equally paired; the same number of values in the set for each element.
    The most recent dataset pair is used to render the canonical recommendations (e.g. reflex testing, phototherapy, escalation of care, exchange tranfusion threshold, postdischarge recommendations, etc.).
    The last two dataset pairs are used to evaluate the rate of change (ROC). More than two dataset pairs may be included, but any datasets prior to the last two chronologically will not affect any of the results. In a future release, those extra datasets may be used to plot all values to visualize the trends on the BiliGraph. See this tutorial for more information.

Examples


Single value entry in US units:

https://emr.bilitool.org/results.php?ageHours=24&totalBilirubin=7.3&bilirubinUnits=US&gestationalWeeks=39&neuroRiskFactors=Yes


Single value entry in SI units:

https://emr.bilitool.org/results.php?ageHours=12&totalBilirubin=210.4&bilirubinUnits=SI&gestationalWeeks=39&neuroRiskFactors=No


Sequential (paired) entry to evaluate bilirubin rate of change:

https://emr.bilitool.org/results.php?ageHours=12,24,48&totalBilirubin=7.3,14.4,15.2&bilirubinUnits=US&gestationalWeeks=39&neuroRiskFactors=No