Quick Reference

All API access is over HTTPS, and accessed via the https://ipl.e-imo.com domain. The relative path prefix /api/v3/ indicates that we are currently using version 3 of the API.

Functions

URL HTTPS Verb Functionality
/api/v3/actions/categorize POST Categorize Problem List
/api/v3/actions/specialize POST Specialize Problem List
Authentication

Authentication is done using HTTPS Basic Authentication (Wikipedia).

Once you have your APIKey and APISecret from IMO follow this simple formula to construct the Authorization header.

Authorization: "Basic: " + Base64Encode(APIKey + ":" + APISecret)

Request Format

The request format must be specified in the Content-Type header as one of the following:

  • JSON: application/json

JSON is the recommended format.

Response Format

The response format must be specified in the Accept header as one of the following:

  • JSON: application/json

The response body will contain a Request field detailing the request sent to the server.

Whether a request succeeded is indicated by the HTTPS status code. A 2xx status code indicates success, whereas a 4xx or 5xx status code indicates failure. For more on errors see below.

Object: Category

A Category object details the properties of a category and lists the Problem objects in that category.

Example:
{
    "Code": "1143548347",
    "Name": "Cardiac and Vasculature",
    "SortOrder": {
        "imo": 300,
        "alpha": 0
    },
    "Problems": [
        ...
    ]
}
Object: Specialty

A Specialty object details the properties of a specialty and lists the Problem objects in that specialty.

Example:
{
    "Code": "1337",
    "Name": "IMO Specialty",
    "SortOrder": {
        "imo": 1,
        "alpha": 1
    },
    "Problems": [
        ...
    ]
}
Object: Problem

A Problem object details the properties of a problem.

Example:
{
    "Code": "1",
    "FreeText": "Heart Attack",
    "ImoLexicalId" : "50263",
    "PreferredLexicalText": "Heart attack",
    "SortOrder": {
        "imo": 3,
        "alpha": 0
    },
    "Details": {
        "IMO": "50263",
        "IMOTitle": "Heart attack",
        "ICD10": "I21.3",
        "ICD10Title": "ST elevation (STEMI) myocardial infarction of unspecified site",
        "SNOMED": "22298006",
        "SNOMEDTitle": "Myocardial infarction",
        "ICD9": "410.90",
        "ICD9Title": "AMI NOS, unspecified",
        "PosStdDev": "0.000",
        "Similarity": "1.000",
        "SpecialtyCode": "1337",
        "SpecialtyTitle": "IMO Specialty",
        "SpecialtyOrder": "1",
        "CategoryCode": "1143548347",
        "CategoryTitle": "Cardiac and Vasculature",
        "CategoryOrder": "300",
        "ClusterCode": "1035677191",
        "ClusterTitle": "Coronary artery",
        "ClusterOrder": "3",
        "MCCFlag": "False",
        "CCFlag": "False",
        "HCCCategoryCode": "87"
    }
}
Function: Categorize

The /api/v3/actions/categorize endpoint will categorize a given list of medical problems.

The request body must be formatted as follows:

{
    "Properties": {
        "PatientId": "205028345"
    },
    "Problems": [
        {
            "Code": "1",
            "FreeText": "Heart Attack",
            "Properties": {
                "MyICD10Code": "I21.3"
            }
        },
        {
            "Code": "2",
            "FreeText": "sty"
        }
    ]
}

Or, at minimum:

{
    "Problems": [
        {
            "FreeText": "Heart Attack",
        },
        {
            "FreeText": "sty"
        }
    ]
}

Response:

