Quickstart

This short tutorial will get you started with the Infermedica API in no time. Subsequent sections of this documentation describe our API in great detail, but if you're short on time and have experience with web services, this is a quick overview of what working with Infermedica API is like.

Basics

The current version of the Infermedica API is available at https://api.infermedica.com/v2. It is a standard web service that accepts GET and POST requests. All responses (including error messages) use the JSON format. POST requests also take JSON inputs (make sure you include the header Content-Type: application/json).

Authentication

The Infermedica API uses custom HTTP headers to authenticate your requests. You will need to add App-Id and App-Key headers to every request you make. Find your credentials at Apps page (when you're logged in).

First request

The most important part of our API, which handles diagnostic reasoning, is the /diagnosis endpoint, which accepts POST requests. Apart from sex and age, it requires a list of observed evidence (symptoms, risk factors or laboratory test results). The list cannot be empty, so first you need to gather some initial information about the case.

Let's assume we have a male patient, aged 30, suffering from severe headaches, light sensitivity and a stiff neck. Each observation is represented by a unique ID; in this case the symptom IDs are s_1193, s_488 and s_418, respectively. Later, you can learn about ways to search for observations and find their IDs (e.g. autocomplete or processing free text). Each piece of evidence can have one of three possible states: present, absent or unknown. The state is defined using the choice_id attribute.

The case described above can be represented with the following JSON object:

{
  "sex": "male",
  "age": 30,
  "evidence": [
    {
      "id": "s_1193",
      "choice_id": "present"
    },
    {
      "id": "s_488",
      "choice_id": "present"
    },
    {
      "id": "s_418",
      "choice_id": "present"
    }
  ]
}

Your first request to the API could look like this:

curl "https://api.infermedica.com/v2/diagnosis" \
  -X "POST" \
  -H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" -d '{
    "sex": "male",
    "age": 30,
    "evidence": [
      {"id": "s_1193", "choice_id": "present"},
      {"id": "s_488", "choice_id": "present"},
      {"id": "s_418", "choice_id": "present"}
    ]
  }'

Output

The response returned from /diagnosis will contain two main sections:

  • the next diagnostic question to ask your user
  • a ranking of possible health conditions.
{
  "question": {...},
  "conditions": [...],
  "extras": {}
}

Question

The question attribute represents the next diagnostic question that can be presented to the user. Questions are follow-ups to already reported evidence and can be used to build conversation-like interfaces (symptom checkers, chatbots, etc.) that resemble the way doctors interview their patients.

In our example the API would generate a question about a symptom called “impaired vision” (represented by its ID s_320).

{
  "question": {
    "type": "single",
    "text": "Is your vision impaired?",
    "items": [
      {
        "id": "s_320",
        "name": "Impaired vision",
        "choices": [
          {
            "id": "present",
            "label": "Yes"
          },
          {
            "id": "absent",
            "label": "No"
          },
          {
            "id": "unknown",
            "label": "Don't know"
          }
        ]
      }
    ],
    "extras": {}
  },
  "conditions": [...],
  "extras": {}
}

Please note that in some rare cases question can have a null value (e.g. when an empty evidence list is sent or when there are no more questions to ask).

There are three possible types of questions:

  • single – a yes/no question about a single symptom (e.g. “Do you have a headache?”)
  • group_single – single-choice questions about a group of related symptoms (e.g. “What is your body temperature?”)
  • group_multiple – a multiple-choice question about a group of related symptoms (e.g. “What is the character of your headache?”); any number of symptoms (including none) can be selected.

In some use cases (a chatbot being a popular one) presentation of group questions (group_single or group_multiple) to users might be difficult to implement. You can disable group questions to make sure the API only returns single questions.

Conditions

The conditions attribute is a list of health conditions related to the reported evidence. The list is a ranking sorted by the estimated probability of the conditions.

{
  "question": {...},
  "conditions": [
    {
      "id": "c_49",
      "name": "Migraine",
      "probability": 0.4532
    },
    {
      "id": "c_151",
      "name": "Meningitis",
      "probability": 0.2942
    },
    {
      "id": "c_55",
      "name": "Tension-type headaches",
      "probability": 0.1787
    }
  ],
  "extras": {}
}

Interview flow

It's possible and sometimes necessary (e.g. when analyzing data without user interaction) to settle for the condition ranking returned by the first call to /diagnosis, but asking the user additional questions generated by the API can greatly improve the results.

Following on from the previous example, the condition ranking seems to indicate that our patient may suffer from migraines, but answering additional questions could either help to confirm this suggestion, by increasing its probability and ruling out other, more serious health problems such as meningitis, or could prompt a broader differential diagnosis by suggesting other possible causes.

If the patient were to answer No to the question about impaired vision, you would need to add the following evidence:

{
  "id": "s_320",
  "choice_id": "absent"
}

For single and group_single questions only one piece of evidence (as in the above example) is required. However, please note that group_multiple questions require special handling: you need to include evidence for each item of the question. You can find more examples on the /diagnosis description page.

It's very important to understand that the /diagnosis endpoint is stateless. This means that the API does not track the state or progress of cases it receives, so with each request you need to send all the information gathered about the patient to this point.

In our case the next /diagnosis request could include the following JSON object:

{
  "sex": "male",
  "age": 30,
  "evidence": [
    {
      "id": "s_1193", 
      "choice_id": "present"
    },
    {
      "id": "s_488", 
      "choice_id": "present"
    },
    {
      "id": "s_418", 
      "choice_id": "present"
    },
    {
      "id": "s_320", 
      "choice_id": "absent"
    }
  ]
}

Note how you have to include the new evidence but (because of the stateless nature of /diagnosis) still keep the other data (including sex, age and initial evidence).

You can continue this process: ask a question, accept an answer from the user, append new evidence to the list, make a request to /diagnosis. Each time the API will reply with the updated condition ranking and another question to ask.

Stop condition

It is up to you to decide when you should stop asking questions and present results. Different use cases may require different approaches. The stop condition could be defined to depend on the probability of the conditions (e.g. stop when the first condition in the ranking has more than a 90% probability), or on the number of questions asked (e.g. stop after 15 questions), but some mixture of these approaches might work best.

Results

When your stop condition is met you may use the condition ranking returned from your last call to /diagnosis. You can then obtain more information about each condition (such as its severity, acuteness or advice for the user) using the /conditions endpoint, or get an explanation of why a given condition was suggested using the /explain endpoint (for conditions with probability >20%).

Next steps

You should now have an initial understanding of how to work with the Infermedica API. Feel free to read the subsequent sections of this documentation for detailed information about each endpoint, or go to our GitHub to see sample applications and libraries built on top of our API.

PreviousCase studies
NextBasics