Onegevity Health Intelligence

This How-To applies to you if:

  • You wish your patients to receive lab testing and analysis, either by kits or by blood draw
  • You already have collected patient information using your own systems
  • You cannot or do not wish to use the Onegevity UI-Kit widgets for a user interface. For example:
    • You are not intending for users to interact with a website
    • You are building a backend-only data solution
    • You are implementing your own UI for presenting to customers

# Prerequisites

This How-To assumes that you have already taken care of understand the following:

  • How to authenticate to the Thorne API
  • How to construct Rest API calls or how to use one of our client SDK libraries

# Synopsis

The following is a high-level overview of the steps involved in the testing lifecycle. Specific API examples will be provided below to walk through the particulars of each step in detail.

# Register your patient

  • A valid patient record must be registered with Thorne utilizing our API
  • For the best and most accurate analysis, we always suggest making sure to provide as much information about the patients medications, health history, and lifestyle habits that you can
    • Since you are working directly with our API and not using our UI-Kit library for displaying our questionnaires, you will be responsible for collecting this information on your patients and translating it into our required data format to send to us.

# Create an order for your patient

  • An order in our system is a request for labwork and/or analysis services to be performed for a given patient
  • When creating the order, you specify which analysis package is to be performed for the patient
  • If the analysis package requires a sample collection kit, you have options as to how to get the kit to your patient:
    • You can manage your own inventory and control how and when your patients receive their kit
    • We can ship the kit to your patient, given their mailing address

# Activate kit

  • If the analysis package uses sample collection kits, the "kit activation" step must be performed to associate the specific collection kit with your patient
  • This involves finding the activation code printed physically on the kit and submitting an API request to associate that code with the patient's order

# Retrieve lab requisition form

  • If the analysis package requires an in-person blood draw performed by our partner labs, then this step must be performed to retrieve the approved lab requisition form before the patient can go get their blood drawn
  • There will be an initial delay of up to 8 hours while the necessary lab requisition is created and approved
  • Once approved our system will send a webhook notification indicating that the requisition has been approved and the form is available for download
  • The requisition form is a PDF file retrieved from the API

# Patient collects their sample

  • For kits, once the collection kit has been activated for the patient they may collect their sample and return using the provided shipping materials
  • For blood draws, once the requisition form is available the patient should bring a printed out copy of the form and visit a partner lab location to get their blood drawn

# Retrieve final analysis

  • Our results processing and analysis kicks off once we've received all results from the lab for a patient's order
  • When the final analysis is ready, we will send a webhook notification indicating that the results are ready and can be retrieved through the API

# An example: Gut Health

# Required patient information

The specifics of required patient information is documented in the interactive API documentation, but generally include:

  • A patient identifier that means something to your system (e.g. a medical record number, patient identifier, etc)
  • First and Last name
  • Date of Birth
  • Gender (sex assigned at birth)

# Desirable additional patient information

To help create the best possible results some additional patient demographic and lifestyle data should be provided if available. View the complete list of patient information fields and their possible values is available here.

# Step by step examples with the API

Below is a walk-through of example API requests and responses that you would expect to work with to request testing for your patient and retrieve the final results. Full documentation and additional examples of these endpoints and request/response objects are available in our API Reference Documentation.

# Step 1: Registering the patient record

In this example we'll assume that the source system has demographic information, current medications, and some amount of health history information. The integrator needs to translate this information from their source systems into the representations understood by the Thorne API and post to the patient endpoint. The required information is provided and we include the optional information we have available in the "healthProfile" section.

Here is an example request to the API to create a patient record:

POST /api/v1/patients

{
    "patientIdentifier": "MRN84327",
    "firstName": "John",
    "lastName": "Doe",
    "gender": "MALE",
    "dateOfBirth": "1973-12-05",
    "healthProfile": {        
        "RACE": "WHITE",
        "ETHNICITY": "NON_LATINO",        
        "BMI": 27.4,
        "SMOKER": "NO",
        "DAILY_ALCOHOL": 2,
        "EXERCISE_MINUTES_PER_WEEK": "90_TO_150_MIN"
    }
}

# Step 2: Creating an order for your patient

Now that we have a patient record registered, a request is made to create an order for the desired analysis package. In this case it's the Gut Health package which requires a sample collection kit. As mentioned above you can either use our fulfillment capabilities to ship kits to your patients or you can manage your own inventory and take care of that yourself.

# An example of creating an order where you are responsible for kit fulfillment