{
    "Request": {
        "Properties": {
            "PatientId": "205028345"
        },
        "Problems": [
            {
                "Code": "1",
                "FreeText": "Heart Attack",
                "Properties": {
                    "MyICD10Code": "I21.3"
                }
            },
            {
                "Code": "2",
                "FreeText": "sty"
            }
        ]
    },
    "Categories": [
        {
            "Code": "1143548347",
            "Name": "Cardiac and Vasculature",
            "SortOrder": {
                "imo": 300,
                "alpha": 0
            },
            "Problems": [
                {
                    "Code": "1",
                    "FreeText": "Heart Attack",
                    "PreferredLexicalText": "Heart attack",
                    "SortOrder": {
                        "imo": 3,
                        "alpha": 0
                    },
                    "Details": {
                        "IMO": "50263",
                        "IMOTitle": "Heart attack",
                        "ICD10": "I21.3",
                        "ICD10Title": "ST elevation (STEMI) myocardial infarction of unspecified site",
                        "SNOMED": "22298006",
                        "SNOMEDTitle": "Myocardial infarction",
                        "ICD9": "410.90",
                        "ICD9Title": "AMI NOS, unspecified",
                        "PosStdDev": "0.000",
                        "Similarity": "1.000",
                        "CategoryCode": "1143548347",
                        "CategoryTitle": "Cardiac and Vasculature",
                        "CategoryOrder": "300",
                        "ClusterCode": "1035677191",
                        "ClusterTitle": "Coronary artery",
                        "ClusterOrder": "3",
                        "MCCFlag": "False",
                        "CCFlag": "False",
                        "HCCCategoryCode": "87"
                    }
                }
            ]
        },
        {
            "Code": "1040456519",
            "Name": "Eye",
            "SortOrder": {
                "imo": 470,
                "alpha": 1
            },
            "Problems": [
                {
                    "Code": "2",
                    "FreeText": "sty",
                    "PreferredLexicalText": "Sty",
                    "SortOrder": {
                        "imo": 100,
                        "alpha": 0
                    },
                    "Details": {
                        "IMO": "46523",
                        "IMOTitle": "Sty",
                        "ICD10": "H00.019",
                        "ICD10Title": "Hordeolum externum unspecified eye, unspecified eyelid",
                        "SNOMED": "1489008",
                        "SNOMEDTitle": "External hordeolum",
                        "ICD9": "373.11",
                        "ICD9Title": "Hordeolum externum",
                        "PosStdDev": "0.000",
                        "Similarity": "1.000",
                        "CategoryCode": "1040456519",
                        "CategoryTitle": "Eye",
                        "CategoryOrder": "470",
                        "ClusterCode": "1035677196",
                        "ClusterTitle": "Eye",
                        "ClusterOrder": "100",
                        "MCCFlag": "False",
                        "CCFlag": "False",
                        "HCCCategoryCode": "0"
                    }
                }
            ]
        }
    ]
}
NEW: IMO Lexical Support

IMO Lexical Ids can also be provided.

{
    "Problems": [
        {
            "FreeText": "Heart Attack",
        },
        {
            "ImoLexicalId" : "46523",
        },
        {
            "FreeText": "Hypothyroidism, Acquired",
            "ImoLexicalId" : "75076"
        }
    ]
}

Response:

