The /diagnosis endpoint is the core of the Infermedica API. Given a patient’s sex, age and medical evidence (including symptoms, risk factors and laboratory test results), it suggests possible causes and generates diagnostic questions to drive an interview similar to one a doctor would have with a patient.
The Infermedica API is stateless. Since the API does not track the state or progress of interviews, each request to /diagnosis must contain all information gathered to that point about a given case. You can’t send only the answer to the most recent question returned from /diagnosis; your application must store sex, age, initial evidence, and all previous answers, and resend them each time together with the most recent answer.
To carry out a diagnostic interview with a patient you will need multiple calls to /diagnosis. Before the first request, the patient’s sex, age and initial evidence must be collected (e.g. the patient's chief complaint and relevant risk factors). The response to the first request will contain a diagnostic question that should be presented to the patient. The patient's answer should then be added to the list of already collected evidence. The process should continue in the following manner:
/diagnosis with the updated evidence list/diagnosisThe process can continue for as long as necessary, until a stop condition is met. The should_stop attribute offers a convenient stop recommendation that should be used in most cases, but if your application requires a different approach, it can also be safely ignored. In general, the number of questions answered and the probability of the top conditions in the ranking should be considered when deciding when to stop the interview.
For more advanced request analysis, we encourage you to include a custom HTTP header Interview-Id with a fixed random value in all requests made during a single interview. Grouping related requests will help us build a better statistical model in order to improve the reasoning engine. Please note that the statistical data we obtain do not compromise the anonymity and privacy of your users in any way.
The /diagnosis endpoint responds to POST requests containing a JSON object that describes a single medical case, e.g.
curl "https://api.infermedica.com/v2/diagnosis" \
-X "POST" \
-H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" -d '{
"sex": "female",
"age": 25,
"evidence": [
{"id": "s_47", "choice_id": "present", "initial": true},
{"id": "s_22", "choice_id": "present", "initial": true},
{"id": "p_81", "choice_id": "absent"}
],
"extras": {
"disable_groups": true
}
}'The sex and age attributes are two required elements of every request to /diagnosis. Under the hood, sex and age are used to automatically instantiate corresponding risk factors that may alter the base prevalence of medical conditions in Infermedica's model.
The sex attribute indicates the patient's biological sex and can only have one of two possible values:
femalemaleAge can only be expressed as a positive integer number (between 0 and 130). Omitting sex or age or providing invalid values will yield a 400 Bad Request error.
The evidence list is the most important part of each request to /diagnosis. While evidence is technically an optional attribute, to receive a non-empty response there must be at least one present symptom or laboratory test result added to your evidence list. Please note that sending only risk factors or only absent symptoms might not be sufficient to start the interview.
Each piece of evidence should be sent as a simple JSON object with two required attributes: id and choice_id. Optionally, initial and observed_at attributes can be added (see their descriptions below).
{
...
"evidence": [
{"id": "s_98", "choice_id": "present"}
]
}The id attribute indicates an observed symptom, risk factor or lab test result. Conditions can also be used as evidence when it is certain that a patient does not have a particular condition.
The choice_id attribute represents the state of given evidence and can have one of 3 values: present, absent or unknown. Please note that absent and unknown cannot be used interchangeably, as their mathematical meanings are different.
Omitting id or choice_id or providing invalid values will yield a 400 Bad Request error .
Interviews are most effective when they are started with meaningful initial evidence. The search space of available symptoms is very wide, so the statistical inference engine needs a place to start. For this reason you should aim for at least 2-3 initial present symptoms. Adding additional symptoms (also absent ones) and risk factors is also helpful.
There are many ways to gather initial evidence:
/search endpoint to implement autocomplete widgets that let users enter and select their observations/parse endpoint to analyze free-text (either pre-existing, like a patient record, or entered by the user) and extract mentions of observations from it/suggest endpoint to find observations that have often been selected by other users with similar health problemsBased on our experience from numerous deployments, it is both important and challenging to design this initial step in a way that will encourage users to provide enough data to begin the interview.
The initial evidence, i.e. evidence reported by the user before the start of the interview, should be marked as initial, e.g.
{
...
"evidence": [
{"id": "s_98", "choice_id": "present", "initial": true}
]
}There are two consequences of marking evidence as initial:
conditions ranking when their probability is sufficiently high. This makes the interview results more focused on the chief complaints.In most cases, initial evidence reported by a patient is related to the conditions in the ranking. However, we've noticed that some users select initial evidence but later deny all related symptoms, causing the engine to broaden its search space and return unrelated conditions. Designating evidence as initial prevents such cases.
Although there are use cases where it is impossible to use the initial attribute, and it is therefore optional, we highly recommend using this attribute whenever possible, especially if you rely on the stop recommendations.
In our medical knowledge base, risk factors can be chronic conditions (e.g. diabetes), lifestyle habits (e.g. smoking), geographical locations (e.g. South America) or events (e.g. a head injury or insect bite). Risk factors alone are not sufficient information to start the interview, but their presence may greatly impact the base prevalence of various conditions. For example, if a patient reports a high fever and chills, it's most likely the flu. However, if the same symptoms are present but we know that the patient has recently returned from some exotic location, the engine will broaden its search towards infectious tropical diseases. Similarly, when a patient reports headache it is important to know if they have recently suffered an injury or trauma.
Although /diagnosis may return questions about risk factors, when implementing a symptom checker we recommend asking the patient about common risk factors before the actual interview begins. This helps to steer the interview in the right direction and to reduce its length. There are a few groups of common risk factors:
p_7 – BMI over 30p_9 – Hypertensionp_10 – High cholesterolp_28 – Smokingp_13 – North America without Mexicop_14 – Latin and South Americap_15 – Europep_16 – Northern Africap_17 – Central Africap_18 – Southern Africap_19 – Australia and Oceaniap_20 – Russia, Kazakhstan and Mongoliap_21 – Middle Eastp_22 – India, China and Southeastern Asiap_147 – Physical injury (marking it absent will also exclude other questions about injury related risk factors listed below)p_144 – Abdominal traumap_145 – Acceleration-deceleration injuryp_146 – Back injuryp_74 – Craniocerebral traumap_136 – Skeletal trauma, chestp_53 – Skeletal trauma, limbThe previous version of the Infermedica API allowed weight and height to be sent along with sex and age. This is no longer supported, but weight-related risk factors are available in our default model and can be included as evidence instead. There are two such risk factors:
p_6 – BMI below 19p_7 – BMI over 30When a patient's weight and height are available, you can compute their BMI in your application and add the appropriate risk factor as present to the evidence list in a /diagnosis call, e.g.
{
"sex": "male",
"age": "35",
"evidence": [
{"id": "p_7", "choice_id": "present"}
]
}When the patient’s BMI falls within a healthy range (between 19 and 30), you may include both of the above risk factors as absent. Otherwise /diagnosis may return a question about BMI when such information would be relevant in the diagnostic process.
In custom models, the /diagnosis endpoint may optionally track when each piece of evidence was observed and decide if it should still be considered valid at the moment of evaluation.
Evidence validity should only be used with selected custom models. Currently, in the Infermedica default model observations are only considered valid at the exact moment of evaluation. Trying to use evidence validity with the Infermedica default model may cause evidence to be considered expired and thus ignored.
Each observation in the custom model or each of the observation's individual states (present, absent or unknown) may be assigned a time span in which it is considered valid (e.g. a day, a week, etc.). When building an evidence list to pass to the /diagnosis endpoint, you may include the observed_at attribute, which indicates when the evidence was observed. Also, evaluated_at must be added to the request, e.g.
{
"sex": "male",
"age": "35",
"evidence": [
{
"id": "s_10",
"choice_id": "present",
"observed_at": "2016-06-15T08:20:10-07:00"
},
{
"id": "s_140",
"choice_id": "absent",
"observed_at": "2016-06-10T20:20:10-07:00"
},
],
"evaluated_at": "2016-06-16T11:40:00-07:00"
}Only evidence that is still valid at the time of evaluation is considered valid and is used in the diagnostic process. If the observed_at attribute is omitted for some piece of evidence, it is considered valid regardless of the evaluated_at value. If the evaluated_at attribute is omitted, the current time is used as the evaluation time.
All dates must be provided in ISO 8601 format. Setting the time zone is optional and UTC is assumed by default. Setting an invalid date value will yield a 400 Bad Request error.
The extras attribute may contain additional or experimental options that control the behavior of the inference engine. Some are only valid with custom models or selected partners.
Note that providing invalid or non-existent options will not yield any error.
Using this option forces /diagnosis to return only questions of the single type, disabling those of the group_single and group_multiple types. This option is useful when it is difficult or impossible to implement group questions , e.g. in chatbots or voice assistants. As a rule of thumb, we advise keeping group questions enabled whenever possible.
{
...
"extras": {
"disable_groups": true
}
}
The response contains 4 sections:
question - next diagnosis question to ask the patientconditions - ranking of possible medical conditionsshould_stop - signals when to stop the interview (optional - this attribute will be returned only if initial evidence is indicated)extras - usually empty, may contain additional or experimental attributes.{
"question": {
"type": "single",
"text": "Does the pain increase when you touch or press on the area around your ear?",
"items": [
{
"id": "s_476",
"name": "Pain increases when touching ear area",
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
},
{
"id": "unknown",
"label": "Don't know"
}
]
}
],
"extras": {}
},
"conditions": [
{
"id": "c_131",
"name": "Otitis externa",
"common_name": "Otitis externa",
"probability": 0.1654
},
{
"id": "c_808",
"name": "Earwax blockage",
"common_name": "Earwax blockage",
"probability": 0.1113
},
{
"id": "c_121",
"name": "Acute viral tonsillopharyngitis",
"common_name": "Acute viral tonsillopharyngitis",
"probability": 0.0648
},
...
],
"should_stop": false,
"extras": {}
}The question attribute represents a diagnostic question that can be presented to the user.
The question attribute can also have a null value. This means that either no present symptom has been provided as initial evidence or, in the rare case of an extremely long interview, there are no more questions to be asked.
There are 3 types of questions, each requiring slightly different handling.
The single type represents simple Yes/No/Don't know questions, e.g.
"question": {
"type": "single",
"text": "Does the pain increase when you touch or press on the area around your ear?",
"items": [
{
"id": "s_476",
"name": "Pain increases when touching ear area",
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
},
{
"id": "unknown",
"label": "Don't know"
}
]
}
],
"extras": {}
}When the user answers a question of the single type, exactly one object with the id of the item and selected choice_id should be added to the evidence list of the next request, e.g.
{
...
"evidence": [
...
{"id": "s_476", "choice_id": "present"}
]
}The group_single type represents questions about a group of related but mutually exclusive symptoms, of which the patient should choose exactly one, e.g.
"question": {
"type": "group_single",
"text": "What is your body temperature?",
"items": [
{
"id": "s_99",
"name": "Between 99.5 and 101 °F (37 and 38 °C)",
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
},
{
"id": "unknown",
"label": "Don't know"
}
]
},
{
"id": "s_100",
"name": "Above 101 °F (38 °C)",
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
},
{
"id": "unknown",
"label": "Don't know"
}
]
}
],
"extras": {}
}For a question of the group_single type, exactly one object with the id of the selected item and choice_id set to present should be added to the evidence list of the next request, with all other items omitted, e.g.
{
...
"evidence": [
...
{"id": "s_99", "choice_id": "present"}
]
}The group_multiple type represents questions about a group of related symptoms where any number of them can be selected, e.g.
"question": {
"type": "group_multiple",
"text": "How would you describe your headache?",
"items": [
{
"id": "s_25",
"name": "Pulsing or throbbing",
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
},
{
"id": "unknown",
"label": "Don't know"
}
]
},
{
"id": "s_604",
"name": "Feels like \"stabbing\" or \"drilling\"",
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
},
{
"id": "unknown",
"label": "Don't know"
}
]
},
{
"id": "s_23",
"name": "Feels like pressure around my head",
"choices": [
{
"id": "present",
"label": "Yes"
},
{
"id": "absent",
"label": "No"
},
{
"id": "unknown",
"label": "Don't know"
}
]
}
],
"extras": {}
}An object should be added to the evidence list of the next request for each item of a group_multiple question. Any available choice_id is allowed. Omitting any item may cause the same question to be returned by the API again.
Please remember that for use cases where implementing question groups is impossible or difficult (e.g. chatbots or voice assistants), you can disable them using the disable_groups attribute, which can be passed in extras.
Each response contains a conditions attribute holding a list of possible conditions sorted by their estimated probability.
Each condition in the ranking is represented by a JSON object with the following attributes: id, name, name_common and probability.
While name and common_name attributes are returned for convenience, any additional information about a given condition can be retrieved from the /conditions/{id} endpoint using the id attribute.
The probability attribute is a floating point number between 0 and 1 indicating a match between reported evidence and conditions in the model.
Please note that the condition ranking may be empty
[]
if there is no evidence or in rare cases where the combination of evidence isn’t associated with any specific condition.
To prevent reverse-engineering of our models, we limit the number of conditions returned from /diagnosis.
Most notably, if the list of evidence is shorter than 3, only one condition will be returned. In the case of longer evidence lists, /diagnosis can return up to 20 conditions, depending on the probability distribution of the conditions in the ranking.
Once enough information has been collected the interview should be stopped. To help you decide when is the good time to finish asking further questions, we’ve provided the stop condition recommendation. This feature uses a heuristic algorithm which takes into account the number of questions asked and the confidence of the current diagnoses.
The stop recommendation will be available only if you indicated at least one initial evidence (see Gathering initial evidence).
If should_stop is true, it means that the stop condition has been reached. False means that the interview should be continued. If the attribute is not available at all, it means that either you haven’t specified the initial evidence or the stop recommendation could not been proposed.
The extras attribute is empty by default, but can be used to return additional or experimental attributes for custom models or selected partners.
While an interactive symptom checker (e.g. mobile application, chatbot or voice assistant) in which the user is presented with a series of diagnostic questions is the most recognizable use case, there are other valid usages where the /diagnosis endpoint proves helpful.
The /diagnosis endpoint can be used to provide context-aware decision support, e.g. when paired with /parse to analyze patient notes, or integrated into an EHR-like system to provide instant insights about possible causes or subsequent diagnostic steps. In such cases only one call to /diagnosis is usually required, as all evidence is known in advance and there is no direct contact with the patient.
When /diagnosis is used with custom models, there are even more possibilities. We've seen /diagnosis used to qualify patients for clinical trials, to assess the risks of post-operational complications, and to support operators of medical call centers.