Truepill logo
Docs
Introduction
Pharmacy
Telehealth

Insurance billing API

Get your patient’s out-of-pocket expenses or copay amounts using our insurance billing APIs.

Overview

Over 85% of prescriptions are processed using the patient’s primary insurance benefit. Our nationwide footprint of pharmacies means we have a broad set of payor contracts to enable insurance billing for your patient. Being able to process prescriptions through traditional insurance channels is a core feature of the Truepill API.

Determining your patient's insurance

There are multiple ways to obtain your patient’s prescription benefit details - including collecting insurance details upfront from your patient directly or leveraging our benefits investigation API. You can determine your patient’s prescription benefits based on the patient’s insurance cards.

Patients with Commercial Insurance: One or Two cards?

Pharmacy benefits can be determined based on the patient’s insurance cards.

One card for both medical AND pharmacy benefits
Health plans may combine the medical and pharmacy benefits into one program. The patient will have one card that includes member identification information (e.g., group number and member ID) for both the medical and pharmacy benefit. The card may also include copay or coinsurance costs for doctor’s office, specialist and emergency room visits. Insurance cards for both benefits typically note the pharmacy benefit with terms such as “prescription” or “Rx."

Example insurance card with both medical and pharmacy benefits

Two separate cards - one for the medical benefit, and one for the pharmacy benefit.
Health plans may use a third-party provider for the pharmacy benefit, such as a pharmacy benefit manager. In this instance, the patient will have one card for the medical benefit that does not include pharmacy benefit information and another card with pharmacy benefit information.

Example insurance card for medical benefitExample insurance card for pharmacy benefit

Patients with Medicaid
These patients are likely to have a single card for all benefits. The appearance of Medicaid cards varies by state and may include the name of the health plan that administers the benefits.

Multiple insurances

There may be cases where your patient has multiple health plans that provide benefit coverage, such as a commercial health plan and Medicaid. Another common example is the use of primary insurance combined with a manufacturer copay assistance program provided as secondary insurance. In the case of multiple health plans, it is important to establish during the benefits investigation which payer is primary, which is secondary and which is tertiary. Please refer to our insurance billing APIs to determine how to use multiple insurances for your patient.

Truepill supports multiple insurances should a patient provide more than one insurance.

Out of pocket expense

A patients OOP costs may vary based on the specific benefit design and current state of their prescription benefit (ie deductible threshold cleared). Once you have insurance details for your patients, you can use our copay request API endpoints to determine the exact OOP expense for your patient and given medication.

Medical vs pharmacy benefit

It is important to understand a patient's plan design as it relates to their medication vs pharmacy benefit. Typically, when working with Truepill you will be using your patient's prescription benefit which generally covers drugs that are self-administered orally, given by injection or inhaled.

Create insurance

The first step in navigating our insurance APIs is to create an Insurance object for your patient. A patient can have multiple insurances, and similar to our other API endpoints you will receive an insurance_token upon successfully creating an insurance object.

icon code

Create insurance


const body = {
  patient_token: '4526d90a',
  insurance: {
    cardholder_id: 'A9321328',
    rx_group: '006726',
    rx_bin: '997928',
    pcn: 'AXA',
    relationship_code: 1,
    phone_number: '(955) 372-4143'
  }
}

