Prescribing & ordering medications

Prescription medications can be requested on behalf of Capable Health Patients by using our partner telehealth platform MD Integrations (MDI). You can optionally fulfill these prescriptions using mail-order pharmacy Curexa, or using pharmacies located near your Patients. Capable also supports creating an MDI Patient Case without specifying medications, when a doctor consultation is needed to determine what kind of care a Patients needs. Payments can be collected using Capable’s Stripe Integration or externally. Below, we walk through the steps necessary to set up these integrations with Capable.

Please note that both MDI and Curexa provide sandbox credentials for testing. It is highly recommended to test the functionality of these integrations in your sandbox before using them in production.

Set up an account with MDI

First, you will need to create an account directly with MD Integrations.

Next, you’ll need to add the medications and compounds you want to make available for MDI to prescribe to your Patients in the MDI admin portal. To add the medications, you’ll need to provide information such as the medication strength, dispense unit, quantity, and directions for use.

When using MDI, there are two ways to prescribe medications: 1) Via doctors already present in MDI’s clinical network; or 2) via clinicians employed by your company, who can use the MDI practitioner portal to review Patient Cases. In either scenario, you will coordinate this part of the process directly with MDI.

Set up the integration with Capable

To create the integration between MDI and Capable Health, you first need to generate API credentials from your MDI admin portal. On the Partners page of your MDI portal, navigate to your company’s page and select the “Generate API Credentials” action.

Then, go to the Capable admin portal, to the Integrations page, and enter the MDI client ID and client secret you just generated. If you want to receive events based on activity in your MDI account, follow the instructions on the Capable admin portal to set up your MDI webhook.

Arrange for prescription fulfillment

When you create Patient Cases through Capable Health to prescribe medications, you’ll need to specify a pharmacy to fulfill the prescriptions. One option is to allow your users to search for a pharmacy convenient to them using our /mdi/pharmacies endpoint.

Another option is to use mail-order pharmacy Curexa, with whom Capable offers an integration. To use the integration, you need to create an account directly with Curexa. To set up a Capable Health-Curexa integration, enter your Curexa client ID and client secret in the Capable Health admin portal. In addition, use the Curexa pharmacy code when creating Patient Cases (see details below).

Create Products in the Capable portal

After you’ve created your medications in the MDI admin portal, you should add them as Products in Capable Health. This can be done through the Capable Portal. The "External Product Type" should be “MDI Compound” or “MDI Medication.” When creating Products through the Portal, you will be shown a list to choose from.

To provide consultations, in which an MDI doctor can determine what type of care a Patient needs, create a Product with “External Product Type” of “Consult service.”

Each Product must have a “Retail Price” when using Capable’s Stripe Integration for payments. If you have an external product list, you can store an “External ID” on the Product in Capable to reference the entity from your external list. A link or ID of a relevant asset can be stored in the “CMS Entry” field. Products support tagging.

Create Questionnaires in the Capable portal

The clinicians who will be prescribing medications on your behalf will likely need to review responses to surveys posed to your Patients. To gather and pass survey responses when creating an Order, you’ll need to create Questionnaires in Capable Health. Please see the Questionnaires page in our docs for details.

There are a few features you can use when creating a Questionnaire in Capable that are specific to the integration with MDI:

Tagging a question as important: You may want to mark particular questions in a Questionnaire as critical for a clinician to review. In the MDI practitioner portal, a question can be made to appear in red font, indicating to the doctor reviewing the responses that this particular question is important to review. To cause a question to be marked in red in the MDI portal, add the following key-value pair to the metadata object of the relevant question in the Capable Questionnaire:

"important": true

2546 — How to mark a question as "important" on the Capable admin portal

MDI patient attributes: Some information can be passed from a Questionnaire directly to patient attributes in MDI such as allergies and current medication. To mark a question as a patient attribute in MDI add a key-value pair to the metadata object of the relevant question in the Capable Questionnaire:

  "mdi_attribute": "current_medications"

Currently supported attributes are:

"weight_in_kg"
"weight_in_lbs"
"height_in_cm"
"height_in_in"
"pregnancy"
"allergies"
"current_medications"

A question can map to only one attribute. All responses to questions marked with allergy or current medication attributes will be combined before being passed to MDI.

