Docs
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 off 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.
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?
The /patient endpoint creates a patient record and returns a patient_token for you to reference in subsequent API requests that require this field.
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 an 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. 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.
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 API reference »
Overview
Your patient has a valid prescription at another pharmacy (eg. 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.
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.
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 event notifying you of a successful transfer may take up to one to three days.
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.
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.
Direct transfers
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.
Direct transfer API reference »
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.
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.
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.
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:
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.
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.
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 quantity_dispensed as part of your fill request webhook event.
Here is an example of a fill request and webhook event with deferring quantities.
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 insurance billed 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.
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.
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 examples 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.
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.
