Download API
In this tutorial, we will employ the Download API. This resource leverages IMO’s capabilities for managing value sets, reference data sets, and custom release files.
Use Cases
The Download API allows users to retrieve release files and reference data sets. IMO retains current collections of the 3rd party coding standards required for use across the healthcare industry. The API is a solution for users who need to:
- Receive files from IMO’s secure download environment, including access to historical files for your release files and reference data sets.
- Manage the reference data sets needed for your organization’s billing and clinical operations. IMO makes the following up-to-date coding standards available for download:
APC | IMO CPT® 2023 | CVX | HCPCS | ICD-10-CM and CMS-HCC | ICD-10-PCS |
ICD-9-CM | LOINC | MS-DRG | NDC | SNOMED CT INT | SNOMED CT US Edition
- Obtain IMO clinical terminology release files:
- Precise problem terminology: ICD-10-CM | SNOMED-CT
- Enhanced specialty terminology (available with IMO Core): DSM-5-TR | Dental | DC:0-5 | ICD-o-3
- Procedure terminology (coming soon!): CPT® | ICD-10-PCS | SNOMED-CT
- Efficiently obtain third party code set updates in a timely manner from a single IMO resource.
Let’s discuss: What work can be done with the Downloads API?
Terminology releases are essential to the accuracy and integrity of data. The Downloads API provides files containing current regulatory standards, ensuring the compliance of health care operations.
When third party code set updates and terminology releases are available, bringing this data up-to-date is a vital step that the Download API can help you do quickly, securely, and efficiently.
Setup
Determine the files that you need to satisfy your use case. You will use the API to obtain release files or reference data sets.
Authentication
To call the Download endpoint, use the access token obtained from our OAuth2 authorization server.
How to call the Downloads API
- I. Determine the file required for your needs.
Step 1: Select product.
Description: This request will give the user a list of the products available to them
Request:
curl –X GET https://api.imohealth.com/download/v1/products
-H “Authorization: Bearer {{UPDATE_BEARER_TOKEN_HERE}}”
Response:
[
{
“id”: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
“product_name”: “Example Product Name”,
“product_slug”: “example-product-slug-12",
“fields”: [
{
“id”: “b8e51b9a-46a2-11ee-be56-0242ac120002",
“product_id”: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
“field_type_id”: 1,
“field_name”: “Library”,
“display_order”: 2
}
],
“menu_options”: [
{
“id”: “24aa9382-46a3-11ee-be56-0242ac120002",
“product_id”: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
“url”: “{0}”,
“option”: “Release Notes”
}
]
}
]
Choose the required product from the list in the response and copy the corresponding product_slug
Step 2: Select sub product.
Description: This request will give the user a paged list of the sub products available to them for a given product. Pass in the product_slug copied in the previous step through the URL
Request:
curl –X GET https://api.imohealth.com/download/v2/products/{product_slug}/sub-products
-H “Authorization: Bearer {{UPDATE_BEARER_TOKEN_HERE}}”
Response:
{
"current_page”: 1,
“total”: 1,
“page_size”: 10,
“items”: [
{
“sub_product_name”: “Example Sub Product Name”,
“id”: “5a9994a2-46ad-11ee-be56-0242ac120002",
“product_id”: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
“organization_id”: “00393482300wD”,
“is_public”: true,
“sub_product_slug”: “example-sub-product-slug-34"
}
]
}
Choose the required sub product from the list in the response and copy the corresponding sub_product_slug
Step 3: Select version.
Description: This request will give the user a paged list of the versions available to them for a given sub product. Pass in the product_slug and sub_product_slug copied in the previous steps through the URL.
Request:
curl –X GET https://api.imohealth.com/download/v2/products/{product_slug}/sub-products/{sub_product_slug}/versions
-H “Authorization: Bearer {{UPDATE_BEARER_TOKEN_HERE}}”
Response:
{
"current_page”: 1,
“total”: 1,
“page_size”: 10,
“items”: [
{
“effective_date”: “2022-10-01”,
“launch_date”: “2022-10-01",
“id”: “61f36aec-46ae-11ee-be56-0242ac120002",
“sub_product_id”: “5a9994a2-46ad-11ee-be56-0242ac120002",
“version_name”: “2022 October”,
“created_at”: "2022-12-15T20:36:54.371613+00:00",
“created_by”: “IMO User”,
“updated_at”: "2022-12-15T20:36:54.371613+00:00",
“updated_by”: “IMO User”,
“version_slug”: “2022-october-93",
“version_metadata”: [],
“version_menu_actions”: []
}
]
}
Choose the required version from the list in the response and copy the corresponding version_slug
- II. Initiate Download
Step 1: Get download URLs.
Description: If the user followed the steps from the previous section, they should have all the information required to initiate downloading of the appropriate files. This next endpoint will give the users a presigned URL from AWS to download the files associated with a given version. Pass in the product_slug, sub_product_slug and version_slug copied in the previous steps through the URL.
Request:
curl –X GET https://api.imohealth.com/download/v1/products/{product_slug}/sub-products/{sub_product_slug}/versions/{version_slug}/files
-H “Authorization: Bearer {{UPDATE_BEARER_TOKEN_HERE}}”
Response:
[
{
“id”: "43084a1a-46b0-11ee-be56-0242ac120002",
“version_id”: “61f36aec-46ae-11ee-be56-0242ac120002",
“file_name”: “example_file_name.csv”,
“download_url”: “https://filex.s3.amazonaws.com/example-product-slug- 12/00393482300wD/example-sub-product-slug-34/2022-october-93/example_file_name.csv”?response-content-disposition=attachment...,
“publish_url”: null
}
]
Copy the download_url for all the files in the response.
IMPORTANT: The download URLs expire in 5 minutes from when they are generated.
Step 2: Download files.
Description: The user must now send a PUT request to each of the download_urls obtained from the previous step. The appropriate headers are also included in the download_url. No bearer authorization token is required.
Request:
curl –X PUT {{UPDATE_DOWNLOAD_URL_HERE}}Response:
The response is the file associated with the download_url
Setup for Notification Process
This notification process is optional. You may follow the steps below to help you set up notifications when new releases are available. In order to receive a notification of new releases that you’re interested in, we will be using Amazon SNS to send out notifications. Webhooks, the HTTP/HTTPS protocol for SNS, is currently supported.
Step 1: Preparing your webhook URL for processing SNS messages
The webhook endpoint that you provide to us will need to be capable of handling the POST requests that SNS sends out for the subscription confirmation as well as the notification messages themselves.
- Please follow the steps outlined in this AWS documentation for preparing your endpoint(s) for processing Amazon SNS messages to properly receive the release notifications.
Step 2: Providing your webhook to IMO customer support
After you have properly prepared your endpoint for the subscription confirmation and notification messages, please reach out to customer support: CustomerSupport@imohealth.com with the following information:
- The subject of “Downloads Release Notification – Webhook"
- A message body containing:
- The webhook URL
- The names of the product(s) and/or subproduct(s) for which you require notifications
Summary: Download
You sent a call to the Download API with a goal to receive release files/reference data sets.
1. Determined the files needed from IMO. Using a GET request, you:
- Choose the required product from the product list in the response, and you copied the corresponding product_slug.
- Choose the required product from the sub products list in the response, and you copied the corresponding product_slug.
- Selected the required product version from the list in the response, and you copied the corresponding sub_product_slug.
2. You initiated the download. Using a GET request, you:
- Obtained the download URLs for the associated with a given version of the product.
- Requested each of the download_urls obtained from the previous step.
- Downloaded the files – the response is the file associated with the download_url.