Overview

The Lumiata API uses the RESTful paradigm. It adheres to the FHIR Specification.

API Grammar

The Lumiata API is built on industry standards for representing data. All medical data is represented as FHIR resources. The following table enumerates the coding systems used within the resources.

Medicals Records, Bundles, and Resources

In the FHIR data model, individual medical records or documents are represented as Resources. A collection of FHIR resources corresponding to a particular individual is called a FHIR Bundle or Bundle. All Lumiata endpoints return one of three data structures:

  • Bundle containing Patient and all related Risk Assessment resources
  • Bundle containing Patient with optional all related via include and rev-include resources
  • Single Patient Resource

Taxonomy of Resources returned by the API

A Bundle can contain any of hte following resources. All Resources conform to the FHIR specification (HL7 DSTU version 2.0). The structure of each resource can be found by clicking through the FHIR specification for that resource.


Resource Description Primary Code System Used
Patient Demographics and other administrative information about an individual receiving care or other health-related services.
RiskAssessment An assessment of the likely outcome(s) for a patient or other subject as well as the likelihood of each outcome. The Risk Matrix™ and Clinical Rationale™ are represented in a RiskAssessment resource. Lumiata Coding System
Practitioner Any individual engaged in the healthcare process and healthcare-related services as part of their formal responsibilities. This Resource is used for attribution of activities and responsibilities to these individuals. NPI
Encounter An interaction between a patient at any care touch point for the purpose of providing health care service(s) or assessing the health status of a patient.
DiagnosticReport The findings and interpretation of diagnostic tests performed on patients, groups of patients, devices, and locations, and/or specimens derived from these. RxNorm, CPT, ICD-9, ICD-10, LOINC, HCPCS
DiagnosticOrder A record of a request for a diagnostic investigation service to be performed. RxNorm, CPT, ICD-9, ICD-10, LOINC, HCPCS
Procedure An action that is or was performed on a patient. This can be a physical intervention like an operation, or less invasive like counseling or hypnotherapy. LOINC, CPT, HCPCS
Condition Conditions, problems or diagnoses recognized by a clinician. ICD-9, ICD- 10
Observation Measurements and simple assertions made about a patient, device or other subject. LOINC, CPT, HCPCS
MedicationOrder An order for both supply of the medication and the instructions for administration of the medication to a patient. RxNorm, NDC

The Lumiata API

Check Your API Key
All API calls must include an API Key.

The Medical Timeline

The Medical Timeline endpoint accepts a Patient ID and optional parameters and returns a FHIR Bundle for that individual.


Connection URL: api.lumiata.com/<version>/individual/now/medicalTimeline/{id}


It can also return a FHIR Bundle for all active patients in that population.


Connection URL: api.lumiata.com/<version>/population/now/medicalTimeline

Parameters

Parameter Required Description
X-App-Key Y Your Personal API Key
X-App-ID Y The unique identifier for the individual
Explore tutorial

The Risk Matrix

The Risk Matrix Endpoint accepts a patient ID and optional parameters and returns the Risk Matrix™ and associated Clinical Rationale™ for that individual.


URL: api.lumiata.com/<version>/individual/future/riskMatrix/

Parameter Required Description
apikey Y Your Personal API Key
patient-id Y The unique identifier for the individual
prediction N If prediction is not set, only risk predictions greater than X% will be returned. Adding a prediction parameter lets a user set the threshold that a diagnoses will be returned. The argument is of the form: {code system}|{code}|threshold
start-date N If set, will only return Resources generated after the start-date
end-date N If set, will only return Resources generated before the end-date

Analyzing the Output

The Risk Matrix API returns a RiskAssessment FHIR resource in the JSON format. The following are the key fields.


Field Description
id The ID that uniquely identifies this risk Matrix output.
reference A field of the form Patient\key which uniquely identifies the patient resource
basis

The Clinical Rationale (in FHIR this is the basis for the prediction). The basis is an array of rationale outputs of the form type\id, that refers to a unique

  • Resource Type and Resource in the patient Bundle

For example:

Condition/f27cf76e-fec1-4c72-a0ba-174c6cb60921

Should be interpreted that the Condition resource with ID = f27cf76e-fec1-4c72-a0ba-174c6cb60921 supports the prediction in the Risk Matrix. The actual resource can be extracted from the FHIR Bundle.

