Pharmacy

The Truepill pharmacy APIs provide you access to fulfillment, insurance billing, prior authorization, and benefits investigation infrastructure.


Truepill makes accessing our entire nationwide pharmacy infrastructure easy. Find the documentation and getting started guides to build exactly what you want, fast. We'll handle the complexity of a regulated pharmacy industry across all 50 states. Let's get started building something great together.

In this guide, we will walk you through the three basic steps of getting medication delivered to your patient.

Step 1. Create a patient

Step 2. Send a prescription

Step 3. Create a fill request

Fulfillment API

Overview

The fulfillment API will allow you to efficiently get medications to your patient's door across all 50 states. We take the compliance and complexity of the process of your plate so you can focus on your patient experience.

With a focus on compliance and patient safety, our process puts your patients first, every step of the way. In this section, you will explore the concepts of a patient, prescription and fill request which are the three essential components of our fulfillment API.

Patient

Overview

The Truepill ecosystem begins by creating a patient record. It is the unifying object across our entire platform, and the entire patient journey revolves around the patient object. Patients have prescriptions and orders. Our mission is to build patient-first technology, so how could we start anywhere else?

Create a Patient

The /patient endpoint creates a patient record and returns a patient_token for you to reference in subsequent API requests that require this field.

Create a patient

Node

cUrl

Copied!

Success response

Copied!
Patient API reference →

Prescription

Overview

A valid prescription is required to dispense and ship medications to your patient. There are three different ways for Truepill to obtain a valid prescription described below. Depending on your specific use case, you can navigate down to the appropriate section for your pharmacy fulfillment needs.

Each of the solutions below results in a valid prescription in our pharmacy and a prescription object created in our system tied to your patient.


Electronic Prescription

A licensed US provider sends an electronic prescription or eRX (from within a EMR) into a Truepill pharmacy. This can be one of your own providers, one of ours, or a third-party provider.

Transfer Prescription

Your patient has a valid prescription at another pharmacy (i.e. Rite-Aid, Walgreens, CVS) and you provide instructions to Truepill to obtain and transfer this prescription in our pharmacy.

Direct Transfer Prescription

You have your own dispensing or non-dispensing pharmacy and want Truepill to ship medications to your patient. This is a programmatic option to transfer a prescription from your pharmacy to ours.


Electronic prescription

An electronic prescription (eRx) is the computer-based electronic generation, transmission and filing of a prescription. In the US, the accepted standard for eRx is the “SCRIPT standard,” governed by the National Council for Prescription Drug Programs (NCPDP).

A licensed US provider sends an electronic prescription or eRX (from within a EMR) into a Truepill pharmacy. This can be one of your own providers, one of ours or a third-party provider.



Matching a prescription to your patient

Matching the incoming electronic prescription is handled by our matching engine using relevant patient, prescription and provider identifiers. Once the prescription has been successfully matched to your patient, we generate a prescription_token, which is a unique identifier for the prescription object.

Prescription notify event

Copied!
Prescription notify API reference →

Transfer prescription

Overview

Your patient has a valid prescription at another pharmacy (eg. Rite-Aid, Walgreens, CVS) and you provide instructions to Truepill to obtain and transfer this prescription in our pharmacy.



In the Truepill API, the prescription transfer is initiated by you on behalf of your patient, who has opted in to receiving their prescription via a home delivery option like Truepill. Once the prescription has been transferred, you receive a webhook event notifying you of a prescription(s) successfully transferred into our pharmacy.

Create a transfer request

A transfer request can be created using our /transfer_request API endpoint. Truepill will provide a receipt confirmation of the request, but please note the subsequent webhook esvent notifying you of a successful transfer may take up to one to three days.

Create a transfer request

Node

cUrl

Copied!

Success response

Copied!

Success webhook event

Copied!

Failed webhook event

Copied!

Prescription notify event

Copied!

There are a number of reasons why a transfer request may fail. These reasons include (1) patient does not have a valid prescription on file at the pharmacy, (2) patient has no refills remaining on prescription, (3) a controlled substance that cannot be transferred by state Board of Pharmacy laws.

Transfer request API reference →

Transfer a prescription from a provider

As you can see above the two fields we require for a pharmacy-to-pharmacy transfer are the name and phone number of the pharmacy. Alternatively, you can also “transfer” a prescription from a doctor's office. This means instead of reaching out to the pharmacy, Truepill will reach out to the patient’s doctor to request a new prescription to Truepill. In this scenario, you would pass in the provider’s name and phone number into the transfer request.

Direct transfer prescription

Overview

A direct transfer is a pharmacy-to-pharmacy transfer of the prescription between your pharmacy and a Truepill pharmacy. This method works best for customers that operate their own pharmacies and are looking for a programmatic way to transfer a prescription. This approach does however require a digital copy of the original prescription.

And similar to a traditional transfer request, there are required fields related to the pharmacist transferring out the prescription, and the pharmacist transferring in the prescription.



Transfers vs direct transfers

In the Truepill ecosystem, transfers and direct transfers are two different flows albeit sharing certain similarities. A key difference is that a direct transfer is used when you own or operate the pharmacy that holds the prescription. Thus, think of a direct transfer as a programmatic transfer of a prescription between two trusted pharmacy entities - your pharmacy and ours.

Create a direct transfer

A direct transfer request can be created using our /direct_transfer API endpoint. Truepill will provide a receipt confirmation of the request, and a subsequent webhook event once the prescription has been saved into our Truepill pharmacy system.

Create a direct transfer

Node

cUrl

Copied!

Success response

Copied!

Success webhook event

Copied!

Failed webhook event

Copied!
Direct Transfer API Reference →

Open refill transfer File (ORTF)