Passing Attachments to MDI: Files possessed by the Patient, such as medical records, may be relevant when prescribing your medications. You can ask the Patient to upload such files in your Questionnaire using the steps below.
- Create an Attachment for the Patient: Ask the Patient to upload the relevant file in the frontend of your application and attach it to the Patient using Capable Health’s /attachments endpoint. Cache the Attachment id value from the response — you’ll need it in the next step.
- Pass the Attachment ID to the Questionnaire using an UploadQuestion: Create a question of type UploadQuestion in your Capable Questionnaire. When you create the Patient's submission, pass the Attachment id you received when creating the Attachment (in the previous step) as the content in the response object to the upload question.
By following these instructions, the Attachments will appear in the MDI practitioner portal in the patient view, for review by a doctor.

Required Patient data

You are now almost ready to create an Order! The remaining step is to ensure that you have all the necessary information on the Patient object. Below is the data that must be present on the Patient object to create a Patient Case:

First name
Last name
Birth date
A phone number marked as primary
A full street address marked as primary
Administrative gender (administrative_gender)

The Patient must also upload a photo of the front of their driver’s license. You can attach the photo to the Patient using the /attachments endpoint. After you upload the driver’s license Attachment in Capable, it will automatically be sent to MDI when you create the Patient Case.

Once the data above has been entered on the Patient object and the Patient has optionally completed a medical-intake Questionnaire, you can create the Order using the /orders endpoint.

Creating Orders with Stripe Integration

When creating a first-time prescription Order:

order_type should be set to medication
If you’re using Capable’s Stripe Integration, requires_approval should be set to false
Add order_line_items objects to the Order with:
- A product_id, corresponding to the ID of a Product created previously in the Capable Portal
- quantity should be set to 1 for MDI prescription Orders. The actual quantity will be determined by the prescription sent by MDI.

Here’s an example POST request body with one item:

{
    "order": {
          "carrier": "USPS",
          "order_type": "medication",
          "requires_approval": false,
          "order_line_items": [
                {
                "product_id": "{product_id_from_capable}",
                "quantity": 1
                }
            ],
           "shipping_address": {
                "line1": "{patient_shipping_address_line_1}",
                "city": "{patient_shipping_address_city}",
                "state": "{patient_shipping_address_state}",
                "zip": "{patient_shipping_address_zip}",
                "country": "{patient_shipping_address_country}"
            },
           "billing_address": {
                "line1": "{patient_shipping_address_line_1}",
                "city": "{patient_shipping_address_city}",
                "state": "{patient_shipping_address_state}",
                "zip": "{patient_shipping_address_zip}",
                "country": "{patient_shipping_address_country}"
           },
           "patient_id": "{patient_id_from_capable}",
           "submission_id": "{submission_id_from_capable}"
      }
}

You can optionally include a submission_id.

When the Order is created, an Order Create event will be sent with status awaiting_payment. The expected order of the events and possible status_details are listed in our events documentation.

Collecting payment for Orders using Stripe

Stripe offers multiple ways to create a checkout experience and collect payment from users. If you’re building a single-page application (SPA), the easiest approach is to use the Stripe Elements widget. If you have a server-side application or a mobile app, Stripe offers other options. We support the use of Coupons + promo codes.

Regardless of the approach you take, you’ll need two pieces of data to collect payment:

Your Stripe publishable key: You can find this on your Stripe dashboard, in the “Developers” section, under “API keys”. We recommend storing this key in an environment variable in your application.
The Order’s payment intent client_secret
When you’re ready request payment for the Order, create a payment intent. You’ll need the order_id of the Order, which was returned in the response to the POST /orders request. The response to the payment intent request will include the client_secret for the Stripe payment. An Order Update event is sent when the payment intent is created.

Tracking the progress of Patient Cases

Once the payment is captured, several events will be sent:

Charge Succeeded with payment details
Order Update with status of awaiting_case_creation, followed by
Order Update with status: processing and processing_status_details: awaiting_prescription_approval
Prescription Create with status: created
Medication Case Assigned

You can track the progress of Patient Cases throughout the MDI Prescription approval process by subscribing to Capable Health webhook events. These events will be sent as a Case progresses:

Medication Case Submitted
Medication Case Processing
Medication Case Completed
Charge Captured
Prescription Update with status: completed
Prescription Update with initial_fullfil_exhausted: true

