Precision Sets - FHIRv14

IMO Precision Sets API

In this tutorial, we will leverage the IMO Precision Sets API’s for retrieving and searching for value sets, supporting both FHIR and generic responses.

What problem can you address with this API?

The IMO Precision Sets API is designed to search and access value sets to identify patient cohorts, implement clinical decision support, provide insights, and support compliant reporting. The API provides a solution for users who need to: 

  • Retrieve individual value sets and their output codes
  • Retrieve value sets and their metadata based on specific search criteria
  • Submit a list of codes for matches within the IMO Precision Administrative Coding Assistance Sets to determine if codes are designated as Non-Primary or Unspecified.
     

How to call the API

To utilize the Precision Sets API, you'll need to first authenticate using an access token. Once authenticated, you can proceed to make requests to the API.

Authentication

Once you have your Client ID and Client Secret from IMO, follow these steps to construct the `Authorization` header.

Send a POST request to:

https://api.imohealth.com/oauth/token

with body:

{
   "client_id":"CLIENT_ID",
   "client_secret":"CLIENT_SECRET",
   "audience":"https://api.imohealth.com",
   "grant_type":"client_credentials"
}

and header: 

content-type: application/json

The response will give you the access_token. Use that to create the header:

Authorization: "Bearer ACCESS_TOKEN_HERE"

Please contact IMO Customer Support at CustomerSupport@imo-online.com if you do not know your Client ID/Secret.

Making a request

Determine the API endpoint you'd like to call, and call it as such replacing the endpoint:

curl -X GET https://api.imohealth.com/fhir/r6/ValueSet/VALUE_SET_ID_HERE -H "Authorization: Bearer ACCESS_TOKEN_HERE"

The response format will be in FHIR R6 compliant JSON.

*Note: for the search endpoint an "Accept-Encoding" header must be sent with the values "gzip, deflate, br" for compression purposes. 

Example:

    return http.get(
        `https://api-dev.imohealth.com/fhir/r6/valueset/search?searchText=${searchTerm}`,
        {
            headers: {
                Authorization: `Bearer ${token}`,
                'Accept-Encoding': 'gzip, deflate, br'
            }
        }
    );

 

Notes on Response Format

Please note that null or empty fields will be excluded from the response payload. Refer to the table below for information on which fields are nullable.

