Diagnostics API

The Truepill Diagnostics API provides access to our fulfillment, kit registration, and lab results infrastructure. Powered by Truepill’s national network of CLIA certified labs, you are enabled to programmatically order from a menu of over 100 at-home lab tests.

Truepill makes ordering at-home lab tests easy, secure, and reliable.

About Our Labs

Truepill integrates with multiple third-party accredited labs, enabling rapid programmatic access to a broad range of at-home lab tests. All labs in Truepill’s network are CLIA-certified. The Clinical Laboratory Improvement Amendments (CLIA) regulate laboratory testing and require clinical laboratories to be certified by the Center for Medicare and Medicaid Services (CMS) before they can accept human samples for diagnostic testing.

We ensure the highest quality standards by providing ongoing reviews and assessments for labs on our platform. We also have the capability to recruit a specialized lab specifically for your diagnostics needs. We work with customers to validate new tests with our labs in the event the test you want to run does not exist.

Your Lab Kit

Truepill’s Diagnostics API supports over 100 at-home lab tests. We will work with you to design the best lab kit for your patients with a focus on ease, safety, and care.

After designing your lab kit, a unique kit id will be provided to you to place an order for your unique lab kit. You will use this kit id to place your order. After a successful order is placed, you’ll be returned a kit id which is the identifier of the kit being shipped to your patient.

Lab requisition requirements vary by test and state. Truepill can ship at-home lab tests in accordance with Federal and State regulations. Some tests and states require physician approval while others allow patient-authorized testing. We will work with you to understand when physician approval is required for your program and when it is not.

In this guide, we will walk you through how to deliver diagnostic tests to your patient.

Create a Patient

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 tests and orders. Our mission is to build patient-first technology, so how could we start anywhere else?

To create a patient, make a request to PUT https://api.truepill.com/v1/patient

Create a patient



Success response

View Create Patient API Reference →

Request a Lab Kit

With a patient token and optional physician information, you can place a lab kit order. A lab kit order is a request within Truepill’s ecosystem to pack and deliver a lab test to your patient. The Lab Order endpoint will provide a confirmation of receipt.

The physician information coupled with the patient information and test information is what one would traditionally refer to as a requisition. As some diagnostic tests do not require physician approval, we have made physician information an optional field. If the test in question requires physician approval, a validation error will be returned.

Do you want Truepill to create requisitions for you? See our Consult API for more information.

Create a Lab Order

A lab order can be created using our POST /v0/orders endpoint. Truepill will provide a receipt confirmation of the request, and multiple subsequent webhook events through the lifecycle of your order. In the case where a requisition is required, we collect information about the authorizing physician. It is your responsibility to ensure that this information is accurate and that the physician is verified.

Create a Lab Order



Success response


Registering a Lab Kit

Registration associates a specific lab kit with a specific patient. Depending on the program, we can register the kit for you when we ship it. You also have the option to use our registration endpoint to register your own kits.

To register a kit for an existing order, you can PUT /v0/orders/{order_id}/kit_serial

Registration for Existing Order Payload


Alternatively, if you already have the kit, or are doing your own fulfillment, you can specify the kit serial during order creation. For this flow, we expose a “register” endpoint: POST /v0/orders/register. The payload of this endpoint is the same as the order creation endpoint, with the inclusion of a “kit_serial” field, and the “address” field is no longer required (as we do not need to ship a kit).

Registration for New Order Payload



Receiving Order Status Updates

The Truepill fulfillment platform provides you full visibility into the status of your orders. You will receive webhook events related to the status of your order, shipment, and lab return. When a lab kit is shipped from Truepill facilities and requires processing in a lab, the kit includes a return label for the patient to easily ship their specimen to the appropriate lab for testing.

Here is a high level summary of the key webhook events in the lab order process:

  1. Order success
  2. Order shipped
  3. Order in-transit
  4. Order delivered to patient
  5. Order shipped to lab
  6. Order in-transit to lab
  7. Order delivered to lab
  8. Lab accessed kit
  9. Results available

Order Success Webhook Event


Order Shipped Webhook Event


Lab Accessed Kit Webhook Event


Lab Results

Get Lab Results

Lab results are ready after the lab has processed the specimen and published the results in a lab report. You will be notified when the lab results are ready by the webhook events provided through the lifecycle of the lab kit.

Once results are ready, you will be able to get lab results using the GET /v0/orders/{orderId}/results API endpoint. The structure of the results is dependent on the type of test being performed.

Lab Accessed Kit Webhook Event


Result Response




Our portfolio


API Documentation





© Truepill 2021
All Rights Reserved.