Developers

Medical concepts

Diagnostic information recognized by our engine is categorized as symptoms, laboratory test results and risk factors. All three categories are also collectively referred to as observations. Conditions and observations together are referred to as medical concepts.

To take advantage of the diagnostic capabilities of our API you must describe your patient cases in terms of observations available in our model; in other words, you need to know the IDs of the observations to be passed to the /diagnosis endpoint. To make it possible to discover and search for observations, we provide a number of endpoints described in this and following sections.

For each medical concept category there are two REST-inspired read-only endpoints supporting GET requests:

  • one returns the list of all concepts in a given category (e.g. /conditions),
  • the other returns a single concept by its ID (e.g. /conditions/c_1).

Each concept is represented by a JSON object with several attributes. Some attributes are common to all concepts:

  • id – short and unique concept id,
  • name – concept name (professional medical term),
  • common_name – alternative name (plain language). If common_name is not defined, the API returns name instead.

Please note that endpoints returning a single concept (e.g. /conditions/c_1) may return more attributes than endpoints returning a list of concepts (e.g. /conditions).

Below you can find descriptions and examples of available endpoints for discovery of medical concepts. Additional information can be found in API Reference.

Conditions

Conditions represent medical pathologies, conditions, diseases and disorders defined in our model. IDs of conditions always start with the c_ prefix followed by an integer, e.g. c_26.

Endpoints

The /conditions endpoint responds to GET requests by returning the list of all available conditions.

cURL
curl "https://api.infermedica.com/v2/conditions" \
  -X "GET" \
  -H "App-Id: XXXXXXXX" \
  -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

The /conditions/{id} endpoint also responds to GET requests, returning details of a single condition. Specifying an invalid condition ID causes an error response (404).

cURL
curl "https://api.infermedica.com/v2/conditions/c_26" \
  -X "GET" \
  -H "App-Id: XXXXXXXX" \
  -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Attributes

Apart from id, name and common_name, each condition has several available attributes:

sex_filter filter indicating conditions only valid for one sex: one of both, female, male
categories list of categories the condition belongs to (e.g. Dermatology or Gastroenterology)
prevalence approximate estimate of how common the condition is: one of very_rare, rare, moderate, common
acuteness comparative distinction between acute and chronic conditions: one of chronic, chronic_with_exacerbations, acute_potentially_chronic, acute
severity approximate estimate of how severe the condition is: one of mild, moderate, severe; can be used together with acuteness to alert users, e.g. when an acute and severe condition is suggested by /diagnosis
hint brief advice for patients recommending steps to take if the condition is suspected (e.g. Please consult a dermatologist as soon as possible); may be null
icd10_code ICD-10 code of condition; may be null

Example of a JSON object representing a condition, as returned by /conditions/c_26:

JSON
{
  "id": "c_26",
  "name": "Major depressive disorder",
  "common_name": "Depression",
  "sex_filter": "both",
  "categories": [
    "Psychiatry"
  ],
  "prevalence": "moderate",
  "acuteness": "chronic_with_exacerbations",
  "severity": "moderate",
  "extras": {
    "hint": "I suggest you consult a psychologist or psychiatrist.",
    "icd10_code": "F33"
  }
}

See the list of all available conditions.

Symptoms

Symptoms represent medical signs and symptoms caused by conditions from our model. IDs of symptoms always start with the s_ prefix followed by an integer, e.g. s_962.

Symptoms in our model are organized into a parent-child hierarchy. Each symptom can have a single parent symptom assigned, e.g. severe headache is a child of headache. Each parent-child relation has a type assigned. The type of each relation is provided as the parent_relation attribute and describes how the child symptom relates to its parent; e.g. the child may refer to a specific body location (e.g. lumbar back pain or back pain) or an exacerbating factor (e.g. abdominal pain increasing after a meal or abdominal pain).

The parent-child hierarchy of symptoms plays an important role in the diagnostic process:

  • reporting a child symptom automatically adds its parent symptom to the evidence list
  • reporting a parent symptom as absent will inform the engine not to ask about its children.

Endpoints

The /symptoms endpoint responds to GET requests by returning the list of all available symptoms.

cURL
curl "https://api.infermedica.com/v2/symptoms" \
  -X "GET" \
  -H "App-Id: XXXXXXXX" \
  -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

The /symptoms/{id} endpoint also responds to GET requests, returning details of a single symptom. Specifying an invalid symptom ID causes an error response (404).

cURL
curl "https://api.infermedica.com/v2/symptoms/s_962" \
  -X "GET" \
  -H "App-Id: XXXXXXXX" \
  -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Attributes

Like conditions, symptoms have several available attributes (including id, name and common_name):

question diagnostic question asking the patient to confirm or deny the symptom; may be null for professional symptoms, which are only intended for medical providers and are not used in patient interviews
sex_filter filter indicating symptoms only valid for one sex: one of both, female, male
category category of the symptom; currently all symptoms are assigned to the same category: Signs and symptoms
parent_id ID of the parent symptom; may be null
parent_relation type of relation with the parent symptom: one of duration, severity, character, exacerbating_factor, diminishing_factor, location, radiation
children list of child symptoms (symptoms that indicate this symptom as their parent) and their relations with this symptom
image_url URL of optional image illustrating this symptom; may be null
image_source source or copyright information for image from image_url attribute; may be null

