Truepill logo
Docs
Introduction
Pharmacy
Telehealth

Consult API

Overview

The Truepill telehealth API will allow you to efficiently leverage a nationwide provider network for a clinical consult by a licensed provider in the state where your patient resides.

The process starts when you request a consult, and similar to our pharmacy API endpoints, you will receive notifications about your requested consult through our webhook events. These webhook events will provide updates on the lifecycle of your clinical consult.

Note: If you are integrating with both our telehealth and pharmacy services, you may notice the same "provider" is referred to as a "prescriber" in our pharmacy APIs (with the same NPI). This is intentional, as naming the provider a "prescriber" in the context of our consult request APIs would be suggestive of a prescription. This would be inconsistent with our clinical guidelines as they pertain to our telehealth platform. Our providers make all clinical decisions on diagnosis, treatment and prescribing of medications.

About our providers

We work with a network of 4,000+ licensed US providers ranging from physicians, physician assistants, and nurse practitioners with a capacity to see 6.5 million patients a month on our platform. We ensure the highest quality of virtual care by providing ongoing reviews, training and assessments for providers on our platform. We also have the capability to recruit a specialized network designed specifically for your therapy area or clinical needs.

Important note: Truepill does not directly employ or contract with any providers in our network. Instead, we work with third-party provider networks and physician groups that can diagnose, treat, and prescribe for your patient population. These providers are all part of licensed professional medical corporations who are independently owned and operated. For more information please contact legal@truepill.com

Types of consults

The two most common types of virtual visits are asynchronous and synchronous consults.

Asynchronous consult

An asynchronous consult is a clinical consult where a provider can asynchronously review clinical data from your patient typically submitted in the form of a patient questionnaire. This questionnaire can be reviewed asynchronously and used to diagnose, treat and prescribe. If follow up questions are needed, a provider can request additional information from the patient.

Synchronous consult

A synchronous consult is a clinical consult where a provider is synchronously communicating with your patient - either by phone or video conference. Some states require that all telehealth visits take place using a synchronous form of communication, and asynchronous consults are not permitted in these states.

Note: Due to the rapidly evolving and constantly changing telehealth regulatory landscape, we do not publish compliance or regulatory guidance in our API docs. When working with our clinical team, we can advise on the current up-to-date regulations on a state-by-state basis.

Clinical protocol review

When you decide to leverage our provider network, you will be required to submit a clinical protocol for review by our clinical team. If you do not have a clinical protocol or guidelines, our team can create one for your specific needs. This ensures that every clinical consult on our platform maintains the highest quality of care for every patient. Your patients' safety and wellbeing is our top priority and our entire API platform is built with this in mind.

You will not be able to initiate your first consult request before having a valid and approved clinical protocol. Once this protocol has been designed and developed, we can work with you to ensure you successfully set up your health questionnaire.

Bring your own provider (BYOP)

You can bring your own providers (BYOP) to the Truepill platform and leverage our telehealth-first EMR platform for your needs. This approach is commonly used by our partners that have their own providers but need the tools, technology and infrastructure to re-imagine their patient experience. Depending on your needs, you may also choose to leverage Truepill’s built-in notification system that alerts your provider when an action is needed (eg new consult, patient message or follow-up consult). Please discuss your specific configuration needs with the Truepill team.

Assigning a provider

Assigning a licensed provider to your consult request is handled seamlessly behind the scenes by our technology. If you are looking to bring your own providers onto our platform, please talk to our team about utilizing our EMR platform and programmable EMR APIs.

This process of matching a high-quality provider to your consult request depends on a variety of factors, including the specialization location and availability of the provider. We manage the entire process of notifying the provider of your consult request. We ensure completion of this consult within our SLA guarantees.

Once a provider is assigned to your consult request, you will receive a webhook event notifying you of the assigned provider.

Consult workflow status

There are a number of stages and steps involved in the lifecycle of your consult request. Below is a summary of the most common status updates you should become familiar with during your integration journey:

Status
Definition
created
Consult Request has been created and is waiting assignment
assigned
Consult Request has been assigned to a licensed provider
unassigned
Consult Request has been unassigned from a provider
accepted
Licensed provider has accepted the Consult Request
rejected
Licensed provider has rejected the Consult Request
started
Licensed provider has started the Consult
completed
Consult Request has been completed
abandoned
Licensed provider has abandoned the Consult
expired
Consult Request has expired
cancelled
Consult Request has been cancelled

Create a consult request

A consult request can be created using our /consult_request API endpoint. Truepill will provide a receipt confirmation of the request, and multiple subsequent webhook events throughout the lifecycle of your consult.

icon code

Create consult request


const body = {
 patient_record_token: '4526d90a',
 consult_url: 'https://www.telehealth.com/survey/4cb4d7z/',
 patient_location: 'CA',
 provider_id: 93832939,
 metadata: 'cfe146'
}


fetch('https://api.truepill.com/v1/consult/request', {
 method: 'POST',
 headers: {
   Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
   'Content-Type': 'application/json'
 },
 body: JSON.stringify(body)
})
 .then(response => response.json())
 .then(response => console.log(response))
icon success

Success response


{
 "request_id": "consult_request_bd6825a9d66a49b3d7a7",
 "timestamp": 1592183925,
 "status": "success",
 "details": {
   "message": "Your consult request has been received successfully and will now be processed.",
   "metadata": "cfe146",
   "patient_record_token": "4526d90a"
 }
}

Our telehealth platform provides full visibility into the status of your consults. You will receive a series of webhook events relating to the status of your consult.

icon webhook success

Success webhook event


{
 "request_id": "consult_request_bd6825a9d66a49b3d7a7",
 "timestamp": 1592183925,
 "status": "success",
 "details": {
   "message": "Your consult request has been received successfully and will now be processed.",
   "metadata": "cfe146",
   "patient_record_token": "4526d90a"
 }
}

Consult assigned webhook

icon webhook success

Success webhook event


{
 "request_id":"consult_request_bd6825a9d66a49b3d7a7",
 "timestamp": 1581019462,
 "callback_type": "CONSULT",
 "status": "assigned",
 "details": {
   "message": "A Licensed provider has accepted the Consult Request",
   "provider": "Dr. Strange",
   "metadata": "cfe146",
   "patient_record_token": "4526d90a"
 }
}

Consult started webhook

icon webhook success

Success webhook event


{
 "request_id":"consult_request_bd6825a9d66a49b3d7a7",
 "timestamp": 1581019462,
 "callback_type": "CONSULT",
 "status": "started",
 "details": {
   "message": "Licensed provider has started the Consult",
   "provider": "Dr. Strange",
   "metadata": "cfe146",
   "patient_record_token": "4526d90a"
 }
}

Consult completed webhook

icon webhook success

Success webhook event


{
 "request_id":"consult_request_bd6825a9d66a49b3d7a7",
 "timestamp": 1581019462,
 "callback_type": "CONSULT",
 "status": "completed",
 "details": {
   "message": "Consult Request has been completed",
   "provider": "Dr. Strange",
   "metadata": "cfe146",
   "patient_record_token": "4526d90a"
 }
}

Notify Rx webhook

icon Notify_Rx webhook success

Prescription notify event


{
 "timestamp": 1581019462,
 "callback_type": "NOTIFY_RX",
 "details": {
   "medication_name": "Atorvastatin 40 mg tablet",
   "prescriber": "Dr. Strange",
   "prescription_token": "z3q2jr",
   "patient_token": "4526d90a",
   "patient_token_duplicates": [],
   "location": "hayward"
 }
}