IMO® Precision Normalize
API User Guide
The information inside of this guide is confidential and proprietary. Any use of this outside an agreement or engagement with IMO Health® is prohibited.
Notices
RxNorm® is a registered trademark of the National Library of Medicine.
LOINC® is a registered United States trademarks of Regenstrief Institute, Inc.
SNOMED and SNOMED CT are registered trademarks of SNOMED International. All rights reserved.
This product includes SNOMED Clinical Terms (SNOMED CT) which is used by permission of SNOMED International.
This material includes ICD-O-3 codes used by permission of WHO, from: International Classification of Diseases for Oncology, Third Edition.
Current Procedural Terminology. CPT® is a registered trademark of the American Medical Association. All rights reserved. Applicable FARS/DFARS Restrictions Apply to Government Use.
Fee schedules, relative value units, conversion factors and/or related components are not assigned by the AMA, are not part of CPT and the AMA is not recommending their use.
The AMA does not directly or indirectly practice medicine or dispense medical services.
The AMA assumes no liability for data contained or not contained herein.
The responsibility for the content of any National Correct Coding Policy included in this product is with the Centers for Medicare and Medicaid Services and no endorsement by the AMA is intended or should be implied. The AMA disclaims responsibility for any consequences or liability to or related to any use, nonuse or interpretation of information contained in this product.
Users of the IMO Behavioral Health add-on may have access to DSM-5 content. The DSM-5 content is reprinted with permission from the Diagnostic and Statistical Manual of Mental Disorders, Fifth Edition TM. Copyright © 2022 American Psychiatric Association (“APA”). All Rights Reserved.
Unless authorized in writing by the APA, DSM-5 content may be reproduced or used in a manner inconsistent with the APA’s copyright. This prohibition applies to unauthorized uses or reproductions in any form.
*DSM and DSM-5 are registered trademarks of the American Psychiatric Association, and are used with permission herein. Use of these terms is prohibited without permission of the American Psychiatric Association. Use of this trademark does not constitute endorsement of this product by the American Psychiatric Association.
Use of DSM-5 Content requires appropriate End-Users licenses from the American Psychiatric Association. Additional fees may apply.
Introduction
IMO Precision Normalize provides normalization capabilities enabling standardization of inconsistent clinical data from diverse health information systems to a common, clinically validated terminology to ensure that problems, procedures, and medications have clean, enriched, and consistent meanings.
The IMO Precision Normalize API is designed for use cases that require real-time normalization. It is ideal for single records or small batches of items per request.
API Access
The API can be accessed at https://api.imohealth.com/precision/normalize/v1/
Authentication
Authentication is performed using OAuth 2.0 Bearer tokens. With an IMO Health® Customer Support provided client ID and secret, a Bearer token can be requested
Prerequisites
An IMO Precision Normalize agreement is necessary to generate bearer tokens. Following entering an agreement API keys are provided and can be used for generating tokens. For more information, contact IMO Health® Customer Support.
Generating a Bearer Token
The following snippet demonstrates a cURL request to generate a Bearer Token:
curl -u "<API Key>:<API Secret>" --data "grant_type=client_credentials&audience=https://api.imohealth.com" "https://auth.imohealth.com/oauth/token"A token will be returned if the provided API keys are valid. This access token can be used in subsequent requests to the IMO Precision Normalize API.
{
"access_token": <Token Value>,
"scope": "normalize",
"expires_in": 8600,
"token_type": "Bearer"
}Code and Description Normalization
The normalize endpoint of the IMO Precision Normalize API supports code and description normalization. The normalize endpoint supports both and is configurable by adjusting the request properties. Up to 300 records may be sent in a single request.
Description Normalization Supported Domains
IMO Precision Normalize supports normalizing descriptions to IMO Content Domains. IMO Precision Normalize supports the Problem, Procedure, and Medication domains.
Domain Description Problem Terms that describe the states of being that can apply to a patient and are relevant to their health or healthcare. that describe the states of being that can apply to a patient and are relevant to their health or healthcare. Procedure Terms that represent actions that can be performed on, or on behalf of, a patient as part of the patient’s health care. Medication Terms representing generic and branded medications at various levels of granularity, such as dose strength and dose form. Lab Terms representing laboratory and anatomic pathology results, orders, and associated observations. Allergen Terms that denote a substance that may trigger an allergic reaction in a patient, including but not limited to food, medication, environmental factors, and other allergenic agents.
Automatic Domain resolution
When the domain of an input description is not known, the IMO Precision Normalize engine can attempt to resolve the description to the IMO Problem, Procedure, Medication, or Lab* (Lab is not enabled by default, please contact IMO Health® Support to enable it) domains (the Allergen domain is not included in the auto domain search as of 04/16/2024).
- Automatic domain resolution will return the matches with highest scores across all IMO domains
- In the event that the highest score includes matches across two or more domains, the API will return an error message, for example:
Unresolvable tied score in problem and procedure domains - Score thresholds can be utilized to meet established organizational policies by setting the minimum score for returned matches.
- Additionally, if an input_code_system is present, the list of resolvable domains will be reduced based on relevance to that code system. Below displays a list of code systems and which domains they include:
- ICD-10-CM - Problem Domain
- RxNorm, NDC, CVX – Medication Domain
- ICD-10-PCS, CPT – Procedure Domain
- SNOMED - Problem, Procedure, Lab Domains
- LOINC - Procedure and Lab Domains
Code Normalization Supported Code Systems
Depending on the code system, clinical equivalent or preferred IMO lexicals will be returned.
Clinically Equivalent
For most code systems a clinically equivalent IMO lexical will be returned for the input code system code. These may be IMO terms that have the same meaning as the code system description or reference descriptions that match the code system description for the code.
Preferred
For CPT and HCPCS a preferred IMO lexical will be returned. Preferred lexicals are not always clinically equivalent to the input, but they represent the clinically relevant aspects of the CPT or HCPCS code. They may be less specific than the input code.
Code Systems
Code System Output Lexical Type Note Supported Naming Formats ICD-9-CM Clinically Equivalent Limited to billable codes icd-9-cm, icd 9 cm, icd 9, icd9-cm, i9, icd9, dx, I9CDX, http://terminology.hl7.org/CodeSystem/icd9cm, 2.16.840.1.113883.6.2, urn:oid:2.16.840.1.113883.6.2 ICD-10-CM Clinically Equivalent Limited to billable codes icd-10-cm, icd 10 cm, icd 10, icd10-cm, i10, i10c, i10p, icd10, icd10cm, icd-10, abf, l, hrv, http://hl7.org/fhir/sid/icd-10-cm, 2.16.840.1.113883.6.90, urn:oid:2.16.840.1.113883.6.90 SNOMED CT Clinically Equivalent
- All IMO Problem terms are mapped to SNOMED CT International codes. An additional mapping is also provided to Problem terms that are equivalent to SNOMED CT US Extension codes and MeSH codes.
- All IMO Procedure terms are mapped to SNOMED CT International codes. An additional mapping is also provided to Procedure terms that are equivalent to MeSH codes.
- All IMO Allergen terms are mapped to SNOMED CT International codes.
snomed, snomed ct, sct, snomedct, snomed-ct, snowmed, snm, snomedct, http://snomed.info/sct, 2.16.840.1.113883.6.96, urn:oid:2.16.840.1.113883.6.96 ICD-10-PCS Clinically Equivalent Limited to billable codes icd-10-pcs, icd 10 pcs, icd10-pcs, icd10pcs, i10pcs, http://www.cms.gov/Medicare/Coding/ICD10, 2.16.840.1.113883.6.4, urn:oid:2.16.840.1.113883.6.4 LOINC Clinically Equivalent loinc, ln, 2.16.840.1.113883.6.1, urn:oid:2.16.840.1.113883.6.1, http://loinc.org CPT Preferred cpt, c4, cpt4, http://www.ama-assn.org/go/cpt, 2.16.840.1.113883.6.12, urn:oid:2.16.840.1.113883.6.12 HCPCS Preferred hcpcs, 2.16.840.1.113883.6.14, urn:oid:2.16.840.1.113883.6.14, http://terminology.hl7.org/CodeSystem/HCPCS, HCP, hcpc, 2.16.840.1.113883.6.285, urn:oid:2.16.840.1.113883.6.285, http://www.cms.gov/Medicare/Coding/HCPCSReleaseCodeSets RXNORM Clinically Equivalent rxnorm, http://www.nlm.nih.gov/research/umls/rxnorm, 2.16.840.1.113883.6.88, urn:oid:2.16.840.1.113883.6.88 NDC Clinically Equivalent Limited to active product NDC codes (as of 8/9/22). And the NDC output will be empty if there are more than 25 NDC product codes mapping to the same RxNorm. Supported formats:
- 11-digit HIPAA format, 5-4-2
- 11-digit CMS-compliant format without any hyphens
- 10-digit format from FDA, includes 4-4-2, 5-3-2, 5-4-1
- Hyphened form is preferred for more accurate results. In certain cases without hyphens, the code can be interpreted as more than one NDC code and IMO Normalize will not assume a particular code (and therefore, will return no match results)
ndc, http://hl7.org/fhir/sid/ndc, 2.16.840.1.113883.6.69, urn:oid:2.16.840.1.113883.6.69 CVX Clinically Equivalent cvx, 2.16.840.1.113883.12.292, urn:oid:2.16.840.1.113883.12.292, http://hl7.org/fhir/sid/cvx
Output Metadata
IMO terms are returned with metadata. This metadata includes code system code mappings for the applicable code system for each IMO domain.
Metadata Object:
Field Name(s) Description flags Object contains flags for the lexical mappings Contains objects for each code system that is mapped to the IMO lexical
For Problem domain lexicals:
icd10cm (ICD-10-CM)
icd9cm (ICD-9-CM)
icdo (ICD-O-3)
snomedInternational (SNOMED CT) (including NLM associated MeSH code)
snomedUSExtension (SNOMED CT US Edition) (including NLM associated MeSH code)
dsm5tr(DSM-5-TR)
For Procedure domain lexicals:
icd10pcs (ICD-10-PCS)
loinc (LOINC)
snomedInternational (SNOMED CT) (including NLM associated MeSH code)
cpt (CPT-4)
hcpcs (HCPCS)
For Lab domain lexicals:
icd10pcs (ICD-10-PCS)
loinc (LOINC)
snomedInternational (SNOMED CT) (including NLM associated MeSH code)
cpt (CPT-4)
hcpcs (HCPCS)
For Medication domain lexicals:
rxnorm (RxNorm)
ndc (NDC)
cvx (CVX)
For Allergen domain lexicals:
rxnorm (RxNorm)
snomedInternational (SNOMED CT) (including NLM associated MeSH code)
severity_mappings (SNOMED CT codes tied to allergen severity)
reaction_mappings (SNOMED CT codes tied to allergic reactions)icd10cm,
icd9cm,
icdo,
snomedInternational,
snomedUSExtension,
dsm5tr
icd10pcs,
loinc,
cpt,
hcpcs,
rxnorm,
ndc,
cvx,
severity_mappings,
reaction_mappingsNested objects of the mappings object. Contains a codes object, which is an array of code system codes for the code system. codes A nested object containing an array of code system codes that are mapped to the IMO lexical
Flags Object
Flags for the lexical
Field Name Description is_icd10cm_refinable A boolean variable indicating whether the lexical can be further refined using IMO's ICD-10-CM calculator/modifier workflow data. When true, it indicates that a term with more ICD-10-CM relevant specificity can be retrieved by submitting the lexical to the IMO Core Search API. allergen_categories These are general categories based on the nature of the allergen source, use, properties, etc. These align with the 2023 HL7 categories in the "AllergyIntoleranceCategory" value set for HL7 FHIR version 5.0.0.
Codes Object
An array of codes mapped to the IMO lexical. For RxNorm codes, see below.
Field Name Description code A code system code title The official description for code map_type A value describing the preference relationship between the code and the IMO lexical. When a lexical is mapped to a single code in a given code system, the map type is by default "preferred primary." When there are multiple codes, this field indicates their relative preference or utility (e.g, "preferred primary", "non-preferred primary", "preferred secondary"). See the map types section for additional information relationship_group Indicates a group number that each ICD-10-PCS code associates with. This is limited to ICD-10-PCS codes only. relationship_type Indicates the semantic relationship between IMO lexical and the code. This field is limited to ICD-10-CM and SNOMED CT.
- Same as: IMO lexical is clinically same as the code
- Narrower than: IMO lexical is narrower than the code
- Broader than: IMO lexical is broader than the code
- Related to: IMO lexical is related to the code
code_metadata An object containing supplemental metadata for the code. Object is present when supplemental metadata may exist for the code’s code system. See Code Metadata for more information regarding available metadata.
dsm5tr Code Object
An array of codes mapped to the IMO lexical. For RxNorm codes, see below.
Field Name Description dsm_icd_10_cm_code ICD-10-CM code per DSM-5-TR guidance dsm_title Description using DSM diagnostic terms map_type A value describing the relationship between the DSM_ICD_10_CM_code and the IMO lexical. See the map types section for additional information
ICD-O Code Object
An array of codes mapped to the IMO lexical.
Field Name Description relationship_group This group is used to identify ICD-O codes that are to be interpreted together to create a complete ICD-O code representation topog_code The topography code indicates the site of the neoplasm topog_desc This field provides the topography code description morph_code The morphology code describes the cell type of the neoplasm and its behavior morph_desc This field provides the morphology code description hist_grad_code This code identifies the histological grading and differentiation of the neoplasm (i.e. grade I – well differentiated) hist_grad_desc This field provides the histological grading and differentiation code description immuno_desig_code This code identifies the immunophenotype designation for lymphomas and leukemias. immuno_desig_desc This field provides the immunophenotype designation code description
rxnorm_codes Object
An array of RxNorm codes mapped to the IMO lexical.
Field Name Description rxnorm_code An RxNorm code rxnorm_titles An array of RxNorm titles for the rxnorm_code
rxnorm_titles Object
Field Name Description title An RxNorm title for rxnorm_code title_type The RxNorm term type (TTY) for title title_status Indicates if the title is ‘current’ and in the current RxNorm release or ‘historical’ and no longer included in the current RxNorm release
ndc_codes Object
An array of NDC codes mapped to the IMO lexical and associated metadata.
Field Name Description ndc_code An NDC code ndc_metadata An array of ndc_metadata objects
ndc_metadata Object
Field Name Description route An array of route(s) of administration of the medication (e.g. oral, intravenous) strength Strength of the medication dose_form Formulation of the medication (e.g. tablet, capsule, solution) brand_name Brand name of the medication generic_name Generic name of the medication title_status Indicates if the title is “Current” in the current NDC release pharm_class An array of pharmacological class categories. If there is no official pharmacological class, such as with some herbal and OTC products, this will be null
cvx_codes Object
An array of CVX codes mapped to the IMO lexical and associated metadata.
Field Name Description cvx_code A CVX code cvx_metadata An array of cvx_metadata objects mvx_metadata An array of mvx_metadata objects
cvx_metadata Object
Field Name Description full_title Full vaccine name for the cvx_code short_title Short description for the cvx_code vaccine_status Indicates the vaccine's availability in the United States (valid values are Active, Inactive, Pending, Never Active) or if it is for use outside of the US ("Non-US"). notes Notes from the CDC about the cvx_code
mvx_metadata Object
Field Name Description code An alphabetic string that identifies the manufacturer of a vaccine. status Indicates the vaccine's availability in the United States (valid values are Active, Inactive, Pending, Never Active) or if it is for use outside of the US ("Non-US").
Map Types
Map Types for icd9cm, icd10cm and dsm5tr
All map types for icd10cm, icd9cm and dsm5tr should be captured. They are all required to represent the clinical intent of the IMO term.
Map Type Description Preferred primary The preferred code mapped to the lexical. Based on CMS guidelines, should be listed first in documentation. Only one preferred primary mapping exists for each lexical. Other preferred primary An additional code mapped to the lexical, which has equal importance as preferred primary. Multiple other preferred primary mappings may exist. Preferred secondary An additional code mapped to the lexical. Should be listed after the preferred codes in documentation. Only one preferred secondary code may exist for each lexical. Alternate secondary Additional codes with mapped to the lexical. Should be listed after the preferred codes in documentation.
Map Types for snomedInternational
All map types for snomedInternational should be captured. They are all required to represent the clinical intent of the IMO term.
Map Type Description Preferred primary The preferred code mapping to the lexical. This record should be captured if only a single SNOMED CT International code can be captured. Non-preferred primary Additional SNOMED CT International code mappings. All should be captured if the integrating application can consume them.
Map Types for snomedUSExtension
All map types for snomedUSExtension should be captured. They are all required to represent the clinical intent of the IMO term.
Map Type Description Preferred primary The preferred code mapping to the lexical. This record should be captured if only a single SNOMED CT US code can be captured. Non-preferred primary Additional SNOMED CT US code mappings. All should be captured if the integrating application can consume them.
Map Types for icd10pcs, cpt, hcpcs, and loinc
Not all codes for ICD-10-PCS, CPT, HCPCS, and LOINC are required to be captured to represent the intent of the clinical term. The below table describes the relationship types.
Map Type Description Preferred primary A "primary code" for a procedure is one that may be appropriate for use as the primary billing code for that procedure. If there is both a preferred and non-preferred primary code, then either or both may be appropriate to use for billing. Applications should ideally present these to billing users so they can use their professional judgment in making that determination.
If an application can only display one code for a lexical, it should display the “Preferred Primary” code.Non-preferred primary A "primary code" for a procedure is one that may be appropriate for use as the primary billing code for that procedure. If there is both a preferred and non-preferred primary code, then either or both may be appropriate to use for billing. Applications should ideally present these to billing users so they can use their professional judgment in making that determination. Not applicable to CPT. Other preferred primary An additional code mapped to the lexical with equal importance as the preferred primary. This occurs when more than one billing code is necessary to reflect the IMO lexical AND either billing code could be the primary billing code. Preferred secondary A "secondary code, which may be needed for complete billing. If there is both a preferred and non-preferred secondary code, then either or both may be appropriate to use for billing. Applications should ideally present these to billing users so they can use their professional judgment in making that determination. If an application can only display one secondary code for a lexical, it should display the “Preferred Secondary” code. Add-on code Code mappings that can optionally be included as add-on codes CPT modifier (only for CPT) Contains CPT modifier code mappings One of these codes A code that has a more specific meaning than the IMO term. Multiple ‘One of these’ mappings will exist and only one of them is applicable. Use one code from group x Limited to ICD-10-PCS. This code set contains a relationship_group indicating a group number that each ICD-10-PCS code associates with. x will update to reflect which group number the ICS-10-PCS code belongs to.
Code Metadata
code_metadata Object
Attribute Name Description ccsr Contains an array of CCSR objects. Each item in the array is a CCSR category associated with the code. If no categories are associated with the code from an applicable code system (ICD-10-CM or ICD-10-PCS) ccsr will be an empty array. hcc Contains an array of HCC objects. Each item in the array is an HCC category associated with the code. If no categories are associated with the code from an applicable code system (ICD-10-CM) hcc will be an empty array.
Clinical Classifications Software Refined Categories (CCSR)
CCSR categories are included in code_metadata for applicable ICD-10-CM and ICD-10-PCS codes.
CCSR Object
Attribute Name Description ccsr_category A CCSR category code ccsr_description The ccsr_category’s description
Risk Adjustment and Hierarchical Condition Category (HCC)
HCC categories are included in code_metadata for applicable ICD-10-CM codes.
HCC Object
Attribute Name Description hcc_factors An HCC factor hcc_model_category The hcc_model_category's code
hcc_factors Object
Attribute Name Description institutional HCC Institutional factor community_fbdual_aged HCC Community full benefit dual aged factor community_pbdual_aged HCC Community partial benefit dual aged factor community_nondual_aged HCC Community non-dual aged factor community_fbdual_disabled HCC Community full benefit dual disabled factor community_pbdual_disabled HCC Community partial benefit dual disabled factor community_nondual_disabled HCC Community non-dual disabled factor
Transformations Object
The transformations object is optional and can be included in the request preferences. When the transformation object is included, the response will contain a new field (transformed_term), which contains the input term after transformations were applied.
Field Name Accepted Value Description type "string_replace"|"multiple_string_replace" The type of transformation to apply to all input_terms in the request location "beginning|end|*" Beginning = Replace a string at the beginning of the input_term; End = Replace a string at the end of the input_term; * = Replace a string found anywhere in the input_term from Any string or array of strings The original string value in the input_term to be replaced. When transformation type is "multiple_string_replace", the value can be an array of strings to Any string The new replacement string case_sensitive "true|false" Whether the string replacement should be case sensitive or not. Default is "false"
Transformations Example
{
"client_request_id": "xxx",
"preferences": {
"match_field_pref": "input_term",
"threshold": 0.5,
"transformations":[
{
"type": "multiple_string_replace",
"location": "end",
"from": ["ARUP","Quest","Labcorp"]
"to": "",
"case_sensitive": false
},
{
"type": "string_replace",
"location": "*",
"from": "pl",
"to": "plasma"
}
]
},
"requests": [{
"record_id": "10001",
"domain": "Lab",
"input_term": "glucose PL ARUP"
},{
"record_id": "10002",
"domain": "Lab",
"input_term": "5-HIAA pl"
}]
}ERROR CODES
If there is an error in processing a record, the output response will contain an error_message field with an error message detailing why the record failed to process. The error message will contain an error code along with text explaining the error message.
Error codes are categorized as follows:
- Validation Errors (Exxx): Indicate issues with the input data.
- Retryable Errors (Rxxx): Indicate temporary issues that may be resolved by retrying the request.
- Non-Retryable Errors (Nxxx): Indicate issues that cannot be resolved by retrying the request.
Validation Errors
- E001: Missing record id
- E002: Missing input term
- E003: Missing domain
- E004: Invalid domain
- E005: Missing input code
- E006: Missing input code system
- E007: Invalid code system
Retryable Errors
- R001: Authentication error: invalid token
- R002: Authentication error: invalid scope
- R003: An error occurred while submitting this record for normalization
Non-Retryable Errors
- N001: Unresolvable tied score in the domain
- N002: Cannot resolve to IMO domain on input term
- N003: An error occurred while performing a term match across multiple domains
- N004: An error occurred while performing a code match across multiple domains
- N005: Cannot resolve IMO domain on input code
Example Error Response
Here is an example of a response with an error message:
{
"summary": {
"count": 1,
"error_count": 1
},
"request_id": "662ff277-b0dd-45cc-aa71-ffe5a285f7cb",
"client_request_id": "xxx",
"requests": [
{
"record_id": "10001",
"domain": "problem",
"response": {
"items": [],
"match_field": "",
"domain": "",
"error_message": [
"E002: Missing input term"
],
"custom_mapped": false,
"parser_output": {}
}
}
],
"response_time": 60,
"preferences": {
"threshold": 0.5,
"debug": true,
"match_field_pref": "input_term"
}
}In this example, the response indicates that there was an error processing the record with record_id "10001" because the input term was missing. The error_message field contains the error code "E002" and the corresponding message "Missing input term".
Error Message Details
The error_message field in the response provides detailed information about the errors encountered during processing. Each error message includes:
- Error Code: A unique identifier for the error.
- Error Message: A description of the error.
By using these error codes and messages, you can quickly identify and address issues with your requests to the IMO Precision Normalize API.
DISCLAIMER
While making all reasonable efforts to ensure accuracy, Intelligent Medical Objects, Inc. assumes no responsibility for errors that may appear in the IMO Health® Precision Normalize user documentation or product. In addition, Intelligent Medical Objects, Inc. assumes no liability with respect to accuracy of codes or data herein.
The information contained in the IMO Precision Normalize user guide is intended to supplement the knowledge of physicians and other health care professionals. This information is advisory only and is not intended to replace sound clinical judgment in the delivery of health care services.
REQUIREMENTS FOR IMPLEMENTATION
The license agreement for the IMO Precision Normalize states that this product must be implemented according to the requirements specified in the IMO Precision Normalize documentation. In addition to the requirements set forth herein and any implementation guides or other documentation provided by IMO Health®, additional requirements for implementing IMO Precision Normalize are as follows:
- The disclaimer notice listed in this document must be included in documentation given to the end user.
- The copyright statement in the copyright file must be listed on all printed reports that are generated using the IMO Precision Normalize data. For example:
Copyright 2024 Intelligent Medical Objects, Inc. All rights reserved
SUPPORT
IMO Health® Customer Support
Phone: (847) 613-6655
Email: CustomerSupport@imohealth.com
Web: www.imohealth.com
© 2024. IMO Health is a trademark of Intelligent Medical Objects, Inc. All rights reserved IMO Health® confidential information, not to be shared with third party without IMO Health® consent.