Example of a JSON object representing a symptom, as returned by /symptoms/s_962:

JSON
{
    "id": "s_962",
    "name": "Dysphagia",
    "common_name": "Difficulty swallowing",
    "question": "Have you observed discomfort or difficulty swallowing?",
    "sex_filter": "both",
    "category": "Signs and symptoms",
    "seriousness": "serious",
    "extras": {},
    "children": [
        {
            "id": "s_1779",
            "parent_relation": "location"
        },
        {
            "id": "s_1776",
            "parent_relation": "location"
        }
    ],
    "image_url": null,
    "image_source": null,
    "parent_id": null,
    "parent_relation": null
}

See the list of all available symptoms (only for registered users).

Lab tests and lab test results

Laboratory tests may represent any medical procedures that involve testing samples of blood, urine, or other tissues or substances in the body. Each laboratory test has multiple laboratory test results assigned to it. These results represent interpreted outcomes of laboratory tests. We don’t rely on numerical values because the interpretation may depend on the laboratory, equipment or method used to perform the test. We use a set of predefined, comparative types of lab test results:

  • very_low (e.g. very low level of hemoglobin in blood)
  • low
  • normal
  • high
  • very_high
  • present (e.g. blood found in urine)
  • absent (e.g. no blood identified in urine)

IDs of lab tests always start with the lt_ prefix followed by an integer, e.g. lt_5, while IDs of lab test results are a concatenation of the lab test ID followed by an underscore _ and a code of the lab test result’s type, e.g. lt_5_1 (where code is 0 for very_low, 1 for low, and so on; present and absent use p and a respectively, e.g. lt_409_p).

Only laboratory test results (and not laboratory tests) may be used as evidence in requests to /diagnosis.

Endpoints

The /lab_tests endpoint responds to GET requests by returning the list of all available lab tests.

cURL
curl "https://api.infermedica.com/v2/lab_tests" \
  -X "GET" \
  -H "App-Id: XXXXXXXX" \
  -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

The /lab_tests/{id} endpoint also responds to GET requests, returning details of a single lab test and its results. Specifying an invalid lab test ID causes an error response (404).

cURL
curl "https://api.infermedica.com/v2/lab_tests/lt_5" \
  -X "GET" \
  -H "App-Id: XXXXXXXX" \
  -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Attributes

These are the attributes available for a lab test (including id and name:

category category of the lab test: one of Genetic testing, Parasitology, Microbiology, Toxicology, Hormones, Immunology, Arterial blood gas, Tumor markers, Cerebrospinal fluid, Coagulation system, Urine, Biochemistry, Blood count, Other
results list of objects representing possible lab test results with IDs and types

Example of a JSON object representing a laboratory test and its possible results, as returned by /lab_tests/lt_5:

JSON
{
    "id": "lt_5",
    "name": "Hemoglobin",
    "common_name": "Hemoglobin",
    "category": "Blood count",
    "results": [
        {
            "id": "lt_5_1",
            "type": "low"
        },
        {
            "id": "lt_5_2",
            "type": "normal"
        },
        {
            "id": "lt_5_3",
            "type": "high"
        }
    ]
}

Risk factors

Risk factors represent a patient’s chronic conditions (e.g. diabetes), lifestyle factors (e.g. smoking), geographical locations (e.g. Central Africa) and events (e.g. insect bite or head injury) that may modify the baseline probability of conditions. IDs of risk factors always start with the p_ prefix (as in predisposition) followed by an integer, e.g. p_28.

Endpoints

The /risk_factors endpoint responds to GET requests by returning the list of all available risk factors.

cURL
curl "https://api.infermedica.com/v2/risk_factors" \
  -X "GET" \
  -H "App-Id: XXXXXXXX" \
  -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

The /risk_factors/{id} endpoint also responds to GET requests, returning details of a single risk factor. Specifying an invalid risk factor ID causes an error response (404).

cURL
curl "https://api.infermedica.com/v2/risk_factors/p_28" \
  -X "GET" \
  -H "App-Id: XXXXXXXX" \
  -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Attributes

These are the attributes available for a risk factor (including id, name and common_name):

question diagnostic question to asking the patient to confirm or deny the risk factor; may be null for risk factors that should be added automatically based on sex- or age-related risk factors
sex_filter filter indicating risk factors only valid for one sex: one of both, female, male
category category of the risk factor; currently all risk factors are assigned to the same category: Risk factors
image_url URL of optional image illustrating this risk factor; may be null
image_source source or copyright information for image from image_url attribute; may be null

Example of a JSON object representing a risk factor, as returned by /risk_factors/p_28:

JSON
{
    "id": "p_28",
    "name": "Smoking",
    "common_name": "Smoking",
    "question": "Do you smoke?",
    "sex_filter": "both",
    "category": "Risk factors",
    "extras": {},
    "image_url": null,
    "image_source": null
}
PreviousBasics
NextRelated symptoms