IMO® Precision Normalize API

import { ImoHealthClient } from "@imo-demo/precision-normalize";
async function main() {
    const client = new ImoHealthClient({
        clientId: "YOUR_CLIENT_ID",
        clientSecret: "YOUR_CLIENT_SECRET",
    });
    await client.normalize.enrich({
        clientRequestId: "xxx",
        sessionId: "00000000-0000-0000-0000-000000000000",
        preferences: {
            matchFieldPref: "input_term",
            threshold: 0.5,
        },
        requests: [
            {
                recordId: "10001",
                domain: "Problem",
                inputTerm: "chest pain",
                context: {
                    sourceText: "a crushing pressure in the chest that radiates to left arm",
                },
            },
        ],
    });
}
main();

{
  "request_id": "a140f56f-939e-4456-be74-6ee492a07179",
  "client_request_id": "xxx",
  "session_id": "00000000-0000-0000-0000-000000000000",
  "response_time": 74,
  "requests": [
    {
      "record_id": "10001",
      "domain": "Problem",
      "input_code": "R07.9",
      "input_code_system": "ICD-10-CM",
      "input_term": "chest pain",
      "context": {
        "source_text": "a crushing pressure in the chest that radiates to left arm"
      },
      "response": {
        "explanation": "The input term 'chest pain' was matched to the IMO lexical 'Chest pain' with a score of 1.0.",
        "items": [
          {
            "lexical_code": "85191",
            "lexical_title": "Chest pain",
            "default_lexical_code": "85191",
            "default_lexical_title": "Chest pain",
            "score": 1,
            "certainty": "",
            "metadata": {
              "mappings": {
                "icd10cm": {
                  "codes": [
                    {
                      "code": "R07.9",
                      "title": "Chest pain, unspecified",
                      "map_type": "Preferred primary",
                      "relationship_type": "Same as",
                      "code_metadata": {
                        "ccsr": [
                          {
                            "ccsr_category": "CIR012",
                            "ccsr_description": "Nonspecific chest pain"
                          }
                        ],
                        "hcc": []
                      }
                    }
                  ]
                },
                "icd9cm": {
                  "codes": [
                    {
                      "code": "786.50",
                      "title": "Chest pain, unspecified",
                      "map_type": "Preferred primary"
                    }
                  ]
                },
                "icdo": {
                  "codes": [
                    {
                      "relationship_group": "0",
                      "topog_code": "C42.1",
                      "topog_desc": "Chest Pain",
                      "morph_code": "9835/3",
                      "morph_desc": "Chest Pain",
                      "hist_grad_code": "",
                      "hist_grad_desc": "",
                      "immuno_desig_code": "9",
                      "immuno_desig_desc": "Cell type not determined, not stated or not applicable"
                    }
                  ]
                },
                "snomedInternational": {
                  "codes": [
                    {
                      "code": "29857009",
                      "mesh_code": "D002637",
                      "title": "Chest pain (finding)",
                      "map_type": "Preferred primary",
                      "relationship_type": "Same as"
                    }
                  ]
                },
                "dsm5tr": {
                  "codes": [
                    {
                      "dsm_icd_10_cm_code": "R07.9",
                      "dsm_title": "Chest pain",
                      "map_type": "Preferred primary"
                    }
                  ]
                },
                "umls": {
                  "codes": [
                    {
                      "code": "C0008031",
                      "title": "Chest Pain"
                    }
                  ]
                },
                "uscdi": {
                  "profiles": [
                    {
                      "data_class": "Conditions and Problems",
                      "data_element": "Condition/Problem",
                      "valueset_oid": "2.16.840.1.113883.6.96",
                      "hrsn_domain": "Food Insecurity",
                      "associated_codes": [
                        {
                          "code": "R007.9",
                          "code_system": "icd10cm"
                        }
                      ]
                    }
                  ]
                }
              },
              "flags": {
                "is_icd10cm_refinable": true
              }
            },
            "domain": "Problem",
            "match_field": "input_term"
          }
        ]
      }
    }
  ],
  "preferences": {
    "threshold": 0.5,
    "match_field_pref": "input_term"
  }
}

Normalize a set of input terms or codes to IMO lexicals from the Problem domain using enriched contextual analysis. Employs enhanced AI models to find the most relevant matches and prioritizes clinical context (age, sex, severity, existing ICD-10 codes) supplied with each record.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

client_request_idstringRequired

A unique identifier for the request from the partner application. This may be any string value using any format.

requestslist of objectsRequired

Each object in this array represents a normalization record for a single clinical term or code that you want to match to an IMO lexical. At a minimum, each object must include the record_id and domain fields, as well as either the input_term (when term-based matching) or both of the input_code and input_code_system fields (when code-based matching). When term-based matching, the context fields are also strongly recommended to ensure the most relevant lexical matches, especially the source_text field.

When working with large batches of normalization records, for optimal performance each payload should include 10 to 25 requests objects.

session_idstringOptional=36 characters

A unique identifier for the session, used to correlate requests across endpoints for the term refinement workflow. This should be a value returned by the GET /precision/normalize/session operation.

preferencesobjectOptional

In this object, the match_field_pref field determines whether the API performs term-based or code-based lexical matching. All other fields in this object define operation preferences only applicable to term-based matching.

The preferences in this object apply to every normalization record included in the requests array.

Response

successful operation

summaryobjectOptional

This object provides a summary of the normalization records returned in the requests array.

request_idstringOptional

A globally unique identifier automatically generated for the request by the API.

client_request_idstringOptional

The same value echoed back from the request’s client_request_id field.

session_idstringOptional=36 characters

The same value echoed back from the request’s session_id field, if applicable.

If session_id was excluded from the request, this field is also excluded from the response.

response_timeintegerOptional

The time in milliseconds taken to process the entire request.

requestslist of objectsOptional

Each object in this array corresponds to a normalization record supplied in the requests array of the request. This array lists each normalization record object in the same sequence as its corresponding record in the request. In each object, the response field describes the normalization outcome for the record.

preferencesobjectOptional

This object echoes back the same fields and values included in the request’s preferences object.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

413

Content Too Large Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error