prediction

An array of prediction objects. Each prediction corresponds to a single diagnosis, and contains the following fields:

  • Outcome

    Contains three fields:

    • A coding array which identifies the code system used and the actual code of the diagnosis
    • A probabilityDecimal field with the current precision of the model at predicting this dx.
    • A whenPeriod, which identifies the timeframe under which the prediction is valid

For example, The following represents a prediction of 80% that a patient will be diagnosed with Benign Essential Hypertension (ICD-9 code 401.1) in the time frame of 4/5/2015 to 7/4/2015:

"prediction": [
    {
      "outcome": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/sid/icd-9-cm",
            "code": "401.1"
          }
        ]
      },
      "probabilityDecimal": 0.8,
      "whenPeriod": {
        "start": "2016-04-05T00:00:00-07:00",
        "end": "2016-07-04T00:00:00-07:00"
      }
   }
]

  • {
      "resourceType": "RiskAssessment",
      "id": "a7bb5a8f-2a90-4a2e-a405-7227817dd850",
      "subject": {
        "reference": "Patient/b04c847a-3fbe-4505-8052-eaa8431f9d9a"
      },
      "basis": [
        {
          "reference": "Condition/f27cf76e-fec1-4c72-a0ba-174c6cb60921"
        },
        {
          "reference": "Procedure/c4255768-fcbf-4d71-89cd-f5b0ec747e31"
        },
        {
          "reference": "Observation/b622ef93-0f7a-45ad-b9f2-e1a2303ae167"
        },
        {
          "reference": "MedicationOrder/0b2f8fdc-18a6-4664-8305-ab65fd94b9a6"
        }
      ],
      "prediction": [
        {
          "outcome": {
            "coding": [
              {
                "system": "http://hl7.org/fhir/sid/icd-9-cm",
                "code": "401.1"
              }
            ]
          },
          "probabilityDecimal": 0.8,
          "whenPeriod": {
            "start": "2016-04-05T00:00:00-07:00",
            "end": "2016-07-04T00:00:00-07:00"
          }
        },
        {
          "outcome": {
            "coding": [
              {
                "system": "http://hl7.org/fhir/sid/icd-9-cm",
                "code": "401.1"
              }
            ]
          },
          "probabilityDecimal": 0.6,
          "whenPeriod": {
            "start": "2016-04-05T00:00:00-07:00",
            "end": "2016-04-19T00:00:00-07:00"
          }
        },
        {
          "outcome": {
            "coding": [
              {
                "system": "http://hl7.org/fhir/sid/icd-9-cm",
                "code": "401.1"
              }
            ]
          },
          "probabilityDecimal": 0.35,
          "whenPeriod": {
            "start": "2016-04-05T00:00:00-07:00",
            "end": "2016-04-06T00:00:00-07:00"
          }
        }
      ]
    }
    

Explore tutorial

Population Search API

The Lumiata Population Search API engine allows users to intuitively search through a population of patients, based on a wide variety of features, including demographics, location, providers, diagnoses, risk of future diagnoses, eliminated diagnoses, and many others criteria.

Methodology

The Search API makes it possible to quickly and intelligently search through the entire population of medical records. This can be used to generate queries for, but not limited to, Patient Chase Lists, population analytics, and risk adjustment.

Endpoints

The Search API endpoint is returns a collection of individual patient timeline FHIR bundles for all patients that are currently active in the system.

Connection URL: api.lumiata.com/<version>/population/now/medicalTimeline

Parameters

Method Parameter Required Notes
GET gender N The unique patient identifier for this customer.
GET age_geq N If specified, returns only patients of age greater than or equal to the specified parameter
GET age_leq N If specified, returns only patients of age less than or equal to the specified parameter
GET Zipcode OR
city and state OR
state
N Specifies the location of the patients returned.
GET condition N Restricts results to patients with the specified condition. The condition must be coded as ICD-10.
GET procedure N Restricts results to patients with the specified procedure. The procedure must be coded as ICD-10.
GET diagnosticOrder N Restricts results to patients prescribed or indicated the specified medication. The order must be coded as RxNorm.
GET pcp N Restricts results to patients with the specified Primary Care Physician. The PCP is identified by his/her NPI.
GET practitioner N Restricts results to patients with the specified practitioner identified in their records. The practitioner is identified by the NPI.
GET observation N Restricts results to patients with the specified observation (Lab). Observations must be coded by LOINC.
GET has_eliminated_dx* N Restricts results to patients with a current suspected eliminated diagnosis.
GET Has_suspected_condition N

