Intent Survey

• Overview
• Prerequisites
• Usage
• Intent Data Model
• Implementation example

Overview

The Intent Survey feature allows patients (or a provider’s employees in, e.g., a call center setting) to report what their initial plans and how those plans change after receiving their triage recommendation. It is an extension of the basic interview flow.

The Intent Survey consists of two core elements:

• a pre-interview question about the user’s intent
• a post-interview question about the user’s intent

Both of these elements can also be compared with the triage recommendation itself.

Prerequisites

The Intent Survey can only be used with interview-based flows that use Interview-Id. More information about Interview-Id may be found here.

Usage

The Intent Survey can be used to collect patient intent and send it to the interview feedback endpoint, which responds to POST requests like this one:

curl "https://api.infermedica.com/v3/interviews/feedback" \
    -X "POST" \
    -H "App-Id: XXXXXXXX" -H "App-Key:
 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
 	-H "Interview-Id: 46d9d342-3d90-42fa-af01-e72ad0142aae" \
    -H "Content-Type: application/json" -d '{
    	"paitent_intent_before": {
          "type": "consultation",
          "channel": {
            "category": "in_person"
          },
          "sub_type": {
            "category": "custom",
            "custom_label": "gastroenterologist"
          }
        },
        "patient_intent_after": {
          "type": "self_treatement_at_home"
        }
  }'

We recommend gathering the intent data from both before the start of the interview and after it’s finished. These are represented in the request body as fields called patient_intent_before and patient_intent_after respectively.

Intent data model

The request body accepts objects with fields patient_intent_before and patient_intent_after. Both fields must be present. If a patient fails to fill out one of the fields, a special intent type called unknown should be used in place of the missing data. For instance, if the patient fails to fill out the patient_intent_after field, unknown should be entered for that field. Both share the same structure, consisting of up to three fields. The most important field is type, which represents the kind of care that the patient expects to need.

Available types include:

• self_treatment_at_home

The patient expects no need for professional care.

• consultation

The patient expects a consultation with a medical professional. Objects of this type may include additional, optional fields:

• channel

The expected consultation medium. An object with fields:

• category

A required field. Allowed values are: in_person, provider_application, chat, audio, video, not_sure, custom

• custom_label

Required if category is custom. A label for a custom option not included in the above categories.

• sub_type

Additional detailed type. An object with fields:

• category

A required field. Allowed values: primary_care_physician, nurse, physiotherapist, psychologist, dietician, specialist_doctor, custom, not_sure

• custom_label

Required if category is custom and ignored for other categories. A label for a custom option not included in the above categories.

• urgent_care_center

The patient expects to be directed to an urgent care center.

• emergency_care

The patient expects to be directed to an emergency care facility. Objects of this type may include an additional, optional field:

• sub_type

Additional detailed type. An object with fields:

• category

Required field. Possible values: with_ambulance, without_ambulance, custom, not_sure

• custom_label

Required if category is custom and ignored for other categories. A label for a custom option not included in the above categories.

• not_sure

No specific expectation.

• unknown

A special value indicating that an intent could not be gathered from a patient. For example, if the patient doesn’t finish the interview, this type should be used for patient_intent_after.

• custom

An expectation not included in the above options. For this type, the object must include another required field:

• custom_label

A label for a custom option not included in the above categories.

All custom_label fields in the above structure have a limit of 160 characters.

Response

A properly constructed Intent Survey request will result in a response with:

• a 200 status code
• response body containing an empty JSON

Invalid request body will produce a response with:

• a 400 status code
• response body containing an error field, with a description of the problem

In the case of an error response from our server or transient network errors, we recommend saving the Intent Survey data locally and retrying the request later.

Implementation example

In this application example, on the first screen a patient is asked whether they consider consulting a healthcare professional. If they were to choose “Don’t know” or “No”, then the following intent would be logged:

{
      "patient_intent_before": {
          "type": "not_sure"
      },
(...)
}
{
      "patient_intent_before": {
          "type": "self_treatment_at_home"
      },
(...)
}                   

But if the user expressed an intent to see a medical professional, they’d be presented with another screen that tries to capture more details.

Should the user decide to choose the first option, they’ll be presented with a third and final screen.

After the user chooses the middle option, to see a doctor in person, the process ends and we’re left with the initial intent, or patient_intent_before. Coded, it’ll look like this:

{
      "patient_intent_before": {
          "type": "consultation",
          "channel": {
            "category": "in_person"
          }
          "sub_type": {
            "category": "primary_care_physician"
          }
      },
(...)
}

When the interview finishes and the patient receives their recommendation, they’ll be presented with an additional question that tries to capture their plan following the interview.

The patient clicks “Recovering at Home”, indicating that they decided to stay at home and now we have our patient_intent_after, meaning we’re ready to send the whole request:

POST /v3/interviews/feedback

Required header: Interview-Id

Request:

{
      "patient_intent_before": {
          "type": "consultation",
          "channel": {
            "category": "in-person"
          }
          "sub_type": {
            "category": "primary_care_physician"
          }
      },
      "patient_intent_after": {
          "type": "self_care_at_home"
      }
}