Truepill logo
Docs
Introduction
Pharmacy
Telehealth

Introduction

The Truepill API platform provides you convenient access to our entire pharmacy and telehealth infrastructure.

Welcome to the Truepill API. Our mission is to put patients first. We believe fundamentally that having open and accessible APIs for healthcare is critical to empower our partners to deliver world-class patient experiences.

We’re thrilled to have partners like you that are looking to revolutionize the patient experience. Our API platform is central to our business and we’re excited for you to get started. We hope your integration experience is smooth and if you have any questions please contact our Sales Team.

What is an API?

If you’re thinking of active pharmaceutical ingredient, you wouldn’t be incorrect! Here however, we will focus on technology APIs and how they can transform your patient experience.

The Truepill API is a powerful and robust RESTful JSON based API. This API will give you the ability to access our healthcare infrastructure on both the pharmacy and telehealth sides of our business.

This getting started guide is organized into two parts: our pharmacy API and our telehealth API. You can also dive into our full API reference documentation at any time.

HIPAA and security

Overview

Truepill takes security and confidentiality of PHI very seriously. We ensure your data integrity is a top priority - from the moment you initiate an API request, all the way to when your patient receives medication from us.

Truepill uses a set of policies and procedures to safeguard our physical and technical infrastructure to maintain compliance with the HIPAA Privacy Rule, Security Rule, Transactions and Code Sets Rule, and their implementing regulations.

Truepill is a Covered Entity. For more information, Truepill also publishes a Privacy Policy, Notice of Privacy Practices and Terms and Conditions.

Business associate agreement

Truepill uses a standard business associate agreement with many of our partners, and may execute customized agreements with large health systems, health plans or PBMs (payers) and pharmaceutical manufacturers.

Security assessments

Security and privacy, along with regulatory compliance are core pillars of our business. We maintain an active review program, and employ professional third-party auditors to evaluate our effectiveness.

Our services have also been evaluated and assessed by many of the largest providers, health plans and manufacturers in the industry. We welcome our partners to conduct their own assessment, including security audits, site reviews and other measures.

Questions or concerns about our security or privacy program may be directed to our Privacy Officer by contacting legal@truepill.com.

Truepill uses trusted HIPAA compliant cloud infrastructure. All API requests are transmitted over TLS 1.2 protocol and all data is encrypted in transit and at rest.

Authentication

The Truepill API uses key based authentication. Requests are authenticated using basic access authentication.

Provide your API key in an authorization HTTP header for all requests. If you do not pass in an authorization HTTP header with a valid API key, your requests will not authenticate successfully.

Authentication API reference »

decorative, blank space

Making requests

In order to access the Truepill API, you will need an API key which will be provisioned and provided to you during the onboarding process. You will be given two unique keys: a sandbox key and a production API key.

As per RESTful design patterns, the Truepill API implements standard HTTP actions: GET, POST, PUT, DELETE. When making requests, arguments can be passed as params, form data or JSON with correct content-type header.

Requests must be made over HTTPS. Any non-secure requests are not redirected (HTTP 302) to the HTTPS equivalent URI.

Base request URL:
https://api.truepill.com/v1/

Webhook events

Overview

Webhook events are the way Truepill communicates all asynchronous events and status changes related to your API requests. As part of your integration, you will be required to set up a HTTP webhook URL that Truepill will POST updates to.

Webhook events send the latest known data for a request at the time of sending, formatted in accordance with the request resource. This way, you are guaranteed to receive the most up-to-date status of any request.

Managing your webhook endpoint

You can set, manage, and update your webhook event URL in your developer account or by using our customer endpoints. Using webhook events is optional, but strongly suggested as it is the only way to receive real-time status changes for all your requests.

Securing your webhook endpoint

You can secure your webhook endpoint using basic access authentication where Truepill will reference a key in the authorization header of every POST request to your webhook endpoint. Alternatively, you may choose to white-list the Truepill IP address range. These security measures are highly recommended, but are not required.

Token management

Our webhook events will return token representations of different objects with high level details. Our most common tokens include the patient_token and prescription_token. Using tokens ensures we limit the amount of patient identifiable data sent using webhook events.

Request vs. notify webhook events

There are two types of webhook events sent by the Truepill system. Request events are asynchronous events that will always reference a request ID from a previous request you have made. Notify events on the other hand are not tied to a request made by you but may be relevant to your specific workflow. Below are two examples of webhook event types explained in greater detail later:

Shipment success webhook event:

icon webhook success

Success webhook event


{
  "request_id": "fill_request_991e90fa6b367cf72032",
  "timestamp": 1590800222,
  "callback_type": "SHIPMENT",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "status": "DELIVERED",
    "message": "Your shipment has been delivered at the destination mailbox.",
    "eta": "2020-06-02T00:54:31.838Z",
    "tracking_number": "43904456187100000000000000",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000",
    "carrier": "usps"
  }
}
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",
    "transfer_prescription_token": "z3q2jr23",
    "location": "Hayward, CA"
  }
}

Webhook events API reference »

Errors

Our API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON. The various HTTP status codes we might return are listed in our API reference.

Additionally, different API endpoints have specific errors and error codes related to that endpoint. These endpoint-specific errors are covered in more detail throughout this guide and as part of our full API reference.

Errors API reference »

decorative, blank space

Environments and testing

You can access two separate environments, sandbox and production using the same base request URL. You will determine which environment you are looking to access by using either your sandbox or production API key. The only functional difference between the two environments is that the sandbox environment has fake data and simulation error events which you can use to test the end-to-end experience.

decorative, blank space