Truepill can also support the industry standard open refill transfer file (ORTF) format. Most pharmacy point-of-sale systems will provide a version of the ORTF file format to transfer data between pharmacies and systems. Due to the slight differences between each ORTF file format across different systems, we don’t offer a public-facing API for this transfer method at this time. We can support this transfer format by working directly with your team.

A note about transferring controlled substances

State and federal regulations determine requirements for controlled substances. Transfer of a drug that is both state-controlled and federally controlled will be handled in accordance with whichever regulations are more stringent.

If moving prescriptions in one pharmacy from one internal computer system to another internal computer system (for example, an in-store upgrade), state regulations for transfers are not applicable as this is not a prescription transfer. Similarly, we are able to transfer controlled substance prescriptions between our pharmacies. If transferring from one pharmacy (you or a third party pharmacy) to Truepill, the transfer is subject to state and federal regulations.

Both parties also need to take into account how individual states may vary in their classification of controlled substances. What may be considered a Schedule 2 drug in one state may be considered a Schedule 3 in another state. It is the responsibility of the sending (you) and receiving pharmacies (us) to determine what rules apply.

Fill request

Overview

Now that you have a patient token and prescription token, it’s time to create a fill request. Think of fill requests as orders within the Truepill ecosystem where a medication refill is dispensed and delivered to your patient. A fill request can be created using our Fill Request API endpoint. Truepill will provide a receipt confirmation of the request, and several subsequent webhook events throughout the lifecycle of the order.

Conceptually, a fill request is just a set of instructions you are providing to Truepill related to a patient order. In addition to the product(s) being dispensed you will also provide details like shipping address, custom packaging requirements, OTC bundled products, and anything else needed to achieve your desired patient experience.

Create a fill request

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

Fill request API reference →

Creating a fill request

Node

cUrl

Copied!

Success response

Copied!

Our pharmacy fulfillment platform provides you full visibility into the status of all your orders. Thus, you will receive webhook events relating to the status of your order. Here’s a high level summary of four key webhook events in the fill request process:

  1. (1) Order success and shipping label generated
  2. (2) Order shipped
  3. (3) Order in-transit
  4. (4) Order delivered

Success webhook event

Copied!

Success webhook event

Copied!

Success webhook event

Copied!

Success webhook event

Copied!

There are a number of reasons why a Fill Request may be rejected by our pharmacy. The most common reasons include: (1) missing or invalid prescription (2) incorrect shipping address (3) various insurance rejection reasons.

Failed webhook event

Copied!
Fill request API reference →

Refills

Overview

The only difference between a refill and a first fill is that this time around, you already have a patient_token and prescription_token - so you are all set! Just send in a fIll request and follow the same process as before and repeat this until you have no remaining refills on a given prescription.

Managing refill quantities

Depending on whether your patients are paying for their prescriptions with cash or insurance, you have some control over the quantity of medication dispensed. For cash prescriptions, you can dispense multiple fills and custom quantities as needed. For example, let’s say you have a prescription on file for “11 refills of Atorvastatin 40mg, take 1 tablet a day.” Conceptually, you can think of this as 11 refills x 30 days/month x 1 pill/day = 330 pills. If your patient pays for 200 pills, you can specify a quantity of 30 using the quantity field as part of your fill request.

For insurance prescriptions, the payor will determine the appropriate quantity that you can dispense to the patient. Typically, this is a 30-90 day supply of medication. In the event you request a quantity greater than allowed by the patient’s insurance, we will dispense the maximum allowable limit and send the quanity_dispensed as part of your fill request webhook event.

Here is an example of a fill request and webhook event with deferring quantities.

Fill request with refill management:

Fill request

Node

cUrl

Copied!

Fill request webhook event with refill management:

Success webhook event

Copied!

Managing refill timing

When using our fill request API endpoint, it’s important to remember Truepill will never ship out a refill to your patient without an explicit new fill request. It is your responsibility to manage the timing of your fill requests to ensure your patients always have medications on hand. In general, we recommend issuing your next fill request 7-8 days before your patient runs out of medication. This is typically also the time window that insurance allows for billing the next refill of medication.

If you send a fill request too early for an insuranceibilled prescription, you will receive a “Refill Too Soon” error message from the payor, with a specific date that you can bill against insurance. Depending on your preference, we can hold this fill request until the refill too soon date arrives, or reject the fill request and await a new one sent by you after the refill too soon date passes.

Multi-dose packaging

Truepill can support a range of medication packaging types including standard vials, custom branded vials and bottles, branded single dose pouch packaging and multi-dose strip style packaging. You can specify the packaging type for your order using the medication_packaging_type field.

Fill request with multi-dose packaging

Node

cUrl

Copied!

Custom packaging

We’re here to represent your brand and customer packaging is a core part of that experience. Many customers provide their own packaging materials to our facilities. We can also design and procure custom packaging for you.

We can support a range of needs including different brand box types and styles, marketing collateral and inserts, new vs. existing customer packaging, new customer welcome letter, seasonal products and inserts, promotional and other brand materials, OTC product samples - just to name a few example of how our partners bring their brands to life with Truepill. You can use the packaging_configuration field in the fill request API to provide specific details of your packaging process for a specific order.

Fill request with custom packaging

Node

cUrl

Copied!

Over-the-counter (OTC) products

Truepill can support a broad range of non prescription OTC products in addition to the full formulary of prescription products. You can dispense an OTC product alone or a bundle of OTC products combined with you prescription medications. Some customers also choose to drop ship and store their OTC products in a Truepill facility for use during the pick and packing process for their orders. You can submit multiple OTC products as part of a fill request using the otc_products field

A prescription is not required for an OTC product - you do not need to pass in a prescription_token for an order that contains only OTC products.

Fill request with OTC products

Node

cUrl

Copied!