Fetching interview results

After a finished interview (when a question returns HTTP code 204) the client can call a set of endpoints that can summarize an interview and present some useful information. Those endpoints are:

• Evidence Assessment
• Summary
• Specialist Recommendation
• Care Navigation
• PDF

Below is a breakdown of each of them:

Evidence Assessment

To be able to fetch Infermedica’s AI assessment, the user must both complete the interview and provide evidence during the interview before calling the GET query to /api/mgp/v1/surveys/{survey_id}/evidence_assessment.

Such a request may look like this:

curl "https://api.infermedica.com/api/mgp/v1/surveys/{survey_id}/evidence_assessment" \
  -X "GET" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

{
  "conditions": [
    {
      "id": "c_927",
      "name": "De Quervain syndrome",
      "common_name": "De Quervain syndrome",
      "probability": 0.8589,
      "rating": "strong",
      "icd10": [
        {
          "code": "M65.4"
        }
      ],
      "condition_details": null,
      "explain": null,
      "patient_education": null
    }
  ],
  "triage": {
    "level": "self_care",
    "description": "The symptoms you have declared may not require medical evaluation and they usually resolve on their own. Sometimes they can be eased with self-care methods. If the symptoms get worse or new symptoms appear, consult a doctor.",
    "serious": []
  }
}

Response object

conditions (list)

Each response contains a conditions attribute holding a list of possible conditions sorted by their estimated probability.

Each condition in the rankings is represented by a JSON object with the following attributes: id, name, common_name, icd10, and probability.

The probability attribute is a floating point number between 0 and 1, indicating a match between the reported evidence and conditions in the model.

Please note that the condition rankings may be empty [ ] if there is no evidence or, in rare cases, where the combination of evidence isn’t associated with any specific condition.

triage (object)

• level (str)
  • emergency_ambulance – the reported symptoms are very serious and the patient may require emergency care. The patient should call an ambulance right now,
  • emergency – the reported evidence appears serious and the patient should go to an emergency department. If the patient can't get to the nearest emergency department, they should call an ambulance,
  • consultation_24 – the patient should see a doctor within 24 hours. If the symptoms suddenly get worse, the patient should go to the nearest emergency department,
  • consultation – the patient may require medical evaluation and may need to schedule an appointment with a doctor. If the symptoms get worse, the patient should see a doctor immediately,
  • self_care – the declared symptoms may not require a medical evaluation and they usually resolve on their own. Sometimes they can be treated through self-care methods. Patients should observe their symptoms and consult a doctor if the symptoms get worse or new ones appear.
• serious (list) – Each listed observation has an unique ID and name. All observations returned in the serious list are alarming and require consultation with a medical professional. Each serious observation has a seriousness value of either: serious, emergency, or emergency_ambulance. Observations with emergency or emergency\_ambulance seriousness are particularly urgent and may require immediate attention.

Errors when fetching evidence assessment

{
  "detail": "Survey not found"
}

Summary

To be able to fetch the collected information from the survey, the patient must complete the interview then call the GET query to /api/mgp/v1/surveys/{survey_id}/summary.

Errors when fetching survey summary

{
  "detail": "Survey not found"
}

Specialist Recommendation

The /api/mgp/v1/surveys/{survey_id}/specialist_recommendation endpoint provides a specialist recommendation based on a user's interview responses, specifying the type of specialist to consult and the suggested channel for the consultation.

Example:

curl "https://api.infermedica.com/api/mgp/v1/surveys/{survey_id}/specialist_recommendation" \
  -X "GET" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response:

{
  "recommended_specialist": "Orthopedist",
  "recommended_channel": "personal_visit",
  "specialist": {
    "id": "sp_6",
    "name": "Orthopedist"
  },
  "channel": {
    "id": "personal_visit",
    "name": "In-person visit"
  }
}

Response object

The response contains the following attributes:

• recommended_specialist – Deprecated – name of the recommended specialist. Will be one of the specialist names listed in the Specialist Table below, such as Allergologist, Cardiologist, or Orthopedist.

• recommended_channel – Deprecated – a channel recommendation id. Will be one of the channel IDs listed in the Channel Table below, such as personal_visit or video_teleconsultation.