If has_suspected_diagnoses is set, results are restricted to patients with the probability of a diagnosis over a 1 year timeframe diagnoses greater than or equal to 10%. If has_suspected_condition is an array, it restricts the output patients with all of the conditions greater than 10%.

If timeframe is set to either 0, 6, 12, 18 or 24, it restricts the results to patients at risk of the condition over the specified timeframe.

If threshold is set to a number between 0 and 1, it restricts patients at risk for the specified diagnosis to be greater than or equal to the threshold.

GET suspected_condition_timeframe
AND
Has_suspected_condition
N

Overrides the timeframe value of the has_suspected_condition filter. Valid time frames are 1,6,12,18 and 24, corresponding to the number of months to predict forward.

For example, to restrict to patients with a probability of being diagnosed with hypertensive CKD (icd-10 code:I112.) within 18 months, the following parameters would be set:

&has_suspected_condition=I112.
&suspected_condition_timeframe=18

GET suspected_condition_

The API supports AND and OR operators

AND operator

The AND operator is achieved in URL via repeating the parameter multiple times (procedures, for example)

http://snomed.info/sct|84439
http://snomed.info/sct|84430
http://snomed.info/sct|84432

or html as:

?procedure=http://snomed.info/sct|84439&procedure=http://snomed.info/sct|84430&procedure=http://snomed.info/sct|84432

OR operator

The OR operator in URL is meaningful only for the non-textual ( type other than string ) fields by adding a comma between parameter values:

http://snomed.info/sct|84439,http://snomed.info/sct|84430,http://snomed.info/sct|84432

or html as:

?procedure=http://snomed.info/sct|84439,http://snomed.info/sct|84430,http://snomed.info/sct|84432

Please note that for the String fields the comma is ignored as a part of the text search

AND vs OR for the same field

And (procedure)

http://snomed.info/sct|84439
http://snomed.info/sct|84430
http://snomed.info/sct|84432

Or (procedure)

http://snomed.info/sct|84439,http://snomed.info/sct|84430,http://snomed.info/sct|84432

Pleas note that the fields containing a type which is not an array cannot contain multi-line parameters and therefore do not support AND clauses, having said that those single-lined paraders will offer support for offer if the type is not a string

Using both operators together

To specify the AND and OR parameters in swagger please follow the following convention

For the fields wth type Array, typing a parameter on each line will generate an AND causes and typing a comma between parameters will generate an OR clause

http://snomed.info/sct|84439,http://snomed.info/sct|84430
http://snomed.info/sct|84432

or html as:

?procedure=http://snomed.info/sct|84439,http://snomed.info/sct|84430&procedure=http://snomed.info/sct|84432

Please note that for the String fields the comma is ignored as a part of the text search

Screening search parameters

In FHIR, the search parameters have to be escaped from specific characters https://www.hl7.org/fhir/search.html#escaping

Output

The output of a search query is a list of Bundles. Each bundle is as specified in the Patient Timeline API.

FHIR data types of search parameters

boolean

Boolean value as "true" or "false" strings in GET parameters and form values or actual boolean value in JSON. For more details, please see FHIR documentation

code

Value from a set of fixed values defined in parameter description. For parameters allowing OR syntax comma , in values must be escaped. For more details, please see FHIR documentation

composite

Parameter for search based on a pair of values, such as all observations with a sodium value >150 mmol/L, or searching on Group.characteristic where you need find a combination of key/value, not an intersection of separate matches on key and value. Another example is spatial coordinates when doing geographical searches. Composite search parameters supports joining single values with a $:

  • state-on-date=new$2013-05-04
  • code-value-quantity=http://loinc.org|2823-3$gt5.4|http://unitsofmeasure.org|mmol/L

If value contains $ symbol it must be escaped. Both single values have own types and must be formatted and escaped accordingly. For more details, please see FHIR documentation

date