{
    "Request": {
        "Properties": {
            "PatientId": "205028345"
        },
        "Problems": [
            {
                "FreeText": "Heart Attack"

            },
            {
                "ImoLexicalId" : "46523"
            },
            {
                "FreeText": "Hypothyroidism, Acquired",
                "ImoLexicalId": "75076"
            }
        ]
    },
    "Categories": [
        {
            "Code": "1143548347",
            "Name": "Cardiac and Vasculature",
            "SortOrder": {
                "imo": 300,
                "alpha": 0
            },
            "Problems": [
                {
                    "FreeText": "Heart Attack",
                    "PreferredLexicalText": "Heart attack",
                    "SortOrder": {
                        "imo": 3,
                        "alpha": 0
                    },
                    "Details": {
                        "IMO": "50263",
                        "IMOTitle": "Heart attack",
                        "ICD10": "I21.3",
                        "ICD10Title": "ST elevation (STEMI) myocardial infarction of unspecified site",
                        "SNOMED": "22298006",
                        "SNOMEDTitle": "Myocardial infarction",
                        "ICD9": "410.90",
                        "ICD9Title": "AMI NOS, unspecified",
                        "PosStdDev": "0.000",
                        "Similarity": "1.000",
                        "CategoryCode": "1143548347",
                        "CategoryTitle": "Cardiac and Vasculature",
                        "CategoryOrder": "300",
                        "ClusterCode": "1035677191",
                        "ClusterTitle": "Coronary artery",
                        "ClusterOrder": "3",
                        "MCCFlag": "False",
                        "CCFlag": "False",
                        "HCCCategoryCode": "87"
                    }
                }
            ]
        },
        {
            "Code": "1040456519",
            "Name": "Eye",
            "SortOrder": {
                "imo": 470,
                "alpha": 1
            },
            "Problems": [
                {
                    "ImoLexicalId" : "46523",
                    "SortOrder": {
                        "imo": 100,
                        "alpha": 0
                    },
                    "Details": {
                        "IMO": "46523",
                        "IMOTitle": "Sty",
                        "ICD10": "H00.019",
                        "ICD10Title": "Hordeolum externum unspecified eye, unspecified eyelid",
                        "SNOMED": "1489008",
                        "SNOMEDTitle": "External hordeolum",
                        "ICD9": "373.11",
                        "ICD9Title": "Hordeolum externum",
                        "PosStdDev": "0.000",
                        "Similarity": "1.000",
                        "CategoryCode": "1040456519",
                        "CategoryTitle": "Eye",
                        "CategoryOrder": "470",
                        "ClusterCode": "1035677196",
                        "ClusterTitle": "Eye",
                        "ClusterOrder": "100",
                        "MCCFlag": "False",
                        "CCFlag": "False",
                        "HCCCategoryCode": "0"
                    }
                },
            {
            "Code": "1040459356",
            "Name": "Endocrine and Metabolic",
            "SortOrder": {
                "imo": 400,
                "alpha": 1
            },
            "Problems": [
                {
                    "FreeText": "Hypothyroidism, Acquired",
                    "ImoLexicalId": "75076",
                    "SortOrder": {
                    "imo": 30,
                    "alpha": 1
                    },
                    "Details": {
                    "LexicalCode": "75076",
                    "LexicalTitle": "Hypothyroidism (acquired)",
                    "ICD10Code": "E03.9",
                    "ICD10Title": "Hypothyroidism, unspecified",
                    "SNOMEDCode": "111566002",
                    "SNOMEDTitle": "Acquired hypothyroidism",
                    "ICD9Code": "244.9",
                    "ICD9Title": "Unspecified hypothyroidism",
                    "DefaultLexicalTextImoCode": "18848",
                    "CategoryCode": "1040459356",
                    "CategoryTitle": "Endocrine and Metabolic",
                    "CategoryOrder": "400",
                    "ClusterCode": "1035677182",
                    "ClusterTitle": "EM:  Thyroid Cluster",
                    "ClusterOrder": "30",
                    "MCCFlag": "False",
                    "CCFlag": "False",
                    "HCCCategoryCode": "0"
                    }
                }
            ]
        }
    ]
}
Function: Specialize

The /api/v3/actions/specialize endpoint will categorize a given list of medical problems.

The request body must be formatted as follows:

{
    "Problems": [
        {
            "Code": "1",
            "FreeText": "HTN - Hypertension"
        },
        {
            "Code": "2",
            "FreeText": "Elevated glycosylated hemoglobin"
        }
    ],
    "Specialties": [
        {
            "Code": "63173",
            "Name": "cardiology"
        }
    ]
}

Or, at minimum:

{
    "Problems": [
        {
            "FreeText": "HTN - Hypertension"
        },
        {
            "FreeText": "Elevated glycosylated hemoglobin"
        }
    ],
    "Specialties": [
        {
            "Code": "63173"
        }
    ]
}

Response:

{
  "Request": {
    "Problems": [
      {
        "Code": "1",
        "FreeText": "HTN - Hypertension"
      },
      {
        "Code": "2",
        "FreeText": "Elevated glycosylated hemoglobin"
      }
    ],
    "Specialties": [
      {
        "Code": "63173",
        "Name": "cardiology"
      }
    ]
  },
  "Specialties": [
    {
      "Code": "63173",
      "Name": "cardiology",
      "SortOrder": {},
      "Problems": [
        {
          "Code": "1",
          "FreeText": "HTN - Hypertension",
          "SortOrder": {},
          "Details": {
            "IMO": "703765",
            "IMOTitle": "HTN - hypertension",
            "ICD10": "I10",
            "ICD10Title": "Essential (primary) hypertension",
            "SNOMED": "38341003",
            "SNOMEDTitle": "Hypertensive disorder",
            "ICD9": "401.9",
            "ICD9Title": "Unspecified essential hypertension",
            "PosStdDev": "0.000",
            "Similarity": "1.000",
            "SpecialtyCode": "63173",
            "SpecialtyTitle": "cardiology",
            "MCCFlag": "False",
            "CCFlag": "False",
            "HCCCategoryCode": "0"
          }
        }
      ]
    }
  ]
}
Errors

When a request fails, the response body will be in the format specified in the Accept header, and will contain the fields ErrorMessage and DevErrorMessage.

Error Codes:

Status Code Name Why?
200 OK All systems go.
400 Bad Request The request values were incorrect or badly formatted.
401 Unauthorized Invalid APIKey or APIKey not given.
404 Not found Could not communicate with IPL.
500 Internal Server Error Server side error. Contact CustomerSupport@e-imo.com.
503 Service Unavailable Server side error. Contact CustomerSupport@e-imo.com.