fetch('https://api.truepill.com/v1/insurance', {
  method: 'POST',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(response => console.log(response))
icon success

Success response


{
  "request_id": "cnpsa8ms8vbs7f52c8y2xchd77tza3nv",
  "status": "success",
  "timestamp": 1560356149,
  "details": {
    "insurance_token": "skhsyq83rkd3uht9"
  }
}

Insurance API reference »

Copay request

Overview

A copay is the out of pocket expense owed by the patient.

There are multiple ways to use the copay request API endpoint to achieve your desired experience. Here is the most common workflow:

Workflow diagram of copay request

Create a copay request

A copay request can be created using our copay request API endpoint. Truepill will provide a receipt confirmation of the request, and a subsequent webhook event once the copay information has been returned by the payor.

icon code

Create a copay request


const body = {
  patient_token: '4526d90a',
  insurance_token: ['skhsyq83rkd3uht9'],
  prescriptions: ['z3q2jr', '3cs873', 'wz25v2'],
  metadata: 'cfe146',
  notes: 'This is a note',
  ship_to_state: 'CA'
}

fetch('https://api.truepill.com/v1/copay_request', {
  method: 'POST',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(response => console.log(response))
icon success

Success response


{
  "request_id": "cnpsa8ms8vbs7f52c8y2xchd77tza3nv",
  "status": "success",
  "timestamp": 1560356149,
  "details": {
    "copay_request_token": "ef6p8y6wz7x3hpng",
    "copay_request_prescription_tokens": [
      {
        "prescription_token": "z3q2jr",
        "copay_request_prescription_token": "an7hj7gp63yjhgpw",
        "status": "pending"
      },
      {
        "prescription_token": "3cs873",
        "copay_request_prescription_token": "r6fjmdx6ub99kksk",
        "status": "pending"
      },
      {
        "prescription_token": "wz25v2",
        "copay_request_prescription_token": "xw6m893xt7tjtybu",
        "status": "pending"
      }
    ]
  }
}
icon webhook success

Success webhook event


{
  "request_id": "cnpsa8ms8vbs7f52c8y2xchd77tza3nv",
  "status": "success",
  "callback_type": "COPAY",
  "timestamp": 1563916377515,
  "details": {
    "metadata": "cfe146",
    "message": "Here is a list of medications that we have successfully checked the copay amounts for",
    "patient_token": "4526d90a",
    "prescriptions": [
      {
        "prescription_token": "z3q2jr",
        "insurance_token": "skhsyq83rkd3uht9",
        "status": "completed",
        "next_fill_date": "2019-07-23T00:00:00.000Z",
        "copay_amount": "21.02",
        "copay_request_prescription_token": "98dagjw",
        "fill_number": 1,
        "days_supply": "28",
        "quantity": 28,
        "claims": [
          {
            "insurance_token": "skhsyq83rkd3uht9",
            "billing_order": 1,
            "status": "Paid",
            "copay_amount": "21.02"
          }
        ]
      },
      {
        "prescription_token": "3cs873",
        "insurance_token": "skhsyq83rkd3uht9",
        "status": "completed",
        "next_fill_date": "2019-08-05T00:00:00.000Z",
        "copay_amount": "1.10",
        "copay_request_prescription_token": "ad92wek",
        "fill_number": 1,
        "days_supply": "28",
        "quantity": 28,
        "claims": [
          {
            "insurance_token": "skhsyq83rkd3uht9",
            "billing_order": 1,
            "status": "Paid",
            "copay_amount": "1.10"
          }
        ]
      }
    ]
  }
}

Handling copay request rejections

There are a number of reasons why a copay request may be rejected. The most common reasons include: (1) incorrect insurance details; (2) refill too soon; (3) product not covered.

icon webhook success

Failed webhook event


{
  "request_id": "cnpsa8ms8vbs7f52c8y2xchd77tza3nv",
  "status": "error",
  "callback_type": "COPAY",
  "timestamp": 1563916377515,
  "details": {
    "error_code": "BAD_INSURANCE_DETAILS",
    "metadata": "cfe146",
    "message": "This request was rejected. Please see details.",
    "patient_token": "4526d90a",
    "reject_reason": "Bad Insurance Details",
    "rejection_reason_other": "Invalid BIN"
  }
}
Important note: You must have a valid prescription on file to use the copay request endpoint. If you do not have a valid prescription_token, your request will be rejected.

Copay request API reference »

Initiating a prior authorization from copay request

The prior authorization workflow is covered in full detail in the prior authorization guide. If you are looking for a more streamlined and simple way to manage your prior authorization (PA) process, you can do so from within your copay request.

Our approach to prior authorizations is to automatically initiate electronic PA requests at the point of claim rejection. If you intend to leverage our PA workflow, you can set the initiate_prior_authorization field to true on the copay request object.

Once a prior authorization has been initiated by Truepill, we will notify you through various stages of the PA process through webhook events.

Once a prior authorization request is approved, your webhook event for the copay request will look identical to a standard successful copay request and will be processed seconds after receiving a PA approval.

Managing time to fill

Regardless of whether we are notified of a PA approval status, or working with an insurer that does not send PA notifications, we have aligned our entire process to ensure we optimize for time to fill. This ensures that you have the most up-to-date information on your patient’s prescriptions at all times. We walk through this process in more detail in our Prior Authorization API.

Note: Some insurers do not provide status updates through the PA process. In these scenarios, Truepill will still try adjudicating your insurance claim several times a day until the outcome of the PA is determined. In situations where we know the provider has completed the PA request, then we will increase the frequency of querying the insurer with the insurance claim until it is processed successfully.

Using copay request vs prior authorization API

We provide a streamlined approach to managing your PA process within your copay request - and a more robust process with our prior authorization API. It’s important to note that the end result is exactly the same - an approved or rejected PA request from the insurer.

Determining which pathway to use is largely dependent on the therapy class and/or medication being dispensed. If you know the medication being dispensed has a low or moderate prevalence of PAs, then you may choose to use the copay request approach since a bulk of your copay requests will be returned successfully without a PA rejection.

Alternatively, if you know the medication being dispensed requires PAs 100% of the time (most specialty products), then we recommend using our prior authorization which will provide finer controls to managing your PA process. Our prior authorization API can also provide you a real-time prediction on whether a PA will be required based on the insurance and medication details provided.

Prior authorization guide »

Insurance claim details

Overview

You can query claim details of a successful insurance claim using our insurance claim object. We do not send this data back using a webhook event since it is not available to all customers by default. You must request specific access to receive the insurance claim object. An insurance claim object is tied to every successful fill request that uses our insurance billing API.

Get insurance claim details

Insurance claim details can be accessed using our get /insurance_claim API endpoint. Truepill will provide a receipt confirmation of the request along with details of your request in real-time.

You must be an approved customer to receive full access to the insurance claim details. This is used primarily by our health plan and PBM partners who are the originators of the claim data. They use the insurance claim object for accounting and reconciliation purposes only.