Precision Sets InterOp APIv9

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"”.

     

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 

 

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