• specialist – An object providing the ID and name of the recommended specialist. Replaces the now deprecated recommended_specialist. Possible values include:

  • id – a unique identifier for the specialist such as sp_23 or sp_6 (refer to the Specialist Table below for a full list of available IDs and specialist names)
  • name – the name of the specialist (e.g., Allergologist, Cardiologist)

• channel – An object providing the ID and name of the recommended consultation channel. Replaces the now deprecated recommended_channel. Possible values include:

  • id – a unique identifier for the channel such as personal_visit or video_teleconsultation (refer to the Channel Table below for a full list of available IDs and channel names)
  • name – the name of the channel (e.g., In-person visit, Video consultation)

Specialist Table

Channel Table

Errors when fetching specialist recommendation

{
  "detail": "Survey not found"
}

Care Navigation

The /api/mgp/v1/surveys/{survey_id}/care_navigation endpoint evaluates the results of a completed interview against a set of predefined rules to suggest specific organizational care pathways.

Rule Processing Logic & Configuration

Before calling the endpoint, it is important to understand how the engine processes data. The logic operates on a user-provided configuration file in YAML format. This file defines two main components: Weights and Rules.

The process follows these steps:

1. Matching: The engine evaluates the interview results against all defined rules. A rule is considered a "match" only if all of its defined criteria are met (logical AND).
2. Scoring: Every matched rule is assigned a score based on the weights of its matched criteria.
3. Ranking: Results are returned as a list, sorted by their score in descending order.

Configuration Example

The configuration must be provided by the client and uploaded to application instance. It allows you to customize the priority of different criteria.

Weights: You can define custom weights for each criterion key. If not provided, default values are used.

Rules: A list of mapping rules. Each rule has a unique id, a set of criteria, and an output.

weights:
  condition_ids: 352
  condition_categories: 32
  triage_level: 16
  sex: 8
  age: 4
  specialist_id: 2
  channel_id: 1
rules:
  - id: rule_1
    criteria:
      condition_ids:
        - c_981 # back pain
        - c_1083 # joint pain
      condition_categories:
        - Orthopedics
      specialist_id:
        - sp_6
      sex: male
    output:
      care_pathway: Book Orthopedist
      care_pathway_url: https://example-1.com
      translations:
        pl: Ortopeda
        de: Orthopäde
  - id: rule_2
    criteria:
      condition_categories:
        - Traumatology
        - Surgery
      age:
        from_: 40
        to: 65
    output:
      care_pathway: Example
      care_pathway_url: https://example-2.com
  - id: rule_3
    criteria:
      sex: male
      channel_id:
        - audio_teleconsultation
    output:
      care_pathway: Teleclinic
      care_pathway_url: https://example-3.com
  - id: rule_4
    criteria:
      condition_ids:
        - c_889 # fracture of rib
      triage_level:
        - emergency
    output:
      care_pathway: Book Orthopedist
      care_pathway_url: https://example-4.com
  - id: rule_5
    criteria:
      sex: female
      age:
        from_: 18
        to: 30
    output:
      care_pathway: Primary Care
      care_pathway_url: https://example-5.com

Usage

The endpoint returns a list of matched pathways based on the configuration above.

Example:

curl "https://api.infermedica.com/api/mgp/v1/surveys/{survey_id}/care_navigation" \
  -X "GET" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response:

{
  "evaluation_results": [
    {
      "care_pathway": "comprehensive_ortho_pathway",
      "care_pathway_url": "https://example-1.com",
      "criteria_matched": [
        "condition_ids",
        "condition_categories",
        "specialist_id",
        "sex"
      ]
    },
    {
      "care_pathway": "general_physio",
      "care_pathway_url": "https://example-physio.com",
      "criteria_matched": [
        "condition_categories"
      ]
    }
  ]
}

Response object

The response contains an evaluation_results list. Each object in the list represents a matched rule from your configuration, ordered by the strength of the match.

evaluation_results (list of objects)

• care_pathway (str) – The identifier or name of the mapped pathway defined in your configuration rules.
• care_pathway_url (str, optional) – A URL associated with the pathway (e.g., a booking link), if defined in the rule.
• criteria_matched (list of str) – A list of the specific criteria keys that triggered this rule (e.g., condition_ids, age, sex, triage_level).

Translations

The care_pathway value in your configuration file should always be written in the default language of your application. To support multiple languages, you can add localized versions of the pathway name using the optional translations block within each rule's output.