A date parameter searches on a date/time or period. The date parameter format is yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm] (the standard XML format). Any degree of precision can be provided, but it SHALL be populated from the left (e.g. can't specify a month without a year), except that the minutes SHALL be present if an hour is present, and you SHOULD provide a time zone if the time part is present. Note: Time can consist of hours and minutes with no seconds, unlike the XML Schema dateTime type. Value may be prefixed to control the nature of the matching. Examples:

  • 2013-01-14 matches any time in 2013-01-14
  • ne2013-01-14 matches any time not in 2013-01-14
  • gt2013-01-14T10:00 matches all time in 2013-01-14 after 10:00

For more details, please see FHIR documentation

id

Resource ID value as is. For parameters allowing OR syntax comma , in values must be escaped. For more details, please see FHIR documentation

include

_include and _revinclude parameters allow retrieve resources related to the search results. Parameter values for both _include and _revinclude have three parts, separated by a : character:

  • 1. The name of the source resource from which the join comes;
  • 2. The name of the search parameter which must be of type reference;
  • 3. A specific of type of target resource (for when the search parameter refers to multiple possible target types).

The latter parts could be omitted:

  • _include=Procedure:performer:Practitioner include resources referenced by matched Procedure resources by performer search parameter of type Practitioner
  • _revinclude=Procedure:subject include all procedures that references matched Patient and Group resources with subject search parameter
  • _include:recurse=Procedure include all resources referenced by all matched and included Procedure resources
  • _include=*&_revinclude=* include all resources referenced by and referencing matched resources with any search parameter
For more details, please see FHIR documentation

number

Search by simple numeric values in resource (integer or float). Value may be prefixed to control the nature of the matching. Examples:

  • 100
  • 100.01
  • lt100

For more details, please see FHIR documentation

quantity

A quantity parameter searches on the Quantity data type. The syntax for the value follows the form [prefix][number]|[system]|[code] and matches a quantity with the given unit. If value contains | symbol it must be escaped. Examples:

  • value=5.4|http://unitsofmeasure.org|mg value of 5.4 mg where mg is UCUM unit code)
  • value=5.4||mg value of 5.4 mg where the unit - either the code or the stated human unit are "mg"
  • value=le5.4|http://unitsofmeasure.org|mg value of is less than 5.4 mg as a UCUM unit

For more details, please see FHIR documentation

reference

A reference parameter refers to references between resources. For example, find all Conditions where the subject reference is a particular patient, where the patient is selected by name or identifier. The interpretation of a reference parameter is either:

  • [parameter]=[id] the logical [id] of a resource using a local reference (i.e. a relative reference);
  • [parameter]=[type]/[id] the logical [id] of a resource of a specified type using a local reference (i.e. a relative reference), for when the reference can point to different types of resources (e.g. Observation.subject);
  • [parameter]=[url] where the [url] is an absolute URL - a reference to a resource by its absolute location
  • [parameter]:[type]=[id] the logical [id] of a resource of a specified type using a local reference (i.e. a relative reference

Examples matching the same resource:

  • GET /1.0/fhir/Condition?subject=23
  • GET /1.0/fhir/Condition?subject=Patient/23
  • GET /1.0/fhir/Condition?subject:Patient=23
  • GET /1.0/fhir/Condition?subject=https://fhirapi.lumiata.com/1.0/fhir/Patient/23

For more details, please see FHIR documentation

string

For a simple string search, a string parameter serves as the input for a case- and accent-insensitive search against sequences of characters. By default, a field matches a string query if the value of the field equals or starts with the supplied parameter value, after both have been normalized by case and accent. The :contains modifier returns results that include the supplied parameter value anywhere within the field being searched. For more details, please see FHIR documentation

token

A token type is a parameter that searches on a URI/value pair. It is used against a code or identifier data type where the value may have a URI that scopes its meaning. The search is performed against the pair from a Coding or an Identifier. The syntax for the value is one of the following:

  • [parameter]=[code] the value of [code] matches a Coding.code or Identifier.value irrespective of the value of the system property;
  • parameter]=[system]|[code] the value of [code] matches a Coding.code or Identifier.value, and the value of [system] matches the system property of the Identifier or Coding;
  • [parameter]=|[code] the value of [code] matches a Coding.code or Identifier.value, and the Coding/Identifier has no system property.

Note: The namespace URI and code both must be escaped. Matches are literal (e.g. not based on subsumption or other code system features), but not case sensitive.

Examples (matching different resources):

  • identifier=http://acme.org/patient|2345
  • code=|2345
  • code=2345

For more details, please see FHIR documentation

Interactive Tutorial