Precision sets editor fields fhir api fIELD NULLABLE
Title name No
Value Set ID id No
Value Set Version ID meta.versionId No
Domain extension.{http://imohealth.com/domain}.value No
Value Set Version Publication Status status No
Created Date (Value Set) extension.{http://imohealth.com/extension/createdDate}.value No
Last Updated Date (Value Set) date No
Created Date (Value Set Version) expansion.timestamp No
Published Date (Value Set Version) approvalDate No
Created By (Value Set) author.name Yes
Last Updated By (Value Set) editor.name Yes
Created By (Value Set Version) publisher Yes
Inclusion criteria scope.inclusionCriteria Yes
Exclusion criteria scope.exclusionCriteria Yes
Scope description Yes
External ID identifier.{http://imohealth.com/identifiers}.value Yes

 

valueset-details - /fhir/r6/ValueSet/{ValueSetId}

This endpoint returns output codes for the latest published value set based on input value set ID. This endpoint is FHIR-functional.

 

valueset-search - /fhir/r6/ValueSet/search
 

The search endpoint returns a list of value sets based on specific search criteria. This endpoint is FHIR-functional.

  • The search will match the user’s input term to its root word; for example, “diabetes” will also return results that contain “diabetic”).
  • If a user inputs more than one term, the search will results based on the exact order.
  • The search will not return any results if the user search criteria contains ONLY the following stop words (i.e. "a", "an", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it",       "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"”.
Parameter  Required?  Allowable Values 
searchText  Optional. Text to search for in value set title and metadata.   
ValueSetType  Optional. By default, "All".  "Custom", "IMO", "Industry Standard", and "All" 
SearchField Optional. By default, "All".  "Title", "Scope", "Inclusion Criteria", "Exclusion Criteria", and "All" 
CreatedDateFrom  Optional  Filter for value sets created on or after this date. It must use UTC time (format: YYYY-MM-DD) 
CreatedDateTo  Optional  Filter for value sets created on or before this date. It must use UTC time (format: YYYY-MM-DD) 
ModifiedDateFrom  Optional  Filter for value sets last modified on or after this date. It must use UTC time (format: YYYY-MM-DD) 
ModifiedDateTo  Optional  Filter for value sets last modified on or before this date. It must use UTC time (format: YYYY-MM-DD) 
page  Optional. It defaults to 1.  Page number for pagination 
pageSize  Optional. It defaults to 100.  Number of records per page 

 

valueset-codes-lookup - v1/value-sets/lookup

A user submits a list of codes to be matched within value sets from the IMO Precision Administrative Coding Assistance Sets (ACS) Library; a user can further specify a category title and/or value set within the library. The endpoint will return results to indicate if the code is designated as Non-Primary or Unspecified.

Recommendation: To minimize implementation changes and facilitate future expansion to additional use cases, it is recommended to populate optional fields (librarytitle, categorytitles, valuesetids) from the outset as a best practice.

 

Parameter  Required?  Allowable Values  Error Handling 
librarytitle  Optional. By default, the API assumes the library as ACS . Currently, no other library is supported. 

A user can specify the library title (i.e. "IMO Precision Administrative Coding Assistance Sets") 

 

If a user specifies an invalid value, they will see a 400 error with a message to check library. 

 
categorytitles  Optional. By default, the API assumes the category includes all categories within the ACS library to which the user has access. 

A user can specify category or categories title. (e.g. "Unspecified Codes", "Non Primary Diagnostic Codes") 

 

If a user specifies an invalid value, they will see a 400 error with a message to check category. If a user specifies valid and invalid values, they will see a 400 error. 

 
valuesetids

Optional. By default, the API assumes the value sets include all value sets within the ACS library to which the user has access. 

 

 A user can specify value set(s) as value set ID (e.g. "10071", "8058") 

If a user specifies an invalid value (either as a single invalid value OR in combination with valid and invalid values), the user will see results for all provided codes.  

  1. If the diagnosis codes has matched to a valid value set, the code will appear in the results with appropriate fields. 
  2. If the diagnosis codes does not match to a valid value set ID, the code will appear in the results with null fields.  
codesystem  Required  A user must indicate code system associated to diagnosis code (i.e. "ICD_10_CM", "IMO_PROBLEM") 
  1. If a user does not provide code system parameter, there will be a 400 error.
  2. If a user provides a code system value that is null or invalid, that specific diagnosis code will null fields because it did not match. 

 
code  Required  This would be ICD-10-CM or IMO lexical codes (e.g. "B82.9", "64434300") 
  1. If a user does not provide code parameter, there will be a 400 error.
  2. If a user provides a code value that is null or invalid, that specific diagnosis code will return as an empty result because it did not match 

 

code-hierarchy-lookup - v1/value-sets/hierarchy/{codeSystem}/{code}

A user submits a code from a code system. The endpoint returns the hierarchy (parents and children) if any exist.

Parameter  Required?  Allowable Values  Error Handling 
codeSystem  Required route parameter. 

A user can specify the following values for code systems: snomed for SNOMED CT, icd10cm for ICD-10-CM, icd9cm for ICD-9-CM.  

 

If a user specifies an invalid value, they will see a 400 error with a message to check their route. 

 
code  Required route parameter. 

A user can specify the code to view its hierarchy.  

 

If a user specifies a code which is not found in the code system, they will see a 400 message that the code was not found. 

 
Domain  Required query parameter. 

A user can specify one of the following domains: Problem, Procedure, or Medication.  

 

If a user specifies an invalid value for domain, they will see a 400 message that the domain was not found. 

 
hierarchyMode  Optional query parameter. 

A user can specify one of the following hierarchy modes: ChildrenOnly, ParentOnly, or Both. If the user does not provide a hierarchy mode, the endpoint will default to Both.  

 

If a user specifies an invalid value for hierarchy mode, they will see a 400 message for unexpected hierarchy mode value