Configuration

Each rule's output can include a translations object where keys are language codes (e.g., pl, de, es) and values are the translated pathway names.

rules:
  - id: rule_1
    criteria:
      condition_ids:
        - c_981
    output:
      care_pathway: Book Orthopedist  # Default language (e.g., English)
      care_pathway_url: https://example.com/ortho
      translations:
        pl: Umów wizytę u ortopedy
        de: Orthopäden buchen
        es: Reservar Ortopedista

How It Works

1. Default Value: The care_pathway field contains the pathway name in your application's default language.
2. Localized Values: The translations block provides alternative names for other supported languages.
3. Fallback: If a translation for the requested language is not available, the system returns the default care_pathway value.

Scoring Details

If you need to fine-tune the order of results, understanding the scoring algorithm is key. The engine prioritizes rules based on their complexity defined in the configuration.

Matching Logic

The engine evaluates the interview results against all defined rules using a specific logical hierarchy:

• Across different criteria (AND): All criteria types defined in a rule must be met. For example, if a rule specifies sex and condition_ids, the patient must match the sex AND have one of the conditions.
• Within list-based criteria (OR): For criteria that accept lists (e.g., condition_ids, condition_categories), the rule matches if the patient presents at least one of the listed items.

Scoring Algorithm

The score for a matched rule is calculated based on the rule's definition, not the number of symptoms the patient actually has.

• Single-value criteria (e.g., sex, age): The score equals the weight defined in the configuration.
• List-based criteria (e.g., condition_ids): The score equals the weight multiplied by the number of items listed in the rule configuration.
  • Note: This means a rule listing multiple alternative conditions (e.g., "Back pain OR Joint pain") will have a higher score than a rule listing just one, regardless of which one the patient has.

Calculation Example

Assuming default weights (condition_ids: 352, sex: 8) and a Male patient reporting Back pain.

Rule A: Specific Condition

• Config: sex: male, condition_ids: ["c_981" (Back pain)]
• Match: Yes. (Sex matches AND patient has Back pain).
• Score:
  • Sex: 8
  • Conditions: 352 * 1 (item in rule) = 352
  • Total: 360

Rule B: Grouped Conditions (OR Logic)

• Config: sex: male, condition_ids: ["c_981" (Back pain), "c_1083" (Joint pain)]
• Match: Yes. (Sex matches AND patient has at least one of the conditions).
• Score:
  • Sex: 8
  • Conditions: 352 * 2 (items in rule) = 704
  • Total: 712

Rule C: Mismatch (Excluded)

• Config: sex: female, condition_ids: ["c_981"]
• Match: No.
• ** Score:** N/A (This rule is excluded from the response).

In this scenario, Rule B appears first because it is defined as a "heavier" rule covering a broader set of orthopedic issues, even though the patient only suffers from one of them. Rule C will not be present at all.

Sorting Order

When multiple rules match the patient's case, the API returns all of them, sorted according to the following hierarchy:

1. Total Score (Descending): The primary sorting factor. Rules with higher cumulative weights appear first.
2. Specificity (Descending): If scores are tied, the rule with a higher number of defined criteria keys is prioritized.
3. Rule ID (Ascending): A deterministic tie-breaker using the alphanumeric order of the rule ID.

Errors when fetching care navigation

{
  "detail": "Survey not found"
}

PDF Summary

The /api/mgp/v1/surveys/{survey_id}/summary_pdf endpoint generates and returns a PDF document that summarizes the patient's interview, including all of the patient's survey responses and other relevant information. The contents of PDF documents are equivalent to those found when using the summary endpoint, but presented in PDF format.

Example:

curl "https://api.infermedica.com/api/mgp/v1/surveys/{survey_id}/summary_pdf" \
  -X "POST" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_stylesheet": "https://example.com/styles.css",
    "blocks": ["age", "sex", "regions", "risk_factors", "confirmed_symptoms"],
  }'

PDF Summary request parameters in body

The following PDF summary parameters can be added to the request parameter body when generating a PDF. All are optional. An empty body can also be sent. The list of all acceptable PDF parameters includes:

Response object

A PDF document with interview summary.

Errors when fetching PDF summary

{
  "detail": "Survey not found"
}