Note: for regulatory purposes, we require mailing address, email address, and phone number for patients. This is utilized to verify the patient lives in a location where we are permitted to perform theses services. Additionally this information is used by our clinical partners to reach out and contact the patient in the rare circumstance that there are highly irregular results that need immediate medical attention.

POST /api/v1/patients/MRN84327/orders

{
    "orderIdentifier": "ORD12356",
    "packageIdentifier": "GUTHEALTH",
    "patientInformation": {
        "address": {
            "streetAddress1": "12345 Example Dr.",
            "city": "Some Town",
            "region": "CA",
            "country": "US",
            "postalCode": "90210"
        },
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@email.com",
        "phoneNumber": "817 555 1212",
        "gender": "MALE",
        "dateOfBirth": "1973-12-05"
    }
}
# An example of creating an order, requesting kit fulfillment

When requesting kit fulfillment, you simply need to provide the shipping address, the shipping method to use, and identify who the recipient is. In this case, we will request that the kit is shipped to the patient at their same address.

POST /api/v1/patients/MRN84327/orders

{
    "orderIdentifier": "ORD12356",
    "packageIdentifier": "GUTHEALTH",
    "patientInformation": {
        "address": {
            "streetAddress1": "12345 Example Dr.",
            "city": "Some Town",
            "region": "CA",
            "country": "US",
            "postalCode": "90210"
        },
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@email.com",
        "phoneNumber": "817 555 1212",
        "gender": "MALE",
        "dateOfBirth": "1973-12-05"
    },
    "fulfillmentInformation": {
        "recipientFirstName": "John",
        "recipientLastName": "Doe",
        "recipientPhoneNumber": "817 555 1212",
        "shippingMethod": "GROUND",
        "shippingAddress": {
            "streetAddress1": "12345 Example Dr.",
            "city": "Some Town",
            "region": "CA",
            "country": "US",
            "postalCode": "90210"
        }
    }
}

# Step 3: Activating the kit

In this step we associate the activation code from a specific sample collection kit to the patient order we just created. How this linkage is established is dependent on what your process is. For instance you may provide a facility for patients to activate their kits using a mobile app or your website. Or if you are managing your own inventory of kits you may keep your own records of which kit is given to which patient. Either way, this is a crucial step in making sure that results are received and released to the proper patient in a timely manner.

Here is an example request where we associate the activation code of a Gut Health test to the patient order we just created above

PATCH /api/v1/patients/MRN84327/orders/ORD12356

{
    "kitActivations": [{
        "packageElementIdentifier": "GUTHEALTH_KIT",
        "activationCode": "00184592"
    }]
}
# Special Note

In some cases where you are managing your own inventory of kits, you may know at the time of order creation what kit you will be giving to your patient. If that is the case, you can combine kit activation and order creation in one API request by including the kitActivations property in your order creation request.

# Retrieving the final analysis results and reports

Once the lab has received the kit and sequenced the patient's sample and we have performed our analysis on the output, the results are ready for retrieval.

To retrieve the completed final report for the Gut Health analysis of our example above, it's a two step process:

GET /api/v1/patients/MRN84327/orders/ORD12356/reports

{
    "pageNumber": 1,
    "numberOfElements": 1,
    "totalNumberOfElements": 1,
    "reports": [
        {
            "id": 671,
            "name": "Gut Health",
            "type": "patient-facing",
            "createdTimestamp": "2022-08-18T04:43:28Z"
        }
    ]
}

The details endpoint retrieves all of the content that is used when displaying a report, including test results analysis and interpretation as well as recommended interventions. You'll also note that there is a related document listed as well, the Full Microbe Community, which is a CSV file of the relative abundance of all microbes identified in the patient's sample. The CSV file can be downloaded using the URL provided with a simple GET request.

GET /api/v1/patients/MRN84327/reports/671/details

{
    "id": 671,
    "name": "Gut Health",
    "type": "patient-facing",
    "createdTimestamp": "2022-08-18T04:43:28Z",
    "summarySection": {
        ...
    },
    "bodySections": [ ... ],
    "relatedDocuments": [
        {
            "id": 39,
            "name": "Full Microbe Community",
            "mediaType": "text/csv",
            "createdTimestamp": "2022-08-18T04:43:37Z",
            "downloadUrl": "..."
        }
    ]
}

# Example output files

# Report details

A complete example of the content of a Gut Health report details endpoint can be viewed here.

# Full Microbe Community

A complete example of the Full Microbe Community breakdown can be downloaded here.