How to use this document

This page is intended to provide help to integrators who want to exchange survey data between their systems and Thorne's API. Normally we recommend using the UI-Kit Survey component which gives integrators an off-the-shelf web interface for patients to interact with to both collect answers to survey questions as well as submit those answers in the appropriate format to Thorne's API.

This document is for integrators who are not using a web UI and want to read and write patient data that is normally captured through the survey APIs.

Important survey concepts

Surveys are used to collect self-reported information from patients and record the results in the patients health profile records. Internally, all health profile data is stored as key-value pairs. The keys are unique identifiers in Thorne's system that represent the individual data element being captured by a question on the survey and the value is typically another unique identifier representing a specific choice the patient made when answering that question. In cases where the question is a free text entry, then the value is whatever the patient typed into the survey.

A patient can fill out a survey at any time and their health history will be updated with their most recent answers. All historical answers to survey questions are kept in the patient's health history, but their most recent answers will be used when performing analysis and data processing.

Submitting survey responses

Integrators wishing to submit survey responses to Thorne's API have a couple of options, but the simplest one is to call the Update Patient endpoint and pass in the key-value pairs. This method will update the patient's health history with new answers to all the questions provided. All other existing health history data will remain unmodified.

For example:

PATCH /api/patients/MRN358965

{
    "healthProfile": {
        "SMOKER": "FALSE",
        "ANXIETY": "TRUE",
        "DAILY_ALCOHOL": 3
    }
}

Retrieving survey responses

Similarly, the easiest way to retrieve the patient's current health history is to retrieve the healthProfile data from the patient detail endpoint

For example:

GET /api/patients/MRN358965

{
    "id": 100005,
    "patientIdentifier": "MRN358965",
    "firstName": "Patient",
    "lastName": "Name",
    "gender": "MALE",
    "dateOfBirth": "1987-08-04",
    "healthProfile": [
        {
            "attribute": "SMOKER",
            "label": "Currently smokes?",
            "valueType": "BOOLEAN",
            "value": "FALSE",
            "createdTimestamp": "2022-06-16T18:04:31Z"
        },
        {
            "attribute": "ANXIETY",
            "label": "Anxiety",
            "valueType": "BOOLEAN",
            "value": "TRUE",
            "createdTimestamp": "2022-06-16T18:04:31Z"
        },
        {
            "attribute": "DAILY_ALCOHOL",
            "label": "Daily Alcohol",
            "valueType": "INTEGER",
            "value": "3",
            "createdTimestamp": "2022-06-16T18:04:31Z"
        },
        ...
    ]
}

Mapping data elements

The primary challenge for integrators not using the off-the-shelf survey component provided by the UI-Kit is mapping data from their own systems into the domain and format required by the Thorne API. This exercise typically involves mapping how the data is stored in the source system and how it can be mapped to the data elements and their possible values as defined in Thorne's system.

In order to aid in that process, a listing of the questions asked in Thorne's default health profile survey is provided here along with the definitions of the corresponding data elements and their possible values. Using this resource, integrators can construct the key-value pairs necessary to update patient health history with answers to these questions using data from their own systems.