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/diagnosis
The 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:
female
male
Age 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.