Intent Survey

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.

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.

Usage

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: d083e76f-3c29-44aa-8893-587f3691c0c5" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_intent_before": {
      "type": "consultation",
      "channel": {
        "category": "in_person"
      },
      "sub_type": {
        "category": "custom",
        "custom_label": "gastroenterologist"
      }
    },
    "patient_intent_after": {
      "type": "self_treatment_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 attributes called patient_intent_before and patient_intent_after respectively.

Request

The request body accepts objects with attributes patient_intent_before and patient_intent_after. Both attributes must be present. If a patient fails to fill out one of the attributes, 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 attribute, unknown should be entered for that attribute. Both share the same structure, consisting of up to three attributes. The most important attribute 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 attributes:

  • channel – the expected consultation medium; an object with attributes:

    • category – a required attribute; one of: 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 attributes:

    • category – a required attribute; one of: primary_care_physician, nurse, physiotherapist, psychologist, dietician, specialist_doctor, custom, not_sure,

    • custom_label – a label for a custom option not included in the above categories, required if category is custom and ignored for other 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 attribute:

  • sub_type – additional detailed type. An object with attributes:

    • category – required attribute; one of: with_ambulance, without_ambulance, custom, not_sure,

    • custom_label – a label for a custom option not included in the above categories, required if category is custom and ignored for other categories,

• not_sure – no specific expectation,

• unknown – a special value indicating that an intent could not be gathered from a patient, e.g. 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 attribute:

  • custom_label – a label for a custom option not included in the above categories.

All custom_label attributes 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 attribute, 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 then the following intent would be logged:

{
  "patient_intent_before": {
    "type": "not_sure"
  },
  ...
}

If they choose No then the intent logged would be:

{
  "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:

{
  ...
  "patient_intent_after": {
    "type": "self_care_at_home"
  }
}

and we’re ready to send the whole request:

curl "https://api.infermedica.com/v3/interviews/feedback" \
  -X "POST" \
  -H "App-Id: XXXXXXXX" \
  -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Interview-Id: d083e76f-3c29-44aa-8893-587f3691c0c5" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_intent_before": {
      "type": "consultation",
      "channel": {
        "category": "in-person"
      },
      "sub_type": {
        "category": "primary_care_physician"
      }
    },
    "patient_intent_after": {
      "type": "self_care_at_home"
    }
  }'