Consultation response

After logging in, accepting terms, and submitting the initial information, the API enters the consultation state. In this state, it keeps asking follow-up questions about symptoms until it can determine an outcome — or concludes that no outcome is possible given the information provided.

Let's explore how the API asks these questions and how you should handle them.

Question

Understanding the structure of a question object is essential for rendering consultation screens correctly and sending valid responses.

  "question": {
    "type": "symptoms",
    "messages": [
      {
        "value": "Do you have any of these symptoms?",
        "type": "HEADER",
        "format": "PLAIN_TEXT"
      }
    ],
    "choices": [
      { "id": "C0006325", "text": "Teeth grinding" },
      { "id": "C0018681", "text": "Headache" },
      { "id": "C0041105", "text": "Difficulty opening mouth" },
      { "id": "C0015468", "text": "Face pain" }
    ],
    "constraints": {
      "min_selections": 0,
      "max_selections": 4
    }
  }

Let's look at the building blocks of this object.

Type

The type of question can impact how it's rendered, so let's look at all the possible values:

• numeric - expects an input field with an integer number.
• text - expects a free text field.
• autocomplete - a special type, explored in more depth in another section.
• Other types (choice, generic, health_background, factor, symptom, symptom_choose_one, symptoms) - single or multi-select options depending on constraints.

When sending the response to this question, make sure you include the original type value.

Messages

Messages are used throughout the API to provide contextual information or metadata related to the current step.

    {
      "value": "Before you begin",
      "type": "HEADER",
      "format": "PLAIN_TEXT"
    }

The value represents the message text, while type and format carry the information on how to display or render it. Here are the possible values:

Type:

• HEADER - display as a title or heading.
• PARAGRAPH - display as normal text.
• INPUT_HINT - display as a placeholder for input fields.
• BULLET_POINT - display in a bulleted list.
• OTHER - anything that doesn't fit the above.

Format:

• PLAIN_TEXT - unformatted text.
• MARKDOWN - markdown syntax.
• HTML - HTML content.

📘

For MARKDOWN, make sure your implementation correctly renders links , bolding, italics, new lines (\n) and bullet points (-).

Choices

Each available choice is represented as a simple object containing an id and a text.

Use the text for displaying it to the users, and the id for answering on the API.

Constraints

Constraints define limits on user selections or input values. If the submitted response violates these, the API returns a 400 Bad Request.

Use constraints programmatically to:

• Restrict user input (e.g., min/max selections).
• Adjust UI controls (radio buttons vs. checkboxes).
• Prevent invalid submissions client-side.

Example:

"constraints": {
  "min_selections": 0,
  "max_selections": 4
}

Conversation Details

The conversation_details type shows some metadata about the current state of the consultation.

{
  "conversation_details": {
    "step_back_possible": true,
    "report_possible": false,
    "scenario": "consultation_questions",
    "conversation_ended": false,
    "symptoms_summary": {
      "selected": [
        {
          "cui": "C0751409",
          "name": "Loss of strength/power in the arm (upper arm or elbow or forearm)"
        }
      ],
      "excluded": [
        {
          "cui": "C0575810",
          "name": "Loss of strength/power in the wrist or hand(s)"
        }
      ]
    },
    "progress": {
      "stage": "Assessment",
      "percentage": 30
    }
  }

Step back possible

Indicates whether the user can navigate backward to the previous question. If false, hide the Back button.

Report Possible

When true, a consultation report can be generated via the report endpoint. Always check this flag before calling the report API.

Conversation ended

Indicates that the consultation has finished. This is usually true when report_possible is true, but note that some flows may end early without a full report.

Symptoms Summary

Shows the previously selected and excluded symptoms. Mostly useful for the autocomplete scenario.

Conversation progress

Information that would allow you to render a progress bar, offering a name as a stage property and an integer from 0 to 100 named percentage