Documentation
Engine API
Build your solution
Intent Survey

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.

ℹ️

Using the Intent Survey feature should be considered if an organization wants support in:

  • comparing pre- and post-interview user intent
  • converting or changing patient behavior
  • utilizing another method of segmenting their users
  • driving smarter user acquisition
  • gaining more overall population health insights

For more use cases or information, please get in touch with our team (opens in a new tab).

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

Screenshot

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:

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

If they choose No then the intent logged would be:

JSON
{
  "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.

Screenshot

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

Screenshot

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:

JSON
{
  "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.

Screenshot

The patient clicks Recovering at home, indicating that they decided to stay at home, and now we have our patient_intent_after:

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

and we’re ready to send the whole request:

cURL
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"
    }
  }'