For Business

API v3 Migration Guidelines

In API v3, we introduced a few major improvements, including breaking changes that require the adaptation of your application. To start using the new version, you need to replace the URL https://api.infermedica.com/v2 to https://api.infermedica.com/v3.

What was changed?

  • We significantly improved the reasoning algorithm. It outperforms the previous algorithm in terms of diagnostic and triage accuracy. Now, a more relevant ranking is returned.
  • We added the age dimension to our models, which requires a new request format. Moreover, the age attribute becomes mandatory in /parse, /suggest and GET requests. Additionally sex parameter will be mandatory in /suggest.
  • Requests with age under twelve years old will not be accepted anymore.
  • A new /concepts endpoint was introduced to return basic data about symptoms, risk factors, lab tests, and conditions. See more details in the Concepts section.
  • A new option in the extras collection: enable_explanations was introduced in /diagnosis. The purpose of this option is to provide additional descriptions of selected questions to make them easier to understand for users. See more details in the enable_explanation section.
  • A new option in the extras collection: enable_third_person_questions. This option allows you to create an interview scenario in which users can answer questions on behalf of someone else, e.g. "Does she have a headache?" See more details in the enable_third_person_question section.
  • The endpoint /rationale will return an empty response when there is no result for the request. Previously it returned a 400 error code and an error message. See more details in the Rationale section.
  • 5-level triage recommendation will become the default one. If you’d like to continue using 3-level triage, you need to add the extras option: enable_triage_3: true See more details in the enable_triage_3 section.
  • Diagnoses ranking is limited to the most relevant conditions by default. The extras option enable_adaptive_ranking: true is no longer supported. See more details in the Disable Adaptive Ranking section.
  • Flags initial and related that occur with evidence in POST requests are no longer supported. They are replaced by the source attribute. See more details in the Indicating Evidence Source section.
  • Request parameter type in /search is replaced with parameter types which can handle multiple values separated by a comma.
  • Endpoint /lookup is removed.

Breaking changes

This section contains all of the changes that require code changes before v3 usage

Requests with age under twelve years old will be rejected

In the new version, only cases with the age greater or equal twelve years old will be accepted. For those aged under 12 years, Infermedica is currently building its pediatric content to support younger patients.

In the old model, requests for children cases are still accepted by our API, but there is no guarantee regarding the correctness of such diagnoses. Because of this, we disabled such a possibility in the new model. When you deal with such cases, the dedicated pediatrics functionality is strongly recommended.

Age has a new format in POST requests

API v2, which supported age in years as the numeric value, was extended and now it is possible to provide an age in months as well. The new format is composed of two attributes:

  • value — numeric value, this attribute is required.
  • unit — text value, one each of year and month; this attribute is optional and the default value is year.

Legacy format from v2 that was replaced:

JSON

"age": 18

New format that is valid since version v3:

JSON

"age": {
    "value": 11,
    "unit": "month"
}

Endpoint /lookup is removed

The /lookup endpoint is no longer supported in v3. It has been removed.

Changes in /parse

  • The age parameter became mandatory with the new format described in the section above.
  • The sex parameter is optional but highly recommended.

The example query including both those parameters:


{
    "text": "my period is late",
    "age": {"value": 18, "unit": "year"},
    "sex": "female"
}

The /parse endpoint is used typically to build health check-up chatbots. It helps identify the user’s chief complaints expressed in unstructured text. Before these changes the chatbot designer could decide whether the user would be asked first for age and sex or the conversation would start with the user reporting chief complaints. Now the chatbot must ask for age first (and, preferably, also for sex) before proceeding to ask for chief complaints.

The change allows us to capture the evidence in user text that is best suited for the given age and sex.

  • Age became mandatory.
  • Request parameter type in /diagnosis was replaced with parameter types which can handle multiple values separated by a comma. Instead of: type=symptom&type=lab_test following format would be accepted: types=symptom,lab_test

Changes in /rationale

  • In case when there is no rationale result for request, the endpoint /rationale will return an empty response. Previously 400 error code and an error message were returned.

Changes in /suggest

  • The age parameter became mandatory with the new format described in the section above.
  • The sex parameter became mandatory.
  • The selected parameter was removed.

Age appears as a required request param in GET requests

In endpoints with an output dependent on age, the request params age.value and age.unit were introduced.

Format

Age in get requests is composed of two request parameters:

  • age.value — numeric value.
  • age.unit — one of year or month, this parameter is optional and the default value is year.

Examples

  • /symptoms?age.value=20 (for 20 years old)
  • /symptoms?age.value=20&age.unit=year (for 20 years old)
  • /symptoms?age.value=7&age.unit=month (for 7 months years old)

Endpoints where age param is required

  • /symptoms
  • /conditions
  • /risk_factors
  • /lab_tests
  • /search

For endpoints like /symptoms, /conditions, /risk_factors, and /lab_tests, the number of returned items could depend on the age. If you would like to get data unrelated to age, please use the new concepts endpoint instead.

Triage recommendation changed to 5-level by default

5-level triage recommendation is now the default one. If you’d like to continue using 3-level triage, you need to add the extras option: enable_triage_3: true.

Diagnoses ranking is limited to the most relevant conditions by default

Since adaptive ranking became default, extras option enable_adaptive_ranking: true is not supported anymore. If you would like to disable adaptive ranking please add the new extras option: disable_adaptive_ranking: true.

Fields marked as deprecated

Functionality marked as deprecated in version v2 has been removed in version v3 and won’t be supported anymore. A list of functionality unsupported in version v3 is attached below:

Flags “initial” and “related” that occur with evidence in POST requests

Implications: The evidence provided in the sample JSON below will not be supported anymore. Instead, use the field source introduced in v2.4 (see Indicating evidence source).

JSON 
      
        {
            "id": "s_21",
            "choice_id": "present",
            "initial": true
        },
        {
            "id": "s_22",
            "choice_id": "present",
            "related": true
        }
© 2019 Infermedica