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

There are six (6) data elements used to successfully render the BiliTool results page. Five (5) are required (ageHours, totalBilirubin, bilirubinUnits, gestationalWeeks, neuroRiskFactors) and one (1) (eTCOC) is optional (see below). Their datatypes are also 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.

NEW: A new optional value of ETCOc (end-tidal carbon monoxide, corrected to ambient CO) has been included. If elevated (per AAP guidelines) it will render the results page for the presence of neurotoxicity risk factors, regardless of the value of neuroRiskFactors. For example, if the API value for neuroRiskFactors is "No", but the API string includes a value for ETCOc AND that value is elevated (>= 1.7 ppm), then the value of the neuroRiskFactors attribute will be set to "Yes" and the results will reflect this change.

Important:

  • Each data element in the URL must be separated by an '&' (ampersand). Their order is not important.
  • Variable names are case sensitive (camelCase). Example: ageHours, not agehours

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&eTCOC=1.8

ageHours (required)

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 (required)

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 (required)

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 (required)

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 (required)

  • 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)
  • Note: if eTCOC is included (optional) and its value is greater than or equal to 1.8 ppm, it will reset neuroRiskFactors to "yes" (see below).
Example: neuroRiskFactors=Yes

eTCOC (optional)

  • The end-tidal carbon monoxide (corrected) in parts per million (ppm)
  • If entered (optional), a value greater than or equal to 1.7 ppm will set the neuroRiskFactors value to yes, regardless of its prior value (Yes or No).
Example: eTCOC=1.8

 

URL formatting

The template URL:

https:/emr.bilitool.org/results.php?ageHours=[value(s)]&totalBilirubin=[value(s)]&bilirubinUnits=[value]&gestationalWeeks=[value]&neuroRiskFactors=[value]&eTCOC=[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&eTCOC=1.8

Single value entry in SI units:

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

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&eTCOC=0.9