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.
|
codesystem | Required | A user must indicate code system associated to diagnosis code (i.e. "ICD_10_CM", "IMO_PROBLEM") |
|
code | Required | This would be ICD-10-CM or IMO lexical codes (e.g. "B82.9", "64434300") |
|
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.
|
codesystem | Required | A user must indicate code system associated to diagnosis code (i.e. "ICD_10_CM", "IMO_PROBLEM") |
|
code | Required | This would be ICD-10-CM or IMO lexical codes (e.g. "B82.9", "64434300") |
|