Please see our events list for a definition of these statuses. If you use the Curexa integration, Capable Health will send webhook events created and received by Curexa related to medication Orders. Please note that for detailed information on Order shipment and delivery, you can set up webhook endpoints for your shipping partner (e.g., Shippo) in the Curexa portal. Once Curexa starts receiving information from a shipping partner, Capable Health will in turn pass tracking updates and information to you via Orders webhook events.

Handling medication refills

If a Patient is prescribed a medication that has refills, you’ll need to create a new Order when it’s time for the Patient to receive one of the refills. Use the /orders POST endpoint to create a new Order with the existing Prescription(s) in the order_line_items object(s).

{
    "order": {
         "carrier": "USPS",
         "order_type": "medication",
         "requires_approval": false,
         "order_line_items": [
              {
                   "prescription_id": "{prescription_id_from_capable}"
              }
         ],
         "shipping_address": {
              "line1": "{patient_shipping_address_line_1}",
              "city": "{patient_shipping_address_city}",
              "state": "{patient_shipping_address_state}",
              "zip": "{patient_shipping_address_zip}",
              "country": "{patient_shipping_address_country}"
         },
         "billing_address": {
              "line1": "{patient_shipping_address_line_1}",
              "city": "{patient_shipping_address_city}",
              "state": "{patient_shipping_address_state}",
              "zip": "{patient_shipping_address_zip}",
              "country": "{patient_shipping_address_country}"
         },
         "patient_id": "{patient_id_from_capable}"
    }
}

After a new Order has been placed, the refills_left attribute on the Prescription resource (retrievable via the /prescriptions endpoint) will go down by one.

Unlike a first-time Order, a refill Order does not require a new MDI Case, since the medicine has already been prescribed.

As before, an Order Create event will be sent with status awaiting_payment. You can then create a payment intent using the order_id. When the payment intent is created, an Order Update event will be sent. Again, the client_secret can be used to capture the payment using Stripe.

Once the payment is captured, these events will be sent:

Charge Succeeded with payment details.
Order Update with status awaiting_fulfillment
Prescription Update

You can find information about how to use coupons and promotion codes under discounts.

Consult-first flow

When a consultation with a doctor is required to determine the correct medications for a Patient, an MDI case can be created without any medications. To use this flow, first create a Product of type Consult service. This can be done in the Capable Portal by setting the External Product type to Consult service.

Then, you can create an Order with this Product( using the /orders endpoint.

Example request payload:

{
    "order": {
        "order_type": "encounter",
        "requires_approval": false,
        "order_line_items": [
            {
                "product_id": "{product_id_from_capable}",
                "quantity": 1
            }
        ],
        "shipping_address": {
            "line1": "{patient_shipping_address_line_1}",
            "city": "{patient_shipping_address_city}",
            "state": "{patient_shipping_address_state}",
            "zip": "{patient_shipping_address_zip}",
            "country": "{patient_shipping_address_country}"
        },
        "billing_address": {
            "line1": "{patient_shipping_address_line_1}",
            "city": "{patient_shipping_address_city}",
            "state": "{patient_shipping_address_state}",
            "zip": "{patient_shipping_address_zip}",
            "country": "{patient_shipping_address_country}"
        },
        "patient_id": "{patient_id_from_capable}",
        "submission_id": "{submission_id_from_capable}"
    }
}

Webhook events that should fire when creating an “encounter” events.
- Order Create
  - "status": "awaiting_payment"
- Order Line Item Create

As with other types of Orders, you can now collect payment with our Stripe integration by creating a payment intent.

📘
The following sequence of events will also occur if a Case is created by an MDI doctor directly from the MDI portal, with the exception of Order Update.

Webhook events that should fire after collecting payment for an “encounter” events.
- Medication Case Assigned
- Order Update
  - "status": "delivered_to_patient"
  - "status_details": null
- Encounter Create

After the MDI doctor adds medications + processes the Case, the following events will fire:

Medication Case Processing
Medication Case Completed
Medication Case Submitted
Prescription Create (possibly multiple of these, if there are multiple Prescriptions added by the MDI doctor)
Encounter Update

Once the MDI case is completed and a prescription has been created, an Order for the prescribed medication can be created by following the same process as for a prescription refill order, outlined above.