Introduction

Welcome to the Truepill API! Our mission is to put patients first. We believe fundamentally that having open and accessible APIs for healthcare is critical to empower our partners to deliver world-class patient experiences.

We’re thrilled to have partners like you that are looking to revolutionize the patient experience. Our API platform is central to our business and we’re excited for you to get started. We hope your integration experience is smooth and if you have any questions please reach out to support@truepill.com.

Overview

The Truepill API is a powerful and robust RESTful JSON based API. This API will give you the ability to access our healthcare infrastructure to do things like deliver medications to all 50 states, request a prescription refill, transfer a prescription from another pharmacy, request a copay or eligibility information, request a physician consult, create a patient record in our programmable EMR, and much more.

Authentication

An API call with the correct header configuration

# Just Pass the Correct Authorization Header
curl "endpoint"
  -H "Authorization: ApiKey API KEY"

fetch('https://api.truepill.com/v1/patient', {
  method: 'PUT',
  headers: {
    Authorization: 'ApiKey [YOUR API KEY]',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})

An API Response when an Invalid API Key is submitted

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Please Send a Valid Api-Key"
}

The Truepill API uses key based authentication. Requests are authenticated using HTTP Basic Auth. Provide your API key in an Authorization HTTP Header for all requests. If you do not pass in an Authorization HTTP Header with a valid API key, your requests will not authenticate successfully.

Versioning

Truepill's APIs are currently on version "1". The version is specified in all API requests with /v1/ in the API endpoint.

HIPAA & Security

Truepill takes security and confidentiality of PHI very seriously. We ensure your data integrity is a top priority - from the moment you initiate an API request, all the way to when your patient receives a medication from us.

Truepill uses a set of policies and procedures to safeguard our physical and technical infrastructure to maintain compliance with the HIPAA Privacy Rule, Security Rule, Transactions and Code Sets Rule, and their implementing regulations.

Making Requests

An API Response when an empty field is passed in

{
  "statusCode": 400,
  "error": "Bad Request",
  "validation_errors": [
    {
      "key": "street1",
      "message": "is not allowed to be empty"
    }
  ]
}

Production Base Request URL: https://api.truepill.com/v1

In order to access the Truepill API, you will need an API key which will be provisioned and provided to you during the onboarding process. You will be given two unique keys: a sandbox and production API key.

As per RESTful design patterns, the Truepill API implements standard HTTP actions: GET, POST, PUT, DELETE. When making requests, arguments can be passed as params, form data or JSON with correct Content-Type header. On request responses, the data returned is in JSON format.

Each API endpoint will document optional and required fields that can be passed into the request body.

Errors

An Example of a 400 Bad Request Response

{
  "statusCode": 400,
  "error": "Bad Request",
  "validation_errors": [
    {
      "key": "last_name",
      "message": "is required"
    }
  ]
}

An Example of a 404 Not Found Response

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource Not Found."
}

Our API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON.

Additionally, different API endpoints have specific errors and error codes related to that endpoint. These endpoint specific errors are covered in more detail as part of our full API reference.

Common HTTP Responses

Code	Text	Description
200	OK	Success
202	Accepted	Success
400	Bad Request	Request body is not correctly formatted. Potential validation error / missing field
401	Unauthorized	Authentication credentials were missing or incorrect, i.e. api key is not valid
404	Not Found	Some Entity Not Found In Request

Environments

You can access two separate environments, sandbox and production. You will distinguish which environment you are looking to access by using either your sandbox or production API key provided to you. The only functional difference between the two environments is that the sandbox environment has fake data and simulation error events which you can use to test the end-to-end experience.

Production Base Request URL: https://api.truepill.com/v1

Sandbox Base Request URL: https://api.falsepill.com/v1

Webhook Events

Example of a Shipment Webhook Event -- Notifying Package Delivery Status

{
  "request_id": "fill_request_991e90fa6b367cf72032",
  "timestamp": 1590800222,
  "callback_type": "SHIPMENT",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "status": "DELIVERED",
    "message": "Your shipment has been delivered at the destination mailbox.",
    "eta": "2020-06-02T00:54:31.838Z",
    "tracking_number": "43904456187100000000000000",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000"
  }
}

An Example of a Notify Rx Webhook Event

{
  "timestamp": 1581019462,
  "callback_type": "NOTIFY_RX",
  "details": {
    "medication_name": "Atorvastatin 40 mg tablet",
    "prescriber": "Dr. Strange",
    "prescription_token": "z3q2jr",
    "patient_token": "4526d90a",
    "transfer_prescription_token": "z3q2jr23",
    "location": "Hayward, CA"
  }
}

Production environments are integrated with live systems. Through these live systems, Truepill exposes processing events to our customer through webhook events.

Webhook events are asynchronous updates that notify the customer as an order is being processed. Customers may set up a webhook server to receive these events.

There are many different webhook events in the Truepill ecosystem. These are:

• NOTIFY_RX,
• ORDER,
• SHIPMENT,
• TRANSFER,
• DIRECT_TRANSFER,
• COPAY,
• COVERAGE
• PRIOR_AUTH
• CONSULT
• DIAGNOSTICS

These webhook events type will contain a few shared fields for reference, noted below:

Shared Webhook Event Fields

Field Name	Type	Description and Example
request_id	String	Token identifier of the request made (Fill Request, Direct Transfer, etc)
callback_type	String	Type of webhook event
status	String	success, triage, pending or error
details	Object	Object containing more information specific to the type of webhook event
timestamp	Integer	Number representing the number of seconds since midnight January 1, 1970

Simulating Webhook Events while Testing

In the sandbox environment, Truepill's live systems for managing eRx's don't exist. To make up for this, The Sandbox environment houses frameworks to simulate these webhook events and prescriptions.

This will be important and useful as you test your integration end-to-end with Truepill's platform on the Sandbox environment.

For a walkthrough on leveraging simulations, see Sandbox Testing with Simulations

Managing Your Webhook Endpoint

To set or update your existing webhook configuration, go to the Truepill Dashboard

1. Click on the settings button (gear icon) on the top right-hand side of the navigation bar
2. Click on "Profile" on the subsequent dropdown
3. You will now see your Account Details page. Here you can edit your production and test webhook endpoints, as well as test the integration.

Token Management

Our webhook events will return token representations for different objects with high-level details. Our most common tokens include the Patient Token and the Prescription Token.

These tokens are unique and ensure we limit the amount of sensitive and patient-identifiable data sent using webhook events.

Requests vs. Notify Webhook Events

Request Webhook Event: Order Success

{
  "request_id": "fill_request_991e90fa6b367cf72032",
  "timestamp": 1590800072,
  "callback_type": "ORDER",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "message": "Your fill request was processed and is pending shipment.",
    "date_filled": "N/A",
    "medications": [
      {
        "medication_name": "Brand Label 10mg Tablet",
        "dispensed_medication_name": "Brand Label 10mg Tablet",
        "requested_medication_name": "prescription_token:7cb7d8ea418d",
        "days_supply": 28,
        "quantity": 42,
        "fill_number": "0",
        "rx_number": "452793000",
        "total_refills_allowed": 2,
        "prescription_token": "7cb7d8ea418d",
        "medication_token": "e2b176d61505",
        "remaining_refills": {
          "total_remaining_refills": 2,
          "total_quantity_remaining": 84
        }
      },
      {
        "medication_name": "Generic Label 50mg Tablet",
        "dispensed_medication_name": "Generic Label 50mg Tablet",
        "requested_medication_name": "prescription_token:e9549cca9639",
        "days_supply": 1,
        "quantity": 12,
        "fill_number": "2",
        "rx_number": "452793000",
        "total_refills_allowed": 2,
        "prescription_token": "e9549cca9639",
        "medication_token": "3fbsz9m613o9",
        "remaining_refills": {
          "total_remaining_refills": 2,
          "total_quantity_remaining": 48
        }
      }
    ],
    "order_token": "3d2c77",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000",
    "patient_token": "838a906bcc6e7671"
  }
}

Notify Webhook Event: Notify Rx

{
  "timestamp": 1581019462,
  "callback_type": "NOTIFY_RX",
  "details": {
    "medication_name": "Atorvastatin 40 mg tablet",
    "prescriber": "Dr. Strange",
    "prescription_token": "z3q2jr",
    "patient_token": "4526d90a",
    "transfer_prescription_token": "z3q2jr23",
    "location": "Hayward, CA"
  }
}

There are two types of webhook events sent by the Truepill system. Request events are asychronous events that are associated to a request that was made, and thus will always reference a request_id. Notify events are not tied to a request, but may be relevant to your specific workflow.

To the right are two examples of webhook event types -- explained in greater detail later.

Get Webhook Events

Example of a Get Webhook Events Request

curl --request GET \
 --url https://api.truepill.com/v1/webhook_events/notify_rx \
 --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'

fetch('https://api.truepill.com/v1/webhook_events/notify_rx', {
  method: 'GET',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
  }
})
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

{
  "results": [
    {
      "payload" : {
        "timestamp": 1625177130,
        "callback_type": "NOTIFY_RX",
        "details": {
          "medication_name": "Prozac 10 mg tablet",
          "prescriber": "Dr. Mockdoc",
          "prescription_token": "6c8f8c4e3e8c",
          "patient_token": "aa86d0683aba4082",
          "patient_token_duplicates": [],
          "merged_patients": [],
          "location": "hayward",
          "rx_link": "rxl_7e26572b556bfc48e611da3a"
        }
      },
      "delivery_data" : {
        "status" : "success",
        "status_code" : 200
      }
    },
    {
      "payload" : {
        "timestamp": 1625177135,
        "callback_type": "NOTIFY_RX",
        "details": {
          "medication_name": "Alprazolam 1 mg tablet",
          "prescriber": "Dr. Mockdoc",
          "prescription_token": "4bee4686e59c",
          "patient_token": "aa86d0683aba4082",
          "patient_token_duplicates": [],
          "merged_patients": [],
          "location": "hayward",
          "rx_link": "rxl_56ec53ebf66fc9e2c5abaa82"
        }
      },
      "delivery_data" : {
        "status" : "success",
        "status_code" : 200
      }
    },
    ...
    {
      "payload" : {
        "timestamp": 1625177295,
        "callback_type": "NOTIFY_RX",
        "details": {
          "medication_name": "Brand Label 10mg Tablet",
          "prescriber": "Dr. P. Scribe",
          "prescription_token": "e644ac29ed07",
          "patient_token": "aa86d0683aba4082",
          "patient_token_duplicates": [],
          "merged_patients": [],
          "location": "hayward",
          "rx_link": "rxl_5fbcf211864b36e4616b1336"
        }
      },
      "delivery_data" : {
        "status" : "success",
        "status_code" : 200
      }
    }
  ],
  "next_page_token": "ef14ac4a652141dd"
}

GET https://api.truepill.com/v1/webhook_events/{webhook_type}?{query}={operator}:{value}

Webhook Events can be retrieved via API to be reprocessed.

This endpoint returns a list of webhook events and allows for the use of query parameters to scope the results of the request. A request payload represents the request's timestamp, type, and details. A request's delivery_data represents the request's status information.

The Get Webhook Events endpoint can be scoped to retrieve Notify Rx Webhook Events only as well.

Webhook Types

Name	Description	Query Parameters
notify_rx	Returns only NOTIFY_RX webhook events, in time-ascending order	id, timestamp, next, status

Query Operators

Name	Description	Value Type
$lt	Less than	Integer
$gt	Greater than	Integer
$lte	Less than or equal to	Integer
$lte	Greater than or equal to	Integer
$eq	Equals	Integer or String

Fields Returned

Field Name	Type	Description and Example
results	Array Callback	List of callback objects
next_page_token	String	Token used in query_parameter to retrieve the next page of results

The results array contains at most 100 entries per page. If the GET webhooks request returns more than 100 results, next_page_token can be used in a subsequent query to return the next page of results.

GET Notify Rx Webhooks Example

GET https://api.truepill.com/v1/webhook_events/notify_rx?timestamp=$gt:1625177120&timestamp=$lt:1625177295

Returns a list of Notify Rx callbacks where timestamp is greater than 1625177120 and less than 1625177295 (and next_page_token if applicable).

GET https://api.truepill.com/v1/webhook_events/notify_rx?next=ef14ac4a652141dd

Returns the next page using next_page_token as the value for the next query parameter.

Electronic Prescription

Notify Rx Webhook Event

{
  "timestamp": 1581019462,
  "callback_type": "NOTIFY_RX",
  "details": {
    "medication_name": "Atorvastatin 40 mg tablet",
    "prescriber": "Dr. Strange",
    "prescription_token": "z3q2jr",
    "patient_token": "4526d90a",
    "transfer_prescription_token": "z3q2jr23",
    "location": "Hayward, CA"
  }
}

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 can write a new prescription to Truepill Pharmacy over the Surescripts network. Once the prescription is received in our system, we will notify you using a Notify Rx webhook event confirming receipt of your patient’s prescription.

Patient

Create a Patient

Example of a Create Patient Request

curl -X PUT https://api.truepill.com/v1/patient \
   --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
   -d first_name='Bruce' \
   -d last_name='Banner' \
   -d gender='male' \
   -d ssn='123456789' \
   -d communications_opt_in=true \
   -d id_image='https://user:securelogin@www.assets.com/rx/saijhofiasjfoasoi2f.png' \
   -d dob='19691218' \
   -d company='Gamma Inc.' \
   -d street1='123 Some Lane' \
   -d street2='Apt. 123' \
   -d city='Los Angeles' \
   -d state='CA' \
   -d country='US' \
   -d zip='94402' \
   -d phone='430-304-3949' \
   -d email='hulkout@hulk.com' \
   -d language_preference ='English'

const body = {
  first_name: 'Bruce',
  last_name: 'Banner',
  gender: 'male',
  dob: '19691218',
  street1: '123 Some Lane',
  street2: 'Apt. 123',
  city: 'Los Angeles',
  state: 'CA',
  country: 'US',
  zip: '94402',
  phone: '430-304-3949',
  email: 'hulkout@hulk.com' ,
  language_preference: 'English'
}

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

Successful Response

{
  "patient_token": "4526d90a"
}

Error Response - Missing Fields

{
  "statusCode": 400,
  "error": "Bad Request",
  "validation_errors": [
    {
      "key": "last_name",
      "message": "is required"
    },
    {
      "key": "gender",
      "message": "is required"
    },
    {
      "key": "dob",
      "message": "is required"
    }
  ]
}

PUT https://api.truepill.com/v1/patient

This endpoint generates a patient record in the Truepill ecosystem.

Upon a successful request, the endpoint returns a patient_token for you to reference in subsequent API requests that require this field.

The patient_token that is returned upon successfully creating a patient record can be used with many of the other endpoints to continue referencing the same record.

If the patient information in the request body matches the information in an existing patient record, the existing patient_token will be returned in the API response.

Create Patient Body Fields

Field Name	Type	Description and Example	Required?
first_name	String	Bruce	Yes
last_name	String	Banner	Yes
dob	String	19691218	Yes
gender	String	male, female	Yes
ssn	String	Social Security Number, 123456789	No
communications_opt_in	Boolean	communications opt in?	No
id_image	String	url for image of user id	No
ssn_serial	String	Social Security Number (last 4 digits), 3654	No
mbi	String	Medicare Beneficiary ID, 1EG4TE5MK73	No
zip	String	94402	No
company	String	Gamma Inc	No
street1	String	123 Some Lane	No
street2	String	Apt. 123	No
city	String	Los Angeles	No
state	String	CA	No
phone	String	430-304-3949	No
email	String	hulkout@hulk.com	No
language_preference	String	English	No

Update a Patient

Example of an Update Patient Request

curl -X POST https://api.truepill.com/v1/patient/c8d36d \
   --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
   -d ssn='123456789' \
   -d communications_opt_in=true \
   -d company='Gamma Inc.' \
   -d street1='123 Some Lane' \
   -d street2='Apt. 123' \
   -d city='Los Angeles' \
   -d state='CA' \
   -d country='US' \
   -d zip='94402' \
   -d phone='430-304-3949' \
   -d email='hulkout@hulk.com' \
   -d language_preference ='English'

const body = {
  first_name: 'Bruce',
  last_name: 'Banner',
  gender: 'male',
  dob: '19691218',
  street1: '123 Some Lane',
  street2: 'Apt. 123',
  city: 'Los Angeles',
  state: 'CA',
  country: 'US',
  zip: '94402',
  phone: '430-304-3949',
  email: 'hulkout@hulk.com',
  language_preference: 'English'
}

fetch('https://api.truepill.com/v1/patient/c8d36d', {
  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))

Successful Response

{
  "patient_token": "c8d36d",
  "timestamp": 1628788977,
  "status": "success",
  "details": {
    "message": "Accepted: Patient c8d36d has been updated"
  }
}

Error Response - Restricted Fields

{
  "statusCode": 400,
  "error": "Bad Request",
  "validation_errors": [
    {
      "key": "last_name",
      "message": "is not allowed"
    },
    {
      "key": "gender",
      "message": "is not allowed"
    },
    {
      "key": "dob",
      "message": "is not allowed"
    }
  ]
}

POST https://api.truepill.com/v1/patient/{patient_token}

This endpoint updates a patient record in the Truepill ecosystem.

Upon a successful request, the endpoint returns the patient_token of the patient updated, the timestamp, the status, and a message.

Only non-required fields can be updated. Submitting a patient's first name, last name, date of birth, or gender as a field to be updated will be considered a bad request.

Update Patient Body Fields

Field Name	Type	Description and Example	Required?
ssn	String	Social Security Number, 123456789	No
communications_opt_in	Boolean	communications opt in?	No
id_image	String	url for image of user id	No
ssn_serial	String	Social Security Number (last 4 digits), 3654	No
mbi	String	Medicare Beneficiary ID, 1EG4TE5MK73	No
zip	String	94402	No
company	String	Gamma Inc	No
street1	String	123 Some Lane	No
street2	String	Apt. 123	No
city	String	Los Angeles	No
state	String	CA	No
phone	String	430-304-3949	No
email	String	hulkout@hulk.com	No
language_preference	String	English	No

Get Patient

Example of a Get Patient Request

curl --request GET \
  --url https://api.truepill.com/v1/patient/6ce427
  --header 'authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \

fetch('https://api.truepill.com/v1/patient/6ce427', {
  method: 'GET',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

{
  "first_name": "Bruce",
  "last_name": "Banner",
  "gender": "male",
  "dob": "19691218",
  "mbi": "1EG4TE5MK73",
  "address": {
    "name": "Bruce Banner",
    "street1": "123 Some Lane",
    "street2": "Apt. 123",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "94402",
    "company": null,
    "country": "US",
    "phone": "430-304-3949",
    "email": "hulkout@hulk.com",
    "communications_opt_in": true
  },
  "patient_token": "4526d90a"
}

Error Response - Patient Not Found

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Unable to find Patient."
}

Error Response - Patient of a Different Customer

{
  "statusCode": 400,
  "error": "Unauthorized",
  "message": "Patient does not belong to this customer."
}

GET https://api.truepill.com/v1/patient/{patient_token}

Once a patient has been created in the Truepill ecosystem, you can access the patient information at any time using the patient_token that was provided on the Create Patient response.

If the patient_token does not map to a patient record, a 404 Not Found will be returned.

Find Patient

Example of a Find Patient Request

curl --request GET \
  --url https://api.truepill.com/v1/patient?\
              first_name=Bruce&\
              last_name=Banner&\
              gender=male&\
              dob=19691218&\
              zip=94402\
  --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'

fetch(
  'https://api.truepill.com/v1/patient?first_name=Bruce&last_name=Banner&dob=19691218&gender=male',
  {
    method: 'GET',
    headers: {
      Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
      'Content-Type': 'application/json'
    }
  }
)
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

{
  "first_name": "Bruce",
  "last_name": "Banner",
  "gender": "male",
  "dob": "19691218",
  "communications_opt_in": true,
  "patient_token": "4526d90a"
}

Error Response - Patient Not Found

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Unable to find Patient."
}

GET https://api.truepill.com/v1/patient?

While the Get Patient endpoint requires a patient_token to retrieve information, you can also retrieve patient information without a patient_token, using the Find Patient endpoint.

Search for patient information by appending the following param fields onto the API endpoint, separated with an &:

Find Patient Params

Field Name	Type	Description and Example	Required?
first_name	String	Bruce	Yes
last_name	String	Banner	Yes
dob	String	19691218	Yes
gender	String	male, female	Yes
zip	String	94402	Yes

Get Patient Prescriptions

Example of a Get Patient Prescriptions Request

curl --request GET \
  --url https://api.truepill.com/v1/patient/4526d90a/prescriptions\
  --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'

fetch('https://api.truepill.com/v1/patient/4526d90a/prescriptions', {
  method: 'GET',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

{
  "patient_token": "4526d90a",
  "prescriptions": [
    {
      "prescription_token": "5ee24e",
      "medication_name": "Tafluprost",
      "medication_sig": "Wake up at midnight, take then.",
      "prescriber": "Dr. Bruce Banner",
      "date_written": "2020-02-05T00:00:00.000Z",
      "refills_remaining": 1,
      "current_rx_status_text": "On Hold",
      "fillable": true
    },
    {
      "prescription_token": "7ahb3v",
      "medication_name": "Luthera",
      "medication_sig": "Take one Tablet by mouth at the same time daily",
      "prescriber": "Dr. Strange",
      "date_written": "2020-02-05T00:00:00.000Z",
      "refills_remaining": 0,
      "current_rx_status_text": "Transferred",
      "fillable": false
    }
  ]
}

Error Response - Patient Not Found

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Unable to find Patient."
}

GET https://api.truepill.com/v1/patient/{patient_token}/prescriptions

Retrieve the list of Patient's prescriptions which includes the prescription token, medication name, medication sig, prescriber, date written, refills remaining, current prescription status and the fillable status.

Patient's prescriptions must already exist in the Truepill ecosystem in order to be retrieved.

Patient Prescription Fields Returned

Field Name	Type	Description and Example
prescription_token	String	Token to reference the prescription
fillable	Boolean	Is this prescription fillable? (has not expired, been transferred-out, etc)
medication_name	String	Name of medication prescribed
medication_sig	String	Instructions for taking medication
prescriber	String	Name of prescriber
date_written	String	When the prescribed was written
refills_remaining	Integer	Number of refills on this prescription
current_rx_status_text	String	Status of the prescription currently

Prescription

Send a Prescription

A valid prescription is required to dispense and ship medications to your patient.

There are 3 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.

Electronic Prescriptions

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.

Learn More

Transfer Prescriptions

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.

Learn More

Direct Transfer Prescriptions

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.

Learn More

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.

Notify Rx Webhook Events

When a prescription is received and processed by Truepill, we will provide a webhook event with the text NOTIFY_RX in the callback_type field.

The Notify Rx Webhook Event will contain the prescription_token to reference the prescription when making Fill and Copay Requests.

It is important to note that, unlike other webhook events, these webhook events are not tied to a specific API Request. They are sent out as Truepill receives and processes prescriptions in our pharmacy software. If you are transferring prescriptions to Truepill, you should have a Webhook Server set up and configured and be expecting these webhook events.

Notify Rx Webhook Events can be retrieved and re-processed using the Get Webhook Events Endpoint

An Example of a Notify Rx Webhook Event

{
  "timestamp": 1581019462,
  "callback_type": "NOTIFY_RX",
  "details": {
    "medication_name": "Atorvastatin 40 mg tablet",
    "prescriber": "Dr. Strange",
    "prescription_token": "z3q2jr",
    "patient_token": "4526d90a",
    "transfer_prescription_token": "z3q2jr23",
    "location": "Hayward, CA"
  }
}

Notify Rx Webhook Event Fields

Field Name	Type	Description
prescription_token	String	Associated prescription's token
patient_token	String	Associated patient's token
transfer_prescription_token	String	New prescription token created when an Rx has been transferred. Store this number to ensure you this token for future requests. Not present on all Rx notifiy events, only when the Rx has been transferred and a new Rx is created. The original token should be saved for association but will be discontinued.
medication_name	String	Medication name on prescription
prescriber	String	Name of the prescribing doctor
location	String	The pharmacy's city name and state

Get Prescription

Example of a Get Prescription Request

curl --request GET \
 --url https://api.truepill.com/v1/prescription/3e0ad68b28e0 \
 --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'

fetch('https://api.truepill.com/v1/prescription/0910788a5ea3', {
  method: 'GET',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
  }
})
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

{
  "prescription": {
    "date_written": "2020-02-05T00:00:00.000Z",
    "expiration_date": "2021-02-05T00:06:00.000Z",
    "days_supply": "84",
    "is_refill": 0,
    "last_filled_date": null,
    "medication_sig": "Take one Tablet by mouth at the same time daily",
    "number_of_refills_allowed": 0,
    "origin": "Electronic",
    "prescribed_brand_name": "Lutera (28)",
    "prescribed_drug_strength": "0.1 mg-20 mcg",
    "prescribed_generic_name": "levonorgestrel-ethinyl estradiol 0.1 mg-20 mcg tablet",
    "prescribed_ndc": "51862002806",
    "prescribed_quantity": 84,
    "prescribed_written_name": "Lutera-28 Tablet",
    "prescriber": "Dr. Strange",
    "prescriber_address": {
      "name": "Dr. Strange",
      "company": null,
      "street1": "12345 Avengers Rd",
      "street2": null,
      "city": "San Francisco",
      "state": "CA",
      "zip": "94402",
      "country": "US",
      "phone": "(800) 888-8888",
      "email": "dr.strange@avengers.com"
    },
    "prescriber_npi": "1639349256",
    "prescriber_order_number": "11111111",
    "quantity_remaining": 0,
    "refills_remaining": 0,
    "rx_number": "1966785",
    "prescription_token": "z3q2jr",
    "notes": "prescription notes",
    "icd_codes": {
      "icd10": ["Z30.09"],
      "icd9": ["N94.6"]
    },
    "is_daw": false,
    "fillable": true,
    "dea_schedule": 0,
    "original_prescribed_ndc": "43547041110",
    "date_filled_utc": "2020-07-30T20:08:55.000Z"
  }
}

Error Response - Prescription Not Found

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Unable to find Prescription."
}

GET https://api.truepill.com/v1/prescription/{prescription_token}

Once a specific prescription is in the Truepill ecosystem -- either via eRx, Direct Transfer or Transfer -- the prescription information can be retrieved at any time through an API request.

This endpoint requires a prescription_token. You will receive a prescription_token through one of the following scenarios:

• A Notify-Rx callback which is sent when a prescription is received by the pharmacy through SureScripts
• A Direct Transfer callback which is sent when a Direct Transfer has been successfully processed
• A Transfer callback which is sent when a Transfer has been successfully processed

Prescription Fields Returned

Field Name	Type	Description and Example
prescription_token	String	Token to reference the prescription
rx_number	String	Rx number of prescription
fillable	Boolean	Is this prescription fillable? (has not expired, been transferred-out, etc)
prescribed_brand_name	String	Name of medication prescribed
prescribed_generic_name	String	Name of generic medication prescribed
prescribed_ndc	String	NDC of prescribed medication
prescribed_quantity	Integer	Quantity of prescribed medication
prescribed_written_name	String	Name of medication prescribed as written
prescribed_drug_strength	String	Drug strength prescribed
medication_sig	String	Instructions for taking medication
days_supply	String	Number of days the medication covers
date_written	String	When the prescribed was written
expiration_date	String	When the prescription will expire
refills_remaining	Integer	Number of refills on this prescription
quantity_remaining	Integer	Quantity of doses remaining on prescription
is_refill	Boolean	Is prescription a refill or new fill?
last_filled_date	String	When prescription was last filled (null if not)
date_filled_utc	String	When prescription was last filled (null if not) in UTC
number_of_refills_allowed	Integer	Number of refills allowed for prescription
prescriber	String	Name of prescriber
prescriber_address	Object	Object containing Prescriber Address information
prescriber_npi	String	NPI of prescriber
prescriber_order_number	String	Prescriber order number of escript
notes	String	Prescription notes associated with Rx
icd_codes	Object	Object containing ICD Information associated with Rx
origin	String	Original source of prescription
is_daw	Boolean	Is prescription dispense-as-written (null if historical rx)
dea_schedule	Integer	Controlled Substance Act drug schedule
original_prescribed_ndc	String	NDC of prescribed medication as originally written on eScript (if applicable)

Prescriber Address Fields

Field Name	Type	Description and Example
name	String	Name of prescriber
company	String	Clinic name (if available)
street1	String	Street 1 of prescribing clinic address
street2	String	Street 2 of prescribing clinic address (if available)
city	String	City of prescribing clinic address
state	Integer	State of prescribing clinic address
zip	String	Zip code of prescribing clinic address
country	String	"US"
phone	String	Prescriber/clinic phone contact information
email	String	Prescriber/clinic email contact information

ICD Codes Fields

Field Name	Type	Description and Example
icd10	Array (String)	Arrray of ICD10 codes associated to the prescription
icd9	Array (String)	Arrray of ICD9 codes associated to the prescription

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 can write a new prescription to Truepill Pharmacy over the Surescripts network. Once the prescription is received in our system, we will notify you using a Notify Rx webhook event confirming receipt of your patient’s prescription.

Notify Rx Webhook Event

{
  "timestamp": 1581019462,
  "callback_type": "NOTIFY_RX",
  "details": {
    "medication_name": "Atorvastatin 40 mg tablet",
    "prescriber": "Dr. Strange",
    "prescription_token": "z3q2jr",
    "patient_token": "4526d90a",
    "transfer_prescription_token": "z3q2jr23",
    "location": "Hayward, CA"
  }
}

Matching a Prescription to your Patient

Matching the incoming electronic prescription relies on a number of fields including provider name, address, clinic name, medication, patient name, patient date of birth, patient address, patient phone taken directly from the electronic prescription.

Once the prescription has been successfully matched to your patient, we generate a prescription_token, which is a tokenized representation of the Prescription object.

Transfer a Prescription

A “transfer” (as it’s commonly referred to in the pharmacy industry) is a pharmacy-to-pharmacy exchange of the prescription between a third party pharmacy and a Truepill pharmacy. This transfer is typically initiated by the pharmacy requesting the prescription.

In simple terms, your patient has a prescription at Rite-Aid, Walgreens, CVS and you’d like to transfer that patient’s prescription to Truepill.

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 Transfer webhook event notifying you of the prescription(s) successfully transferred into our pharmacy.

Create a Transfer

Example of a Create Transfer Request - Providing Pharmacy Details

curl -X POST https://api.truepill.com/v1/transfer_request \
   --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
   -d patient_token= "4526d90a" \
   -d pharmacy_name="Walmart Pharmacy" \
   -d pharmacy_phone="3018897765" \
   -d pharamcy_fax="3018897765" \
   -d notes="transfer notes"

const body = {
  patient_token: '4526d90a',
  pharmacy_name: 'Walmart Pharmacy',
  pharmacy_phone: '(949) 837-0504',
  pharmacy_fax: '(949) 837-0504',
  medication_name: ['Finasteride, 1 mg', 'Sucralfate'],
  metadata: 'cfe146',
  notes: 'transfer notes'
}

fetch('https://api.truepill.com/v1/transfer_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))

Successful API Response

{
  "request_id": "transfer_request_68e47e32ba93db638259",
  "timestamp": 1564608647,
  "status": "success",
  "details": {
    "message": "Your transfer request has been received.",
    "transfer_token": "d36889c10dcf",
    "transfer_medications": [
      {
        "transfer_medication_token": "1bbda354e8c7",
        "medication_name": "Finasteride, 1 mg"
      },
      {
        "transfer_medication_token": "ea52a1392697",
        "medication_name": "Sucralfate"
      }
    ],
    "patient_token": "4526d90a"
  }
}

POST https://api.truepill.com/v1/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 1-3 days.

The following endpoint requests the transfer of a prescription from a third-party pharmacy to Truepill’s pharmacy. If the prescription in question was generated by a physician contracted by the API User then this endpoint does not need to be called; otherwise this request is necessary for the Fill Request to be fulfilled.

Request Fields

Field Name	Type	Description and Example	Required?
patient_token	String	4526d90a	Yes
pharmacy_name	String	Walmart Pharmacy	See Note
pharmacy_phone	String	3018987787	See Note
prescriber_name	String	Dr. Susan Yen	See Note
prescriber_phone	String	5559998867	See Note
pharmacy_fax	String	3018987787	No
prescriber_fax	String	3018987787	No
medications	Array	["Sprintec Tablet", "Spironolactone 10mg tablet"]	No
metadata	String	Customer-side identifier to reference the Transfer in Customer system	No
notes	String	Additional transfer notes to specify	No

Transfer Webhook Events

Notify Rx Webhook Event

{
  "timestamp": 1590784899,
  "callback_type": "NOTIFY_RX",
  "details": {
    "medication_name": "Bupropion Hcl Xl 300 Mg Tablet",
    "prescriber": "Dr. P. Scribe",
    "prescription_token": "z3q2jr",
    "patient_token": "4526d90a",
    "location": "Hayward, CA"
  }
}

Successful Transfer Webhook Event

{
  "request_id": "transfer_request_9a813a5a8782d15923da",
  "timestamp": 1564611968,
  "callback_type": "TRANSFER",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "message": "Here is a list of medications that were successfully transferred",
    "patient_token": "4526d90a",
    "medications": [
      {
        "transfer_medication_token": "6c34dacasdeb49",
        "requested_medication_name": "Bupropion XL",
        "last_filled_date": "No Data",
        "prescription_token": "z3q2jr",
        "prescriber": "Dr. P. Scribe",
        "medication_name": "Bupropion Hcl Xl 300 Mg Tablet",
        "medication_sig": "Take one daily.",
        "num_refills_remaining": 1,
        "quantity": 150,
        "days_supply": 30,
        "dea_schedule": 0
      }
    ]
  }
}

Error Transfer Webhook Event

{
  "request_id": "transfer_request_c91f2af0a847271bdc0b",
  "status": "error",
  "callback_type": "TRANSFER",
  "timestamp": 1502304584,
  "details": {
    "metadata": "cfe146",
    "message": "No medications were able to be transferred",
    "patient_token": "4526d90a"
  }
}

Transfer Webhook Events are sent on the completion of a prescription transfer with the text TRANSFER in the callback_type field and, like with other webhook events, the status field indicating whether or not it was successful.

In a successful transfer, you will receive a Notify Rx Webhook Event for each prescription that is transferred to Truepill, along with a transfer webhook event that contains a detailed list of the transferred medications in the medications field.

Successful Transfer Webhook Event Fields

Field Name	Type	Description and Example
patient_token	String	Associated patient's url token
medications	Array of Medications objects	rx information
metadata	String	Customer-side identifier to reference the Transfer in Customer system
message	String	Plain english status text

Medications

The medications field returns an array of objects that contain the following fields:

Field Name	Type	Description and Example
prescription_token	String	Token used for looking up an Rx
medication_name	String	Medication name
requested_medication_name	String	Requested medication name
quantity	Integer	Quantity prescribed
days_supply	Integer	Number of days supply
num_refills_remaining	Integer	Total refills remaining on Rx
last_filled_date	Integer	Last Filled Date of Rx
transfer_medication_token	String	Token of requested medication on Transfer
dea_schedule	Integer	Controlled Substances Act drug schedule

Transfer Error Codes

Each rejection webhook event contains an error code denoting the type of error in the "error_code" field. These codes are accompanied by a text description detailing the error in the “description” field.

If there is additional information that can accompany the error code and description, it will be provided in the "message" field. This occurs on certain rejections such as 'Other Reason' (rejection specifics).

It is important to note that the same descriptions may correspond to several different error codes.

Table of Error Codes & Associated Information

Code	Description	Message (Additional Information)
RX_DOSAGE_MISMATCH	Dosage doesn't match prescription	N/A
RX_FORMULA_MISMATCH	Formulation doesn't match prescription	N/A
RX_NO_REFILLS	No refills remaining	N/A
RX_NONEXISTANT	Prescription doesn't exist at specified pharmacy	N/A
RX_EXPIRED	Prescription has expired	N/A
RX_IS_DAW	Prescription is dispense as written for brand	N/A
PATIENT_RECORD_NONEXISTANT	No patient record at pharmacy	N/A
PATIENT_CANCELLED_RX	Patient cancellation request	N/A
PATIENT_INFO_MISMATCH	Patient information doesn't match prescription	N/A
PATIENT_CONTACT_REQUESTED	Pharmacy/prescriber requesting patient contact	N/A
PHARMACY_NO_RESPONSE	Pharmacy did not respond after 6 days	N/A
PHARMACY_DECLINED	Pharmacy refuses transfer	N/A
PRESCRIBER_DECLINED	Prescriber declined to provide prescription	N/A
PRESCRIBER_NO_RESPONSE	Prescriber did not respond after 6 days	N/A
TRANSFER_DUPLICATE	Duplicate Transfer	N/A
TRANSFER_CONTACT_INFO_INCORRECT	Incorrect pharmacy/prescriber contact information	N/A
TRANSFER_OTHER_REASON	Other Reason	Rejection Specifics

List of Failures

There are a number of reasons why a transfer request may fail. A full list of rejections for transfers are:

• Dosage doesn’t match prescription
• Duplicate transfer
• Formulation doesn’t match prescription
• Incorrect pharmacy/prescriber contact information
• No patient record at pharmacy
• No refills remaining
• Patient cancellation request
• Patient information doesn’t match prescription
• Patient requested qty higher than prescribed
• Pharmacy did not respond after 6 days
• Pharmacy refuses transfer
• Pharmacy/prescriber requesting patient contact
• Prescriber declined to provide prescription
• Prescriber did not respond after 6 days
• Prescription doesn’t exist at specified pharmacy
• Prescription has expired
• Prescription is dispense as written for brand
• Others

Transfer Contact Webhook Events

Successful Transfer Contact Webhook Event

{
  "request_id": "transfer_request_9a813a5a8782d15923da",
  "timestamp": 1564611968,
  "callback_type": "TRANSFER_CONTACT",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "message": "A transfer contact was successfully made",
    "patient_token": "4526d90a",
    "transfer_token": "59222e5807",
    "contact_name": "Walmart",
    "contact_method": "fax",
    "contact_number": "6235474583"
  }
}

Error Transfer Contact Webhook Event

{
  "request_id": "transfer_request_9a813a5a8782d15923da",
  "timestamp": 1564611968,
  "callback_type": "TRANSFER_CONTACT",
  "status": "error",
  "details": {
    "error_code": "RX_NO_REFILLS",
    "metadata": "cfe146",
    "transfer_token": "59222e5807",
    "message": "No refills remaining",
  }
}

Transfer Contact Webhook Events are sent when a transfer's pharmacies/doctors are contacted via phone or fax. The webhook event has the TRANSFER_CONTACT in the callback_type field and, like with other webhook events, the status field indicating whether or not it was successful.

Successful Transfer Contact Webhook Event Fields

Field Name	Type	Description and Example
patient_token	String	Associated patient's url token
transfer_token	String	Associated transfer's url token
contact_name	String	The contacted pharmacy/doctor's name
contact_method	String	The contact method: Fax or Phone
contact_number	String	The contact's fax or phone number
metadata	String	Customer-side identifier to reference the Transfer in Customer system
message	String	Plain english status text

Common Failures

There are situations that a transfer contact request may fail. These are:

• Transfer is not in pending status
• Transfer contact method is not supported

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 which 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.

List Transfers

An Example of a List Transfers Request

curl -X GET https://api.truepill.com/v1/transfer_request \
   --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'

fetch('https://api.truepill.com/v1/transfer_request', {
  method: 'GET',
  headers: {
    'Authorization': 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  })
  .then(response => response.json())
  .then(response => console.log(response))

Using Pagination on the List Transfers Request

curl -X GET https://api.truepill.com/v1/transfer_request?page=2 \
   --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'

fetch('https://api.truepill.com/v1/transfer_request?page=2', {
  method: 'GET',
  headers: {
    'Authorization': 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  })
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

[
  {
    "created_at": "2019-05-09T19:35:49.000Z",
    "url_token": "582ee42c9537",
    "status": "rejected",
    "transfer_medications": [
      {
        "url_token": "15b79ebc94fb",
        "medication_name": "Thing1"
      },
      {
        "url_token": "867712a0f21c",
        "medication_name": "Thing 3 400MG"
      }
    ]
  },
  {
    "created_at": "2019-05-30T20:54:02.000Z",
    "url_token": "74d8f1424291",
    "status": "rejected",
    "transfer_medications": [
      {
        "url_token": "f6ab259d253d",
        "medication_name": "Thing1"
      },
      {
        "url_token": "35563b59d80d",
        "medication_name": "Thing 3 400MG"
      }
    ]
  }
]

Response when Pagination Value surpasses Number of Transfers in the System

[]

GET https://api.truepill.com/v1/transfer_request

This endpoint retrieves a list of all the transfer requests you have made to the Truepill ecosystem.

List transfers utilizes an optional pagination functionality when retrieving a large number of transfers. By default, this endpoint retrieves 50 transfers at a time, starting with the earliest transfers.

For example, if you were looking to retrieve the 70-80th transfers made to Truepill, you would use a pagination of 1 (zero base indexing).

To paginate, append a ? at the end of the API endpoint along with the page=[PAGE_NUMBER], and replace
[PAGE_NUMBER] with an integer.

If the pagination value surpasses the number of transfers in the system, an empty array [] will be returned.

Query Params

Field Name	Type	Description and Example	Required?
page	Integer	5 'page' of transfers to receive. Zero based indexing	No

Get Transfer

Example of a Get Transfer Request

curl -X GET https://api.truepill.com/v1/transfer_request/98asdf0a9sd \
   --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'

fetch('https://api.truepill.com/v1/transfer_request/98asdf0a9sd', {
  method: 'GET',
  headers: {
    'Authorization': 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  })
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

[
  {
    "created_at": "2019-05-29T21:14:11.000Z",
    "url_token": "0b8341246895",
    "status": "completed",
    "cancel_reason": null,
    "cancel_reason_other": null,
    "pharmacy_name": "Walmart Pharmacy",
    "pharmacy_phone": "(704) 982-8948",
    "prescriber_name": "",
    "prescriber_phone": "",
    "notes": "Medication: ",
    "metadata": "cfe146",
    "transfer_medications": [
      {
        "url_token": "10cb9171ee0c",
        "rejection_reason": null,
        "rejection_reason_other": null,
        "medication_name": "Prednisone",
        "prescription": {
          "num_refills_remaining": 5,
          "medication_name": "Prednisone",
          "prescription_date": null,
          "prescriber": null,
          "last_filled_date": "2019-05-23",
          "url_token": null,
          "days_supply": "30",
          "num_refills_filled": "0",
          "prescribed_quantity": 60,
          "prescribed_written_name": "prednisone 5 mg tablet",
          "prescribed_generic_name": "prednisone 5 mg tablet"
        }
      }
    ],
    "messages": []
  }
]

Error Response -- Transfer Not Found

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Transfer not found."
}

GET https://api.truepill.com/v1/transfer_request/{transfer_token}

Once a transfer has been created in the Truepill ecosystem, you can access the transfer information at any time using the transfer_token that was provided on the Create Transfer response.

If the transfer_token does not map to a transfer record, a 404 Not Found will be returned.

Direct Transfer a Prescription

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.

Create a Direct Transfer

Example of a Direct Transfer Request

curl -X POST https://api.truepill.com/v1/direct_transfer \
   --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
   --data '{
     "prescriber": {
      "first_name": "Stephen",
      "last_name": "Strange",
      "npi": "123123123",
      "address": {
          "name": "Stephen Strange",
          "street1": "123 Some Lane",
          "city": "San Mateo",
          "state": "CA",
          "zip": "94538"
        }
      },
      "patient_token: "4526d90a",
      "transfer_from": {
        "name": "Walmart Pharmacy",
        "address": {
          "name": "",
          "street1": "123 Some Lane",
          "city": "San Mateo",
          "state": "CA",
          "zip": "94538"
        },
        "id_number": 490382308,
        "pharmacist": "Dr. Storm"
      },
      "transfer_to": {
        "name": "Truepill",
        "id_number": 490382377,
        "pharmacist": "Dr. Strange"
      },
      "prescription": {
        "medication_name": "Finasteride",
        "quantity_written": "60",
        "days_supply": 30,
        "quantity_dispensed": "60",
        "medication_sig": "Apply Daily.",
        "written_date": "20190101",
        "last_fill_date": "20190201",
        "first_fill_date": "20190115",
        "refills_left": 5,
        "refills_transferred": 5,
        "number": "4567",
        "can_substitute": true,
        "direct_transfer_url": "https://user:securelogin@www.assets.com/rx/saijhofiasjfoasoi2f.png",
        "prescribed_ndc": "12345678912",
        "icd10_code": "G43.909",
        "notes": "A note here",
        "annotation": "Hair loss treatment",
        "diagnosis": "Male pattern baldness"
      },
      "metadata": "5fc6c6"
    }'

const body = {
  prescriber: {
    first_name: 'Stephen',
    last_name: 'Strange',
    npi: '123123123',
    address: {
      name: 'Stephen Strange Practice',
      street1: '123 Some Lane',
      city: 'San Mateo',
      state: 'CA',
      zip: '94538'
    }
  },
  patient_token: '4526d90a',
  transfer_from: {
    name: 'Walmart Pharmacy',
    address: {
      name: 'Walmart Pharmacy',
      street1: '123 Some Lane',
      city: 'San Mateo',
      state: 'CA',
      zip: '94538'
    },
    id_number: '490382308',
    pharmacist: 'Dr. Storm'
  },
  transfer_to: {
    name: 'Truepill',
    id_number: '1295182590',
    pharmacist: 'Quynh Do'
  },
  prescription: {
    medication_name: 'Finasteride',
    prescribed_ndc: '12345678912',
    days_supply: 30,
    quantity_written: '60',
    quantity_dispensed: '60',
    medication_sig: 'Apply Daily.',
    written_date: '20190101',
    last_fill_date: '20190201',
    first_fill_date: '20190115',
    refills_left: 5,
    refills_transferred: 5,
    number: '4567',
    can_substitute: true,
    direct_transfer_url:
      'https://user:securelogin@www.assets.com/rx/saijhofiasjfoasoi2f.png',
    icd10_code: 'G43.909',
    notes: 'A note here',
    annotation: 'Hair loss treatment',
    diagnosis: 'Male pattern baldness'
  },
  metadata: '5fc6c6'
}

fetch('https://api.truepill.com/v1/direct_transfer', {
  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))

Successful Response

{
  "request_id": "5a9a79a446f5d554",
  "timestamp": 1559580965,
  "status": "success",
  "details": {
    "direct_transfer_id": "c8a73a55dc"
  }
}

POST https://api.truepill.com/v1/direct_transfer

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.

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.

Request Fields

Field Name	Type	Description and Example	Required?
patient_token	String	4526d90a (Required)	Yes
prescriber	Prescriber	Prescriber Object	Yes
transfer_from	TransferFrom	Transfer From Object	Yes
transfer_to	TransferTo	Transfer To Object	Yes
prescription	Prescription	Prescription Object	Yes
metadata	String	5fc6c6	No

Prescriber

Field Name	Type	Description and Example	Required?
first_name	String	Prescriber first name	Yes
last_name	Prescriber	Prescriber last name	Yes
address	Address	Address Object	Yes
npi	String	Prescriber NPI	Yes

Transfer From

Field Name	Type	Description and Example	Required?
name	String	Pharma One	Yes
address	Address	Address Object	Yes
id_number	String	2142134123	Yes
pharmacist	String	Dill Droga	Yes

Transfer To

This object must match Truepill's records. Contact us for more details.

Field Name	Type	Description and Example	Required?
name	String	Truepill	Yes
id_number	String	1295182590	Yes
pharmacist	String	Quynh Do	Yes

Prescription

Field Name	Type	Description and Example	Required?
medication_name	String	Finasteride	Yes
prescribed_ndc	String	"12345678912"	Yes
days_supply	Integer	30	Yes
quantity_written	String	60	Yes
quantity_dispensed	String	60	Yes
medication_sig	String	Take one daily.	Yes
refills_left	Integer	5	Yes
refills_transferred	Integer	5	Yes
number	String	12321341 Rx number	Yes
can_substitute	Boolean	true	Yes
written_date	String	19840123 : yyyymmdd format	Yes
direct_transfer_url	String	https://user:secure@www.assets.com/rx/asoi2f.png	No
last_fill_date	String	19840123 yyyymmdd format	No
first_fill_date	String	19840123 yyyymmdd format	No
icd10_code	String	G43.909	No
notes	String	A note here	No
annotation	String	Hair loss treatment	No
diagnosis	String	Male pattern baldness	No

Address

Field Name	Type	Description and Example	Required?
name	String	CVS Pharmacy	Yes
company	String	Gamma Inc	Yes
street1	String	123 Some Lane	Yes
street2	String	Apt. 123	No
city	String	Los Angeles	Yes
state	String	CA	Yes
zip	String	94402	Yes
phone	String	430-304-3949	No
email	String	hulkout@hulk.com	No

Direct Transfer Webhook Events

Notify Rx Webhook Event

{
  "timestamp": 1590784899,
  "callback_type": "NOTIFY_RX",
  "details": {
    "medication_name": "Bupropion Hcl Xl 300 Mg Tablet",
    "prescriber": "Dr. P. Scribe",
    "prescription_token": "z3q2jr",
    "patient_token": "4526d90a",
    "location": "Hayward, CA"
  }
}

Successful Direct Transfer Webhook Event

{
  "request_id": "9a813a5a8782d15923da",
  "timestamp": 1564611968,
  "callback_type": "DIRECT_TRANSFER",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "message": "Direct Transfer Accepted.",
    "patient_token": "4526d90a",
    "direct_transfer_token": "dff0a98124",
    "prescription_token": "z3q2jr"
  }
}

Error Direct Transfer Webhook Event

{
  "request_id": "c91f2af0a847271bdc0b",
  "status": "error",
  "callback_type": "DIRECT_TRANSFER",
  "timestamp": 1502304584,
  "details": {
    "metadata": "cfe146",
    "message": "Direct Transfer Rejected.  duplicate",
    "patient_token": "4526d90a",
    "direct_transfer_token": "9e6d606fva"
  }
}

You will receive a Notify Rx Webhook Event for each prescription that is transferred to Truepill.

After a Direct Transfer Request has been successfully completed, you will receive a Notify Rx Webhook Event for the prescription transferred to Truepill, along with a Direct Transfer webhook event. This will contain the prescription_token to utilize the prescription within Truepill.

If a Direct Transfer is unable to be successfully processed, only an error Direct Transfer webhook event will be sent.

Direct Transfer Webhook Events are sent with text DIRECT_TRANSFER in the callback_type field and, like with other webhook events, the status field indicating whether or not it was successful.

Success Direct Transfer Webhook Event Fields

Field Name	Type	Description and Example
prescription_token	String	Associated prescription token if accepted
patient_token	String	Associated patient's token
metadata	String	Customer-side identifier to reference the Fill Request in Customer system
message	String	Plain english status text
direct_transfer_token	String	Associated Direct Transfer token

Fill Request

Overview

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.

Truepill will provide a receipt confirmation of the request, and several subsequent webhook events throughout the life cycle of the order.

Create a Fill Request

Example of a Create Fill Request

curl -X POST https://api.truepill.com/v1/fill_request \
   -H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json" \
   -d '{"patient_token": "4526d90a",
      "patient_payment_type": "insurance",
      "insurances": [
        {
          "insurance_token": "19sienglo92831n5"
        },
      ],
      "medications": [
        {
          "prescription_token": "z3q2jr"
        },
        {
          "prescription_token": "3cs873",
        }
      ],
      "otc_products": [
        {
          "item": "Vitamin B",
          "quantity": 30
        }
      ],
      "address_to_name": "Bruce Banner",
      "address_to_company": "Avengers",
      "address_to_street1": "1700 S Amphlett Blvd",
      "address_to_street2": "#221",
      "address_to_city": "San Mateo",
      "address_to_state": "CA",
      "address_to_zip": "94402",
      "address_to_country": "US",
      "address_to_phone": "(347) 610-8896",
      "address_to_email": "bruce.banner@avengers.com",
      "communications_opt_in": true,
      "shipping_method": "usps_priority",
      "signature_confirmation": false,
      "replacement_order": "fill_request_cb619ca2e133d37daefc",
      "metadata": "cfe146",
      "notes": "Here are some special instructions on how to package this order",
      "patient_survey": {
        "allergies": "Penicillian",
        "medications": "Tafluprost",
        "conditions": "Glaucoma",
        "smoking_frequency": "N/A",
        "drinking_frequency": "One drink nightly",
        "bleeding_clotting_disorder": true,
        "thyroid_disorder": false,
        "events":[
          {
            "year":"2019",
            "type":"hospitalization",
            "reason":"food poisoning"
          },
          {
            "year":"2018",
            "type":"surgery",
            "reason":"glaucoma treatment"
          }
        ]
      }
    }'

const body = {
  patient_token: '4526d90a',
  patient_payment_type: 'insurance',
  insurances: [
    {
      insurance_token: '19sienglo92831n5'
    },
    {
      cardholder_id: '112233445566',
      rx_bin: '172020',
      pcn: 'HDMI',
      rx_group: '444555'
    }
  ],
  medications: [
    {
      prescription_token: 'z3q2jr'
    },
    {
      prescription_token: '3cs873'
    }
  ],
  otc_products: [
    {
      item: 'Vitamin B',
      quantity: 30
    }
  ],
  address_to_name: 'Bruce Banner',
  address_to_company: 'Avengers',
  address_to_street1: '1700 S Amphlett Blvd',
  address_to_street2: '#221',
  address_to_city: 'San Mateo',
  address_to_state: 'CA',
  address_to_zip: '94402',
  address_to_country: 'US',
  address_to_phone: '(347) 610-8896',
  address_to_email: 'bruce.banner@avengers.com',
  shipping_method: 'usps_priority',
  signature_confirmation: false,
  replacement_order: 'fill_request_cb619ca2e133d37daefc',
  metadata: 'cfe146',
  notes: 'Here are some special instructions on how to package this order',
  patient_survey: {
    medications: 'Tafluprost',
    allergies: 'Penicillian',
    conditions: 'Glaucoma'
  }
}

fetch('https://api.truepill.com/v1/fill_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))

Successful Response

{
  "request_id": "fill_request_bd6825a9d66a49b3d7a7",
  "timestamp": 1592183925,
  "status": "success",
  "details": {
    "message": "Your fill request has been processed successfully.",
    "metadata": "cfe146"
  }
}

Error Response - Missing Fields

{
  "statusCode": 400,
  "error": "Bad Request",
  "validation_errors": [
    {
      "key": "address_to_name",
      "message": "is required"
    },
    {
      "key": "address_to_street1",
      "message": "is required"
    },
    {
      "key": "address_to_city",
      "message": "is required"
    },
    {
      "key": "address_to_state",
      "message": "is required"
    },
    {
      "key": "patient_survey",
      "message": "is required"
    }
  ]
}

POST https://api.truepill.com/v1/fill_request

This endpoint generates a Fill Request to fill/refill prescriptions and order Over-the-Counter products. The prescriptions and products requested can be shipped to your patient with various shipping methods.

When making a Fill Request, the patient will be referenced with a patient_token being passed into the request body. If you do not have a patient_token for your Patient, one can be created using the Patient Create endpoint.

On a successful submission of the Fill Request, a fill request token will be provided that is used to reference the Fill Request (similar to prescription_token and patient_token).
This attribute is returned under the field request_id.

Fill Request Body Fields

Field Name	Type	Description and Example	Required?
patient_token	String	4526d90a Token to reference Patient record upon Patient Creation	Yes
patient_payment_type	String	cash or insurance Must be one of these two fields	Yes
insurances	Array	Array of Insurance objects Required if patient_payment_type is set to insurance	See Description
medications	Array	Array of Medication objects to fill	See Description
otc_products	Array	Array of OTC objects to fill. Request must include either medications or otc_products	See Description
address_to_name	String	Patient's name for delivery	Yes
address_to_company	String	ABC Inc.	No
address_to_street1	String	Patient's delivery address	Yes
address_to_street2	String	Apt 456	No
address_to_city	String	Patient's delivery city	Yes
address_to_state	String	Patient's delivery state	Yes
address_to_zip	String	Patient's delivery zip code	Yes
address_to_phone	String	Patient's phone	Yes
patient_survey	JSON	Required information on patient's current health. See Patient Survey section for details	Yes
address_from_company	String	Desired Name to display on the Return section of Shipping Label	No
address_to_email	String	Patient's email	No
metadata	String	Customer-side identifier to reference the Fill Request in Customer system	No
shipping_method	String	One of the following usps_priority, usps_first, usps_priority_express, fedex_2_day fedex_ground, fedex_smart_post fedex_standard_overnight, fedex_priority_overnight Defaults to usps_first	No
signature_confirmation	Boolean	Set to true to request a signature confirmation on delivery	No
notes	String	Additional information customer wishes to convey relating to this Fill Request	No
medication_packaging_type	String	standard vial, custom vial custom bottle single dose pouch multi-dose pouches Multi-dose packaging options	No
is_custom_order	Boolean	Set to true for custom orders only. Contact Truepill for more details.	No
packaging_instructions	String	Specify details of your packaging process for a specific order (Limit 40 characters). Custom packaging	No
replacement_order	String	fill_request_cb619ca2e133d37daefc Fill Request token of the order that this Fill Request is replacing	No
check_in	Boolean	false : Set to true to request a consultation with a Truepill Pharmacist prior to completing the Fill Request. Patient Check	No

Insurances

Fill Request Body with Insurance

{
   "patient_token": "4526d90a",
   "patient_payment_type": "insurance",
   "insurances": [
      {
         "insurance_token": "19sienglo92831n5"
      }
   ],
   "medications": [
      {
         "prescription_token": "z3q2jr"
      },
      {
         "prescription_token": "3cs873"
      }
   ],
   ["...other fields..."]
}

The insurances field accepts an Array of objects with the following fields.

Field Name	Type	Description and Example	Required?
insurance_token	String	Token to reference a Patient's insurance Required if cardholder_id and rx_bin are not provided	See Description
cardholder_id	String	A9321328 Member ID number on insurance card Required if insurance_token is not provided	See Description
rx_bin	String (6 characters)	997928 RX Bin on card, always 6 characters Required if insurance_token is not provided	See Description
rx_group	String	006726 RX group on insurance card	No
pcn	String	AXA Member ID number on insurance card	No
phone_number	String	(955) 372-4143 Insurance provider phone number	No
insurance_card_image_url	String	http://imageurl.jpg Used to manually troubleshoot any claims issues	No

Fill Request Medications

Fill Request Body with Medications

{
   "patient_token": "4526d90a",
   "patient_payment_type": "cash",
   "medications": [
      {
         "prescription_token": "z3q2jr"
      },
      {
         "prescription_token": "3cs873"
      }
   ],
  ["...other fields..."]
}

The medications field accepts an array of objects with the following fields.

When providing the prescription_token only, we will attempt to dispense exactly what was prescribed by the doctor.

You can also control the quantity dispensed on a fill. See Refills for more information.

Field Name	Type	Description and Example	Required?
prescription_token	String	Token to reference exact prescription. See the Prescription section for more details	Yes

Patient Check In

Fill Request Body with Patient Check-In

{
   "patient_token": "4526d90a",
   "patient_payment_type": "insurance",
   "insurances": [
      {
         "insurance_token": "19sienglo92831n5"
      }
   ],
   "medications": [
      {
         "prescription_token": "z3q2jr"
      },
      {
         "prescription_token": "3cs873"
      }
   ],
   "check_in": true,
   ["...other fields..."]
}

Patient Check is available should the patient want to discuss with a pharmacist before dispensing on a refill. Before sending us a refill for an existing patient you must ask them the following questions:

1. Have you started taking any new medication?
2. Have you experienced any new allergies?
3. Have you experienced any side effects?
4. Have you been in the hospital or experienced transitions of care?
5. Have you started using another pharmacy since the last fill?
6. Do you believe the medication is effective?

If your patient wishes to have a consultation with a pharmacist you must either provide them with our phone number or set the check_in field to true on their next Fill Request. Although the responses to these questions are not required, our pharmacists expect API Users to use good faith determination on whether or not to provide our pharmacists with responses in order to help facilitate a patient's treatment.

By setting the check_in field to true, a Truepill Pharmacist will reach out to your patient for a consultation before the Fill Request is processed.

Patient Survey

Fill Request Example with No Patient Survey Information to Report

curl -X POST https://api.truepill.com/v1/fill_request \
   -H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json" \
   -d '{"patient_token": "4526d90a",
      "patient_payment_type": "cash",
      "medications": [
        {
          "prescription_token": "z3q2jr"
        },
        {
          "prescription_token": "3cs873",
        }
      ],
      "patient_survey": {
        "allergies": null,
        "medications": null,
        "conditions": null,
      },
      [...other fields...]
    }'

const body = {
  patient_token: '4526d90a',
  patient_payment_type: 'cash',
  medications: [
    {
      prescription_token: 'z3q2jr'
    },
    {
      prescription_token: '3cs873'
    }
  ],
  patient_survey: {
    medications: null,
    allergies:  null,
    conditions: null
  },
  [...other fields...]
}

fetch('https://api.truepill.com/v1/fill_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))

Fill Request Example with Patient Survey Information to Report

curl -X POST https://api.truepill.com/v1/fill_request \
   -H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json" \
   -d '{"patient_token": "4526d90a",
      "patient_payment_type": "cash",
      "medications": [
        {
          "prescription_token": "z3q2jr"
        },
        {
          "prescription_token": "3cs873",
        }
      ],
      "patient_survey": {
        "allergies": null,
        "medications": null,
        "conditions": null,
        "events":[
          {
            "year":"2019",
            "type":"hospitalization",
            "reason":"food poisoning"
          },
          {
            "year":"2018",
            "type":"surgery",
            "reason":"glaucoma treatment"
          }
        ]
      },
      [...other fields...]
    }'

const body = {
  patient_token: '4526d90a',
  patient_payment_type: 'cash',
  medications: [
    {
      prescription_token: 'z3q2jr'
    },
    {
      prescription_token: '3cs873'
    }
  ],
  patient_survey: {
    medications: "Glaucoma",
    allergies:  "Bimatoprost",
    conditions: "Hay Fever",
    events: [
      {
        year: '2019',
        type: 'hospitalization',
        reason: 'food poisoning'
      },
      {
        year: '2018',
        type: 'surgery',
        reason: 'glaucoma treatment'
      }
    ]
  },
  [...other fields...]
}

fetch('https://api.truepill.com/v1/fill_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))

As part of being a URAC-accredited pharmacy, you are required to collect specific patient safety details for every Fill Request you submit. This includes current medications, allergies and health conditions.

This can be provided in the patient_survey field on the Fill Request.

A Fill Request for a patient without a completed survey will return a successful response initially, but once the order is processed it will be rejected. You will receive a webhook event detailing the rejection reason.

The survey consists of a series of questions about pre-existing conditions, current medications, allergies, hospitalization incidents, smoking frequency, drinking frequency, and several true or false questions. The more information you provide, the better we can serve you and your patients. However, we understand in many cases there is no information to report. In this case, we only require you to send the fields: conditions, medications, and allergies with the value null. We recommend a UI interaction for the patient to interact with to indicate none.

Field Name	Type	Description and Example	Required?
conditions	String or null	Glaucoma Any pre-existing conditions not listed below.	Yes
medications	Array[JSON] or String or null	See below. Other medications prescribed to the patient.	Yes
allergies	String or null	Hay Fever Any allergies this patient has	Yes
events	Array[JSON] or String	See Events below. Details surgery or hospitalization events.	No
smoking_frequency	String	N/A The frequency of smoking, if any.	No
drinking_frequency	String	One drink nightly The frequency of drinking, if any.	No
asthma_breathing	Boolean	false Whether the patient has asthma or breathing problems	No
heart_disease	Boolean	false Whether the patient has heart disease	No
arthritis	Boolean	false Whether the patient has arthritis	No
lung_disorder	Boolean	false Whether the patient has a lung disorder	No
bleeding_clotting_disorder	Boolean	true Whether the patient has a bleeding/clotting disorder	No
neurological_chronic_headaches	Boolean	false Whether the patient has neurological disorders or chronic headaches	No
blood_transfusion	Boolean	false Whether the patient has had a blood transfusion	No
psychiatric_disorder	Boolean	false Whether the patient has a psychiatric disorder	No
bowel_stomach	Boolean	false Whether the patient has Bowel/Stomach problems	No
pulmonary_embolism	Boolean	false Whether the patient has had a pulmonary embolism	No
cancer	Boolean	false Whether the patient has had cancer	No
stroke	Boolean	false Whether the patient has had a stroke	No
cholesterol_disorder	Boolean	false Whether the patient has a cholesterol disorder	No
seizure_epilepsy	Boolean	false Whether the patient has seizures or epilepsy	No
diabetes	Boolean	false Whether the patient has diabetes	No
thyroid_disorder	Boolean	false Whether the patient has a thyroid disorder	No
eye_disorder	Boolean	true Whether the patient has an eye disorder	No
urinary_kidney_disorder	Boolean	true Whether the patient has a Urinary/Kidney disorder	No
pregnancy	Boolean	true Whether the patient is pregnant or not	No

Events Fields

If you choose to provide the patient response in more detail than a freeform text field, the format we expect for the events information is below.

Field Name	Type	Description and Example	Required?
type	String	surgery The type of event, either 'surgery' or 'hospitalization'	Yes
year	Integer or Null	2018 The year of incidence	Yes
reason	String or Null	glaucoma treatment The reason for the event	Yes

Medications Fields

Fill Request Body with Expanded Patient Survey Medication Information

{
   "patient_token": "4526d90a",
   "patient_payment_type": "cash",
   "medications": [
      {
         "prescription_token": "z3q2jr"
      },
      {
         "prescription_token": "3cs873"
      }
   ],
   "patient_survey": {
      "medications": [
        {
          "name": "Sildenafil",
          "strength": 20,
          "dosage": "mg",
          "frequency": "Daily"
        }
      ],
      "allergies": "Bimatoprost",
      "conditions": "Hay Fever",
   },
   ["...other fields..."]
}

If you choose to provide the patient response in more detail than a freeform text field, the format we expect for the other medications field is below. In the medication name field include the length of time the patient has been taking the medication. Additionally, you may provide any over the counter medications or herbal supplements which may interfere with medical treatment through these same fields.

Field Name	Type	Description and Example	Required?
name	String	Tafluprost The name of the medication	Yes
strength	Number	0.05 The strength of the medication	Yes
dosage	String	mg/ml The unit of the strength	Yes
frequency	String	Daily The frequency of medication use	Yes

Fill Request Webhook Events

Order Pending Review Webhook Event

{
  "request_id": "fill_request_0fbbde7492c8b024d800",
  "timestamp": 1571251314,
  "callback_type": "ORDER",
  "status": "pending",
  "details": {
    "metadata": "cfe146",
    "message": "Your fill request is pending pharmacy review",
    "date_filled": "Mon, 01 Jun 2020 17:45:06 GMT",
    "order_token": "b392d",
    "medications": [
      {
        "quantity": 14,
        "medication_name": "Metronidazole 500 mg oral tablet",
        "dispensed_medication_name": "Metronidazole 500 mg oral tablet",
        "days_supply": 7,
        "requested_medication_name": "Metronidazole 500 mg oral tablet",
        "original_requested_prescription_token": "c8226924vf1a",
        "medication_token": "310ca0fa",
        "remaining_refills": {
          "total_remaining_refills": 0,
          "total_quantity_remaining": 0
        },
        "fill_number": "0",
        "rx_number": "1484947",
        "total_refills_allowed": 3,
        "prescription_token": "z3q2jr",
        "patient_cash_amount": null
      },
      {
        "quantity": 14,
        "medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
        "dispensed_medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
        "days_supply": 7,
        "requested_medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
        "original_requested_prescription_token": "bas8292xd",
        "medication_token": "5d466090",
        "remaining_refills": {
          "total_remaining_refills": 0,
          "total_quantity_remaining": 0
        },
        "fill_number": "0",
        "rx_number": "1483253",
        "total_refills_allowed": 3,
        "prescription_token": "3cs873",
        "patient_cash_amount": null
      },
      {
        "requested_medication_name": "Fluconazole 150 mg oral tablet",
        "reject_reason": "Refill too soon",
        "error_code": "79",
        "medication_token": "7ebc894e"
      }
    ],
    "otc_products": [
      {
        "sku": "TPIBPN20",
        "requested_quantity": "5"
      }
    ],
    "location": "Hayward, CA",
    "patient_token": "4526d90a"
  }
}

Successful Order Webhook Event

// note that this completed order has one medication that was unable to be filled
{
  "request_id": "fill_request_0fbbde7492c8b024d800",
  "timestamp": 1571251314,
  "callback_type": "ORDER",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "message": "Your fill request was processed and is pending shipment.",
    "date_filled": "Mon, 01 Jun 2020 17:45:06 GMT",
    "order_token": "b392d",
    "medications": [
      {
        "quantity": 14,
        "medication_name": "Metronidazole 500 mg oral tablet",
        "dispensed_medication_name": "Metronidazole 500 mg oral tablet",
        "original_requested_prescription_token": "c8226924vf1a",
        "days_supply": 7,
        "requested_medication_name": "Metronidazole 500 mg oral tablet",
        "medication_token": "310ca0fa",
        "remaining_refills": {
          "total_remaining_refills": 0,
          "total_quantity_remaining": 0
        },
        "fill_number": "0",
        "rx_number": "1484947",
        "total_refills_allowed": 3,
        "prescription_token": "z3q2jr",
        "patient_cash_amount": null
      },
      {
        "quantity": 14,
        "medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
        "dispensed_medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
        "original_requested_prescription_token": "bas8292xd",
        "days_supply": 7,
        "requested_medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
or        "medication_token": "5d466090",
        "remaining_refills": {
          "total_remaining_refills": 0,
          "total_quantity_remaining": 0
        },
        "fill_number": "0",
        "rx_number": "1483253",
        "total_refills_allowed": 3,
        "prescription_token": "3cs873",
        "patient_cash_amount": null
      },
      {
        "requested_medication_name": "Fluconazole 150 mg oral tablet",
        "reject_reason": "Refill too soon",
        "medication_token": "7ebc894e"
      }
    ],
    "otc_products": [
      {
        "sku": "TPIBPN20",
        "requested_quantity": 5
      }
    ],
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=92001902453595000012688153",
    "location": "Hayward, CA",
    "patient_token": "4526d90a"
  }
}

Error Order Webhook Event - No Refills Remaining

// No additional information required/accompanying this rejection reason
{
  "request_id": "fill_request_2c069215483bb6676a9b",
  "status": "error",
  "timestamp": 1585608018,
  "callback_type": "ORDER",
  "details": {
    "metadata": "cfe146",
    "error_code": "NR",
    "description": "Rejected: No Refills Remaining",
    "message": null,
    "order_token": "b392d",
    "medications": [
      {
        "prescription_token": "z3q2jr"
      },
      {
        "prescription_token": "3cs873"
      }
    ],
    "otc_products": [
      {
        "sku": "TPIBPN20",
        "requested_quantity": 5
      }
    ],
  }
}

Error Order Webhook Event - High Copay

// Rejection reason along with specified copay amount
{
  "request_id": "fill_request_2c069215483bb6676a9b",
  "status": "error",
  "timestamp": 1585608018,
  "callback_type": "ORDER",
  "details": {
    "metadata": "cfe146",
    "error_code": "R009",
    "description": "Rejected: High Copay",
    "message": "$87.49",
    "order_token": "b392d",
    "medications": [
      {
        "prescription_token": "z3q2jr"
      },
      {
        "prescription_token": "3cs873"
      }
    ]
  }
}

Upon receiving a Fill Request, the Truepill pharmacy gets to work on running a claim with the patient’s insurance, reviewing the patient and the prescription, and packaging the prescription for delivery.

When an order is successfully processed and packaged, the order is deemed “completed” and is awaiting delivery to the patient. A success webhook event notification will be sent to the customer as well as three additional Shipment webhook events as the order journeys to the patient address.

If an issue occurs during processing that prevents the prescription from being filled and packaged, the fill request may be rejected. In this case, an Error Webhook Event will be sent to the customer detailing the rejection of the Fill Request.

If an order is blocked by an extraneous circumstance, but is believed to be resolved soon, the order may be moved to a Triage status. A webhook event notification will be sent for Triaged Orders as well.

Successful Fill Request Webhook Event Fields

Field Name	Type	Description and Example
order_token	String	Associated order's url token
patient_token	String	Associated patient's url token
medications	Array of Medications	Array of Medication details
otc_products	Array of OTC Products	Array of OTC item details
tracking_url	String	URL to be used for carrier tracking
metadata	String	Provided by customer
date_filled	String	Filled Date of Rx
location	String	Location where the order was filled
message	String	Plain english status text

Medication

A successfully filled medication object is as follows:

Field Name	Type	Description and Example
prescription_token	String	Token used for looking up an Rx
medication_name	String	Medication name
requested_medication_name	String	Requested medication name
dispensed_medication_name	String	Dispensed (substitution) medication name
original_requested_prescription_token	String	Original prescription token (if applicable)
rx_number	String	Rx number of prescription
patient_copay_amount	Integer	Patient amount paid if insurance order
patient_cash_amount	Integer	Patient amount paid if cash order
days_supply	Integer	Number of days supply
quantity	Integer	Quantity sent
fill_number	String	Prescription refill No. (0 is first fill)
remaining_refills	Remaining Refills	Rx information
total_refills_allowed	Integer	Number of refills allowed
medication_token	String	Associated token for the prescription request

A rejected medication object is as follows:

Field Name	Type	Description and Example
error_code	String	Error code for rejection
reject_reason	String	Reason details for medication rejection
requested_medication_name	String	Requested medication name
medication_token	String	Associated token for the prescription request

OTC Products

An OTC product object is as follows:

Field Name	Type	Description and Example
item_name	String	Item name of OTC item as specified on Fill Request
sku	String	SKU of OTC item as specified on Fill Request
quantity_requested	Integer	Requested quantity of product

Remaining Refills

Field Name	Type	Description and Example
total_remaining_refills	Integer	Total refills remaining on Rx
total_quantity_remaining	Integer	Total quantity across all refills on Rx

Error Webhook Event Fields

Field Name	Type	Description and Example
order_token	String	Associated order's url token
description	String	Rejection reason
message	String	Additional information regarding rejection, if possible - otherwise null
medications	Array	Array of objects containing prescription token (if available)
metadata	String	Provided by customer
error_code	String	Error Codes

Order Error Codes

Each rejection webhook event contains an error code denoting the type of error in the "error_code" field. These codes are accompanied by a text description detailing the error in the “description” field.

If there is additional information that can accompany the error code and description, it will be provided in the "message" field. This occurs on certain rejections such as 'Refill Too Early' (date of refill eligibility), 'High Copay' (copay amount), or 'Other Reason' (rejection specifics).

It is important to note that the same descriptions may correspond to several different error codes.

Table of Error Codes & Associated Information

Code	Description	Message (Additional Information)
R2	Bad Address Details	N/A
12	Bad Insurance Details	Will contain at least one of the following: 'Missing/Invalid Group Number', 'Missing/Invalid PCN', 'Non-Matched Cardholder ID', 'Missing/Invalid DOB'
R004	Coverage Not Effective	N/A
R003	Closed Network	N/A
09	Date of Birth Mismatch	N/A
DI	Drug Interactions	Description of Impeding Drug Interactions
R1	Duplicate Order	The Order Number of Duplicate Order
DT	Duplicate Therapy	Description of Other Duplicate Therapy
R009	High Copay	The High Copay Amount in question
R010	Mail Order Fills Exceeded	N/A
PC	Missing e-RX	N/A
NR	No Refills Remaining	N/A
R0	Order Cancelled by Customer	N/A
R005	Order Rejected by Truepill for Customer	N/A
R019	Other Reason	Specifics of Reason
R3	Out of Stock/Unavailable to Order	N/A
62	Patient Name Mismatch	N/A
75	Prior Authorization Required	N/A
R015	Quantity Limited by Insurance	Limited Quantity information
79	Refill Too Early	Date of Refill Availability
R4	Returned to sender	N/A
R022	Sig Clarification Needed	Description of Required Instructions or Missing Instructions
R017	Test	N/A
R5	Transferred Out of Pharmacy	N/A
R024	Prescription Expired	N/A
R025	Coverage Terminated	N/A
R026	Quantity Mismatch	N/A

Common Failures

Commonly found rejections for orders are:

• Coverage terminated
• Incorrect name or DOB
• Medication is not on approved formulary
• No eRx in prescription
• No refills remaining
• Non-matched cardholder ID
• Prior authorization required
• Refill too soon
• Reimbursement issue

Triage

A Triaged Order Webook Event

// No additional information required/accompanying this triage webhook event
{
  "request_id": "fill_request_2c069215483bb6676a9b",
  "timestamp": 1585608018,
  "callback_type": "ORDER",
  "status": "triage",
  "details": {
    "metadata": "cfe146",
    "message": "This order has been moved to Triage status",
    "code": "T001",
    "description": "Invalid Address",
    "additional_information": null,
    "order_token": "b392d",
    "medications": [
      {
        "prescription_token": "z3q2jr"
      },
      {
        "prescription_token": "3cs873"
      }
    ]
  }
}

// Triage webhook event along with additional information
{
  "request_id": "fill_request_2c069215483bb6676a9b",
  "timestamp": 1585608018,
  "callback_type": "ORDER",
  "status": "triage",
  "details": {
    "metadata": "cfe146",
    "message": "This order has been moved to Triage status",
    "code": "T005",
    "description": "Out of Stock",
    "additional_information": "2020-04-12",
    "order_token": "b392d",
    "medications": [
      {
        "prescription_token": "z3q2jr"
      },
      {
        "prescription_token": "3cs873"
      }
    ]
  },
}

Certain orders may be blocked from being processed further due to external dependencies, but can be resolved in a timely manner. These orders are moved into the TRIAGE status to be identified quickly, and triaged by proper personnel.

A webhook event will be sent to the customer when an order is moved to TRIAGE. Similarly to the ORDER ERROR rejection webhook event, the TRIAGE webhook event contains a code denoting the triage reason in the "code" field. These codes are accompanied by a text description detailing the reason in the “description” field.

If there is additional information that can accompany the triage code and description, it will be provided in the "additional_information" field.

Table of Triage Codes & Associated Information

Code	Description	Additional Information
T001	Invalid Address	N/A
T003	Prior Authorization Required	May include description of Prior Authorization
T004	Customer Clarification Needed	May include description of Desired Customer Clarification
T005	Out of Stock	Date of Stock Availability
T006	Clinical Outreach to MD	Description/Reason of Clinical Outreach
T007	Other Reason	Specifics of Reason

Shipment Webhook Events

Shipment Webhook Event - Arrival to Facility

{
  "request_id": "fill_request_991e90fa6b367cf72032",
  "timestamp": 1590800102,
  "callback_type": "SHIPMENT",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "status": "TRANSIT",
    "message": "Your shipment has arrived at the USPS regional origin facility.",
    "eta": "2020-06-02T00:54:31.838Z",
    "tracking_number": "43904456187100000000000000",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000"
  }
}

Shipment Webhook Event - Package in Transit

{
  "request_id": "fill_request_991e90fa6b367cf72032",
  "timestamp": 1590800162,
  "callback_type": "SHIPMENT",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "status": "TRANSIT",
    "message": "In Transit, Arriving On Time",
    "eta": "2020-06-02T00:54:31.838Z",
    "tracking_number": "43904456187100000000000000",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000"
  }
}

Shipment Webhook Event - Package Delivered

{
  "request_id": "fill_request_991e90fa6b367cf72032",
  "timestamp": 1590800222,
  "callback_type": "SHIPMENT",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "status": "DELIVERED",
    "message": "Your shipment has been delivered at the destination mailbox.",
    "eta": "2020-06-02T00:54:31.838Z",
    "tracking_number": "43904456187100000000000000",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000"
  }
}

When an order is successfully processed and packaged, the order is deemed “completed” and is awaiting delivery to the patient. After a successful order webhook event is sent, additional shipment webhook events will also be sent as the order journeys to the patient address.

These callbacks will have callback_type of SHIPMENT.

Shipment Webhook Event Fields

Field Name	Type	Description and Example
tracking_url	String	URL to be used for carrier tracking
tracking_number	String	Carrier tracking number
status	String	Status of package delivery from carrier
eta	String	ETA of package delivery to patient's address
message	String	Text description of package delivery status from carrier
metadata	String	Customer-side identifier to reference the Fill Request in Customer system

Refills

Example of a Fill Request with Refill Management

curl -X POST https://api.truepill.com/v1/fill_request \
   -H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json" \
   -d '{"patient_token": "4526d90a",
      "patient_payment_type": "insurance",
      "insurances": [
        {
          "insurance_token": "19sienglo92831n5"
        },
      ],
      "medications": [
        {
          "prescription_token": "z3q2jr",
          "quantity": 300
        },
        {
          "prescription_token": "3cs873",
          "quantity: 15
        }
      ],
      "address_to_name": "Bruce Banner",
      [...other fields...]
    }'

const body = {
  patient_token: '4526d90a',
  patient_payment_type: 'insurance',
  insurances: [
    {
      insurance_token: '19sienglo92831n5'
    }
  ],
  medications: [
    {
      prescription_token: 'z3q2jr',
      quantity: 90
    },
    {
      prescription_token: '3cs873',
      quantity: 15
    }
  ],
  address_to_name: 'Bruce Banner',
  [...other fields...]
}

fetch('https://api.truepill.com/v1/fill_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))

Successful Order Webhook Event with Refill Management

// note that the quantity fields in the medications array
{
  "request_id": "fill_request_0fbbde7492c8b024d800",
  "timestamp": 1571251314,
  "callback_type": "ORDER",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "message": "Your fill request was processed and is pending shipment.",
    "date_filled": "Mon, 01 Jun 2020 17:45:06 GMT",
    "order_token": "b392d",
    "medications": [
      {
        "quantity": 90,
        "medication_name": "Metronidazole 500 mg oral tablet",
        "dispensed_medication_name": "Metronidazole 500 mg oral tablet",
        "days_supply": 7,
        "requested_medication_name": "Metronidazole 500 mg oral tablet",
        "medication_token": "310ca0fa",
        "remaining_refills": {
          "total_remaining_refills": 0,
          "total_quantity_remaining": 0
        },
        "fill_number": "0",
        "rx_number": "1484947",
        "total_refills_allowed": 3,
        "prescription_token": "z3q2jr",
        "patient_cash_amount": null
      },
      {
        "quantity": 15,
        "medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
        "dispensed_medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
        "days_supply": 7,
        "requested_medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
        "medication_token": "5d466090",
        "remaining_refills": {
          "total_remaining_refills": 0,
          "total_quantity_remaining": 0
        },
        "fill_number": "0",
        "rx_number": "1483253",
        "total_refills_allowed": 3,
        "prescription_token": "3cs873",
        "patient_cash_amount": null
      },
      {
        "requested_medication_name": "Fluconazole 150 mg oral tablet",
        "reject_reason": "Refill too soon",
        "medication_token": "7ebc894e"
      }
    ],
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=92001902453595000012688153",
    "location": "Hayward, CA",
    "patient_token": "4526d90a"
  }
}

The only difference between a refill and a first fill is that this time around you already have a PatientToken and PrescriptionToken, 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.

A Fill Request can also be partially filled as well.

To dispense multiple fills or partial fills, include a quantity field in the medication object.

For insurance prescriptions, the payer 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 as part of your Fill Request webhook event.

Your medication object passed in on the Fill Request would look like this:

Field Name	Type	Description and Example	Required?
prescription_token	String	Token to reference exact prescription. See the Prescription section for more details	Yes
quantity	Integer	Quantity to dispense	Yes (For Fill Control)

Multi-Dose Packaging

Example of a Fill Request with Multi-Dose Packaging

curl -X POST https://api.truepill.com/v1/fill_request \
   -H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json" \
   -d '{"patient_token": "4526d90a",
      "patient_payment_type": "cash",
      "medications": [
        {
          "prescription_token": "z3q2jr"
        },
        {
          "prescription_token": "3cs873"
        }
      ],
      "medication_packaging_type": "standard vial",
      [...other fields...]
    }'

const body = {
  patient_token: '4526d90a',
  patient_payment_type: 'cash',
  medications: [
    {
      prescription_token: 'z3q2jr'
    },
    {
      prescription_token: '3cs873'
    }
  ],
  medication_packaging_type: 'standard vial',
  [...other fields...]
}

fetch('https://api.truepill.com/v1/fill_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))

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.

Custom Packaging

Example of a Fill Request with Custom Packaging

curl -X POST https://api.truepill.com/v1/fill_request \
   -H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json" \
   -d '{"patient_token": "4526d90a",
      "patient_payment_type": "cash",
      "medications": [
        {
          "prescription_token": "z3q2jr"
        },
        {
          "prescription_token": "3cs873"
        }
      ],
      "packaging_instructions": "promotional Vitamin B product sample",
      [...other fields...]
    }'

const body = {
  patient_token: '4526d90a',
  patient_payment_type: 'cash',
  medications: [
    {
      prescription_token: 'z3q2jr'
    },
    {
      prescription_token: '3cs873'
    }
  ],
  packaging_instructions: 'promotional Vitamin B product sample',
  [...other fields...]
}

fetch('https://api.truepill.com/v1/fill_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))

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_instructions field in the Fill Request API to provide specific details of your packaging process for a specific order. This field is limited to 40 characters so it can be propagated to the shipping label.

Over the Counter Products

Example of a Fill Request with OTC Products

curl -X POST https://api.truepill.com/v1/fill_request \
   -H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json" \
   -d '{"patient_token": "4526d90a",
      "patient_payment_type": "cash",
      "otc_products": [
        {
          "item": "Vitamin B",
          "quantity": 30
        }
      ],
      [...other fields...]
    }'

const body = {
  patient_token: '4526d90a',
  patient_payment_type: 'cash',
  otc_products: [
    {
      item: 'Vitamin B',
      quantity: 30
    }
  ],
  [...other fields...]
}

fetch('https://api.truepill.com/v1/fill_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))

Truepill can support a broad range of non prescription OTC products in addition to the full formulary of prescription products.

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

For Fill Requests containing OTC's, populate the otc_products field with an array of objects with the following fields:

Field Name	Type	Description and Example	Required?
item	String	Product name	Yes
quantity	Integer	Quantity requested	Yes
days_supply	Integer	Number of days the product and quantity should cover	No
customer_item_id	String	Customer item ID	No

Replacing Fill Requests

Example of a Fill Request Replacement

curl -X POST https://api.truepill.com/v1/fill_request \
   -H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json" \
   -d '{"patient_token": "4526d90a",
      "patient_payment_type": "insurance",
      "insurances": [
        {
          "insurance_token": "19sienglo92831n5"
        },
      ],
      "medications": [
        {
          "prescription_token": "z3q2jr",
          "quantity": 300
        },
        {
          "prescription_token": "3cs873",
          "quantity: 15
        }
      ],
      "replacement_order": "fill_request_cb619ca2e133d37daefc",
      [...other fields...]
    }'

const body = {
  patient_token: '4526d90a',
  patient_payment_type: 'insurance',
  insurances: [
    {
      insurance_token: '19sienglo92831n5'
    },
    {
      cardholder_id: '112233445566',
      rx_bin: '172020',
      pcn: 'HDMI',
      rx_group: '444555'
    }
  ],
  medications: [
    {
      prescription_token: 'z3q2jr',
      quantity: 90
    },
    {
      prescription_token: '3cs873',
      quantity: 15
    }
  ],
  replacement_order: 'fill_request_cb619ca2e133d37daefc',
  [...other fields...]
}

fetch('https://api.truepill.com/v1/fill_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))

If an order is lost or damaged on delivery, it can be replaced with a new Fill Request.

When making a new Fill Request to replace a previous one, include the request_id received on the previous Fill Request that the new Fill Request is intended to replace.

You will receive the standard Fill Request API Response containing a new request_id to use as the fill request token.

Get Fill Request

Example of a Get Fill Request

curl --request GET \
  --url https://api.truepill.com/v1/fill_request/fill_request_cb619ca2e133d37daefc \
  --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'

fetch(
  'https://api.truepill.com/v1/fill_request/fill_request_cb619ca2e133d37daefc',
  {
    method: 'GET',
    headers: {
      Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
    }
  }
)
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

{
  "patient_first_name": "Bruce",
  "patient_last_name": "Banner",
  "patient_dob": "19891123",
  "patient_gender": "male",
  "patient_payment_type": "cash",
  "medication_name": "Lipitor",
  "otc_products": [
    {
      "item": "Vitamin C",
      "quantity": 1
    }
  ],
  "quantity_dispensed": 30,
  "days_supply": 30,
  "prescribing_doctor": "Dr. Strange",
  "medication_sig": "Take 1 tablet by mouth at the same time every day.",
  "refill_number": 12,
  "is_refill": true,
  "check_in": true,
  "shipping_method": "usps_first",
  "address_from_name": "",
  "address_from_company": "Avengers",
  "address_from_street1": "1700 S Ampnlett Blvd",
  "address_from_street2": "#221",
  "address_from_city": "San Mateo",
  "address_from_state": "CA",
  "address_from_zip": "94402",
  "address_from_country": "US",
  "address_from_phone": "1-800-368-0038",
  "address_from_email": "support@pharmacy.com",
  "address_to_name": "Peter Parker",
  "address_to_street1": "1700 S Amphlett Blvd",
  "address_to_street2": "#221",
  "address_to_city": "San Mateo",
  "address_to_state": "CA",
  "address_to_zip": "94402",
  "address_to_country": "United States",
  "address_to_phone": "(650) 353-5495",
  "address_to_email": "pharmacy@truepill.com",
  "patient_known_allergies": "Hay Fever",
  "patient_other_medications": "none",
  "notes": "",
  "metadata": "cfe146",
  "status": "pending",
  "created_at": "2021-01-01T00:00:00.000Z",
  "error_code": "R021",
  "rejection_reason": "Drug Interactions",
  "additional_rejection_details": "Rejected on 01/01/2021",
  "triage_reason": "Missing information",
  "additional_triage_details": "Need insurance information",
  "tracking_url": "https://tools.usps.com/origTrackNum=111111111111111"
}

GET https://api.truepill.com/v1/fill_request/{request_id}

Once a Fill Request has been submitted, you can look up the request payload that was submitted at any time for reference with an API request.

This endpoint requires a request_token. You will receive a request_token upon a successful Fill Request API submission response in the request_id field.

Get Fill Request Webhook Events

Example of a Get Fill Request Webhook Events

curl --request GET \
  --url https://api.truepill.com/v1/fill_request/fill_request_cb619ca2e133d37daefc/webhook_events \
  --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'

fetch(
  'https://api.truepill.com/v1/fill_request/fill_request_cb619ca2e133d37daefc/webhook_events',
  {
    method: 'GET',
    headers: {
      Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
    }
  }
)
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

{
  "results": [
    {
      "payload": {
        "timestamp": 1628540166,
        "callback_type": "ORDER",
        "details": {
          "metadata": "Unique Identifier of Client side",
          "message": "Your fill request was processed and is pending shipment.",
          "date_filled": "Mon, 01 Jan 2021 20:16:06 GMT",
          "order_token": "t0k3n",
          "medications": [
            {
              "medication_name": "Sildenafil 100 Mg Tablet",
              "dispensed_medication_name": "Sildenafil 100 Mg Tablet",
              "requested_medication_name": "Sildenafil Tab 100mg Torr 30@",
              "original_requested_prescription_token": "pr3scr1pt10n",
              "days_supply": 30,
              "quantity": 6,
              "fill_number": "1",
              "rx_number": "1376688",
              "total_refills_allowed": 5,
              "prescription_token": "pr3scr1pt10n",
              "medication_token": "a4024b355184",
              "remaining_refills": {
                "total_remaining_refills": 4,
                "total_quantity_remaining": 24
              },
              "rx_link": "rxl_e173b34762298c2d2c863983"
            }
          ],
          "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=11111111111111111111111111",
          "location": "Hayward, CA",
          "patient_token": "p4t13ntt0k3n"
        }
      },
      "delivery_data": {
        "status": "success",
        "status_code": 200
      }
    },
    {
      "payload": {
        "timestamp": 1628695007,
        "callback_type": "SHIPMENT",
        "details": {
          "metadata": "Unique Identifier of Client side",
          "status": "TRANSIT",
          "message": "Your shipment has arrived at the USPS regional origin facility.",
          "eta": "2021-01-02T04:00:00Z",
          "tracking_number": "11111111111111111111111111",
          "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=11111111111111111111111111"
        }
      },
      "delivery_data": {
        "status": "success",
        "status_code": 200
      }
    },
  ],
  "next_page_token": null
}

GET https://api.truepill.com/v1/fill_request/{request_id}/webhook_events?{query}={operator}:{value}

This endpoint returns a list of webhook events and allows for the use of query parameters to scope the results of the request.

A request payload represents the request's timestamp, type, and details.

A request's delivery_data represents the request's status information.

See Get Webhook Events documentation for query parameter details.

Update Fill

Example of an Update Fill Request

curl -X POST https://api.truepill.com/v1/update_request \
   -d api_key=tp_live_key_dwXajyzag6mhXQi1z0Gq9w \
   -d request_id="fill_request_aecafb34372151077db8" \
   -d address_from_company="Avengers" \
   -d address_to_name="Peter Parker" \
   -d address_to_company="" \
   -d address_to_street1="1700 S Amphlett Blvd" \
   -d address_to_street2="#221" \
   -d address_to_city="San Mateo" \
   -d address_to_state="CA" \
   -d address_to_zip="94402" \
   -d address_to_country="US" \
   -d address_to_phone="(347) 610-8896" \
   -d address_to_email="peter.parker@avengers.com" \
   -d shipping_method="usps_priority" \
   -d signature_confirmation="false" \
   -d notes="Here are some special instructions on how to package this order"

const body = {
  request_id: 'fill_request_aecafb34372151077db8',
  address_from_company: 'Avengers',
  address_to_name: 'Peter Parker',
  address_to_company: '',
  address_to_street1: '1700 S Amphlett Blvd',
  address_to_street2: '#221',
  address_to_city: 'San Mateo',
  address_to_state: 'CA',
  address_to_zip: '94402',
  address_to_country: 'US',
  address_to_phone: '(347) 610-8896',
  address_to_email: 'peter.parker@avengers.com',
  shipping_method: 'usps_priority',
  signature_confirmation: false,
  notes: 'Here are some special instructions on how to package this order'
}

fetch('https://api.truepill.com/v1/update_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))

Successful Response

{
  "request_id": "update_request_bc22b83aeb5fc2970920",
  "timestamp": 1511916806,
  "status": "success",
  "details": {
    "message": "Accepted: Order fill_request_7fe917b47ac87a9f3c5a has been updated with the new request parameters."
  }
}

Error Response

{
  "timestamp": 1511913120,
  "status": "error",
  "message": "There was an error updating this request (fill_request_e841dbbf56e1365f69b5), either you are not the owner of the request, or the request has already been processed as either shipped or cancelled. Please contact us at (855) 910-8606 for help if neither is the case."
}

This endpoint amends the fields of an existing Fill Request, such as for correcting an address or changing the shipping method to expedite your order.

Request Fields

Field Name	Type	Description and Example	Required?
request_id	String	fill_request_5c4b21b9aecaea155d67	Yes
address_to_name	String	Peter Parker	Yes
address_to_company	String		No
address_to_street1	String	1700 S Amphlett Blvd	Yes
address_to_street2	String	#221	Yes
address_to_city	String	San Mateo	Yes
address_to_state	String	CA	Yes
address_to_zip	String	94402	Yes
address_to_country	String	US : Use US for all requests	Yes
address_to_phone	String	(347) 676-9989	Yes
address_to_email	String	peter.parker@avengers.com	Yes
address_from_company	String	Desired Name to display on the Return section of Shipping Label	No
shipping_method	String	usps_priority, usps_first, usps_priority_express, fedex_ground, fedex_standard_overnight, fedex_priority_overnight Defaults to usps_first	No
signature_confirmation	Boolean	true, false	No
notes	String	Here are some special instructions on how to package this order	No

Cancel Fill

Example of a Cancel Fill Request

curl -X POST https://api.truepill.com/v1/cancel_request \
   -d api_key="ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -d request_id="fill_request_34f68f71f980f78bb0bc"

const body = {
  request_id: 'fill_request_34f68f71f980f78bb0bc'
}

fetch('https://api.truepill.com/v1/cancel_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))

Example of a Cancel Fill Request for Specific Medications

curl -X POST https://api.truepill.com/v1/cancel_request \
   -d api_key="ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -d request_id="fill_request_34f68f71f980f78bb0bc"
   -d medications='[
      {
         "prescription_token": "z3q2jr"
      },
      {
         "prescription_token": "3cs873"
      }
   ]'

const body = {
  request_id: 'fill_request_34f68f71f980f78bb0bc',
  medications: [
    {
      prescription_token: 'z3q2jr'
    },
    {
      prescription_token: '3cs873'
    }
  ]
}

fetch('https://api.truepill.com/v1/cancel_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))

Successful Response

{
  "request_id": "cancel_request_3a8bc280d8e959287db0",
  "timestamp": 1511224340,
  "status": "success",
  "details": {
    "code": "03",
    "description": "Order Cancelled by Customer Request",
    "message": "Accepted: Order fill_request_34f68f71f980f78bb0bc has been cancelled."
  }
}

Error Response

{
  "timestamp": 1511226167,
  "status": "error",
  "message": "There was an error cancelling this request, either you are not the owner of the request, or have already cancelled the request. Please contact us at (855) 910-8606 for help if neither is the case."
}

POST https://api.truepill.com/v1/cancel_request

This endpoint cancels a Fill Request whose “request_id” field matches the respective user provided text parameter.

Request Fields

Field Name	Type	Description and Example	Required?
request_id	String	fill_request_5c4b21b9aecaea155d67	Yes
medications	Array	Array of Medication objects to cancel	No

Cancelling Medications in Fill Request

Optionally, specific medications can be cancelled on the order itself rather than the entire order.

To do this, pass a medications field on the Cancel Fill Request containing one or more objects with a prescription_token associated with the order that should be cancelled.

If the medications array contains all the prescriptions on the order, the entire Fill Request will be cancelled.

If the medications array contains a prescription that is not associated with the specific Fill Request, it will be ignored and the remaining valid prescriptions will be cancelled on the specific Fill Request.

The medications field accepts an array of objects with the following fields:

Field Name	Type	Description and Example	Required?
prescription_token	String	Token to reference exact prescription to be cancelled. See the Prescription section for more details	Yes

Insurance Billing

Create Insurance

Example of a Create Insurance Request

curl -X POST https://api.truepill.com/v1/insurance \
   --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
   -d patient_token ='4526d90a' \
   -d insurance='{
        "cardholder_id": "A9321328",
        "rx_group": "006726",
        "rx_bin": "997928",
        "pcn": "AXA",
        "phone_number": "(955) 372-4143"
   }'

const body = {
  patient_token: '4526d90a',
  insurance: {
    cardholder_id: 'A9321328',
    rx_group: '006726',
    rx_bin: '997928',
    pcn: 'AXA',
    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))

Successful Response

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

Error Response - Patient Not Found

{
  "message": "Patient not found"
}

Error Response - Missing Fields

{
  "statusCode": 400,
  "error": "Bad Request",
  "validation_errors": [
    {
      "key": "insurance.cardholder_id",
      "message": "is required"
    },
    {
      "key": "insurance.rx_bin",
      "message": "is require
    }
  ]
}

POST https://api.truepill.com/v1/insurance

With a Patient created in the Truepill ecosystem, you can associate an Insurance to that patient with the Create Insurance API endpoint using the patient_token.

Upon a successful response, an insurance_token is provided that can be used along with the existing patient_token for Copay and Fill Requests.

Body Fields

Field Name	Type	Description and Example	Required?
patient_token	String	Token to reference Patient record upon Patient creation	Yes
insurance	Object	See Insurance object fields below	Yes

Insurance Fields

The insurance object is required for all Insurance Requests.

Field Name	Type	Description and Example	Required?
cardholder_id	String	A9321328 Member ID number on insurance card	Yes
rx_bin	String	997928 RX Bin on card, always 6 characters	Yes
rx_group	String	006726 RX group on insurance card	No
pcn	String	AXA Member ID number on insurance card	No
phone_number	String	(955) 372-4143 Insurance provider phone number	No
insurance_card_image_url	String	http://imageurl.jpg Used to manually troubleshoot any claims issues	No

Get Insurance Claim Details

Example of a Get Insurance Claim Request

curl --request GET \
  --url https://api.truepill.com/v1/prescription/29djd02dndu/fill/3 \
  --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'

fetch(
  'https://api.truepill.com/v1/prescription/29djd02dndu/fill/3',
  {
    method: 'GET',
    headers: {
      Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
    }
  }
)
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

[
   {
      "patient_copay_amount":2.42,
      "transaction_code":"B1",
      "transaction_status":"APPROVED",
      "claim_type":"BILLING",
      "transmission_date":"2021-07-16 12:41:30",
      "insurance_type":"PRIMARY",
      "insurance":{
         "group_number":"RX881A",
         "bin":"17142",
         "pcn":null
      },
      "payor":"Health Partners",
      "payor_adjudication_amount":2.5
   },
   {
      "patient_copay_amount":null,
      "transaction_code":"B1",
      "transaction_status":"REJECTED",
      "claim_type":"BILLING",
      "transmission_date":"2021-07-16 12:41:30",
      "insurance_type":"SECONDARY",
      "insurance":{
         "group_number":"RX393",
         "bin":"3939",
         "pcn":null
      },
      "payor":"Some Secondary Partner",
      "payor_adjudication_amount":null,
      "claim_reject_codes":[
         {
            "code":70,
            "message":"Refill Too Soon"
         }
      ]
   },
   {
      "patient_copay_amount":2.42,
      "transaction_code":"B2",
      "transaction_status":"APPROVED",
      "claim_type":"REVERSAL",
      "transmission_date":"2021-07-16 12:41:30",
      "insurance_type":"PRIMARY",
      "insurance":{
         "group":"RX881A",
         "bin":"17142",
         "pcn":null
      },
      "payor":"Health Partners",
      "payor_adjudication_amount":2.5
   }
]

GET https://api.truepill.com/v1/prescription/{prescription_token}/fill/{fill_number}

Given a prescription token and a fill number, the claim information associated with a prescription and that particular fill can be retrieved via API.

All claim information correlating to a specific fill is made available here, including claim rejections and reversals. Claim information is displayed in array format, with each object representing a claim record.

If a claim is rejected, NCPDP codes are also displayed for the particular claim rejection within the claim_reject_codes field.

Claim records are displayed in chronological order. If no claim information is available for a provided prescription_token and fill_number, an empty array is returned.

Available fields in each Claim object:

Claim Object Fields

Field Name	Type	Description and Example
patient_copay_amount	Float	Expected Patient Copay Amount from claim if adjudication is successful. null if claim is Rejected (no copay amount)
transaction_code	String	Adjudication Transaction Type. Typically B1 and B2
transaction_status	String	APPROVED, REJECTED, PAID
claim_type	String	BILLING or REVERSAL
transmission_date	Datetime	Transmission date of adjudication
insurance_type	String	PRIMARY, SECONDARY, TERTIARY
insurance	Object	Insurance Details
payor	String	Payor Name
payor_adjudication_amount	Float	Payor adjudication amount. null if claim is Rejected
claim_reject_codes	Array of Reject Code Objects	Array of objects providing NCPDP Error Codes

Claim Insurance Details

Field Name	Type	Description
bin	String	Insurance BIN number associated to claim
pcn	String	Insurance PCN associated to claim
group_number	String	Insurance Group Number associated to claim

Claim Reject Code Object Fields

Field Name	Type	Description
code	String	NCPDP claim rejection code
message	String	String explanation of the NCPDP claim rejection code

Copay Request

Create Copay Request

Example of a Copay Request

curl -X POST https://api.truepill.com/v1/copay_request \
   --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
   -d patient_token='4526d90a' \
   -d insurance_token='["skhsyq83rkd3uht9"]' \
   -d prescriptions='[
        "z3q2jr",
        "3cs873",
        "wz25v2"
   ]' \
   -d metadata='cfe146' \
   -d notes='This is a note' \
   -d ship_to_state='CA'

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))

Successful 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"
      }
    ]
  }
}

POST https://api.truepill.com/v1/copay_request

This endpoint generates a Copay Request to retrieve copay information on a patient's prescription(s). We can support multiple insurances on a copay request.

Body Fields

Field Name	Type	Description and Example	Required?
patient_token	String	4526d90a	Yes
insurance_token	Array [String]	["skhsyq83rkd3uht9", "ubqfc1a0a17hjb1c", "oi4aafwcsv5zzvvj"]: Submit an array of one or more insurances in priority order [Primary, Secondary, Tertiary]	Yes
prescriptions	Array [String]	["4ddy38", "b5q3t2", "h3r55c"]: List of patient's prescription tokens	Yes
initiate_prior_auth	Boolean	true or false: Set to true to initiate an electronic PA Request at the point of claim rejection	No
metadata	String	Customer-side identifier to reference the Copay Request in Customer system	No
notes	String	Additional information customer wishes to convey relating to this Copay Request	No
ship_to_state	String	State prescription is being shipped to as 2 letter abbreviation	No

Copay Request Webhook Events

Successful Copay Request Webhook Event - All Prescriptions

{
  "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_fillable_date": "2019-07-23T00:00:00.000Z",
        "copay_amount": "21.02",
        "copay_request_prescription_token": "98dagjw",
        "days_supply": "28",
        "quantity": 28
      },
      {
        "prescription_token": "3cs873",
        "insurance_token": "skhsyq83rkd3uht9",
        "status": "completed",
        "next_fillable_date": "2019-08-05T00:00:00.000Z",
        "copay_amount": "1.10",
        "copay_request_prescription_token": "ad92wek",
        "days_supply": "28",
        "quantity": 28
      }
    ]
  }
}

Successful Copay Request Webhook Event with Completed & Rejected Copays

{
  "request_id": "cnpsa8ms8vbs7f52c8y2xchd77tza3nv",
  "status": "success",
  "callback_type": "COPAY",
  "timestamp": 1563916377515,
  "details": {
    "metadata": "cfe146",
    "message": "Here is a list of medications that were checked",
    "patient_token": "4526d90a",
    "prescriptions": [
      {
        "prescription_token": "z3q2jr",
        "insurance_token": "skhsyq83rkd3uht9",
        "status": "rejected",
        "claim_reject_codes": [
          {
            "code": "79",
            "message": "Refill too soon"
          }
        ],
        "copay_request_prescription_token": "17ed9e856d5baba1",
        "next_fill_date": "2020-05-10T00:00:00.000Z"
      },
      {
        "prescription_token": "3cs873",
        "insurance_token": "skhsyq83rkd3uht9",
        "status": "completed",
        "copay_request_prescription_token": "a7da36900cedbd80",
        "next_fill_date": "2020-04-20T20:23:43.000Z",
        "copay_amount": "0",
        "days_supply": "90",
        "quantity": 90
      }
    ]
  }
}

Incoming Copay Requests are processed in our Truepill pharmacy system.

On completion of a copay check request, Truepill will provide a webhook event with the text COPAY in the callback_type field. Like other webhook events, the status field within each prescription object indicates if it was successful.

In a successful copay check, a detailed list of the medications will be provided in the prescriptions field.

If a copay is blocked by an extraneous circumstance, but is believed to be resolved soon, the copay may be moved to a Triage status. A webhook event notification will be sent for Triaged Copays as well.

Successful Copay Request Webhook Event Fields

Field Name	Type	Description
patient_token	String	Associated patient's url token
prescriptions	Array of Copay Prescription Objects	List of prescription copay information
metadata	String	Provided by customer
message	String	Plain English status text

Copay Prescription Object

The prescriptions field houses an array of objects that contain the following fields:

Field Name	Type	Description
prescription_token	String	Associated prescription's url token
insurance_token	String	Associated token for insurance that was used for the Copay Claim
status	String	Status of copay request on associated prescription
next_fill_date	String	Date the associated prescription is fillable
copay_amount	String	Copay price for the associated prescription
copay_request_prescription_token	String	Token for identifying a prescription in a copay request
days_supply	String	Day supply for the associated prescription
quantity	Integer	Quantity for the associated prescription

Handling Copay Request Rejections

Error Copay Request Webhook Event

{
  "request_id": "cnpsa8ms8vbs7f52c8y2xchd77tza3nv",
  "status": "error",
  "callback_type": "COPAY",
  "timestamp": 1563916377515,
  "details": {
    "metadata": "cfe146",
    "message": "This request was rejected. Please see details.",
    "patient_token": "4526d90a",
    "reject_reason": "Other",
    "rejection_reason_other": "Duplicate Copay Request"
  }
}

There are a number of reasons why a Copay Request may be rejected. The most common reasons include:

• Incorrect insurance details
• Refill too soon
• Product not covered.

In an rejected copay check, the webhook event will contain the rejection reason.

Rejected Copay Request Webhook Event Fields

Field Name	Type	Description
patient_token	String	Associated patient's url token
claim_reject_codes	Array of Reject Code Objects	Array of objects providing NCPDP Error Codes
reject_reason	String	A string containing the rejection reason
reject_reason_other	String	Additional information about rejection - if provided
metadata	String	Provided by customer
message	String	Plain English status text

Reject Code Object Fields

Field Name	Type	Description
code	String	NCPDP claim rejection code
message	String	String explanation of the NCPDP claim rejection code

A Simulated Direct Transfer Webhook Event will be identical to a Direct Transfer Webhook Event in production. Note that the patient_token returned will be identical to the one passed in on the request.

Triaged Copay Requests

A Triaged Copay Webhook Event

// Triage webhook event along with additional information
{
  "request_id": "914b810e56445e6ca2ab025c9c96d254",
  "timestamp": 1585608018,
  "callback_type": "COPAY",
  "status": "triage",
  "details": {
    "metadata": "cfe146",
    "message": "This copay has been moved to Triage status",
    "code": "CT004",
    "description": "Refill too soon",
    "additional_information": "2020-08-21",
    "copay_token": "6fb823f403dc5aa3",
    "patient_token": "bd8d80"
  }
}

Certain copays may be blocked from being processed further due to external dependencies, but can be resolved in a timely manner. If desired, these copays can be moved into the TRIAGE status and handled by proper personnel.

A webhook event will be sent to the customer when a Copay Request is moved to TRIAGE. Similarly to the COPAY ERROR rejection webhook event, the TRIAGE webhook event contains a code denoting the triage reason in the "code" field. These codes are accompanied by a text description detailing the reason in the “description” field.

If there is additional information that can accompany the triage code and description, it will be provided in the "additional_information" field.

If a Copay Request is made with initiate_prior_auth set to true, the Copay Request will be moved to Triage if prior authorization is needed, and the Prior Authorization Request is automatically initiated and handled by Truepill.

Table of Triage Codes & Associated Information

Code	Description	Additional Information
CT001	Clinic Outreach	Description/Reason of Clinical Outreach
CT002	Customer Clarification needed	May include description of Desired Customer Clarification
CT003	Prior Authorization needed	May include description of Prior Authorization
CT004	Refill too soon	Date of when medication can be filled
CT005	Pending internal transfer
CT006	Other Reason	Specifics of Reason

Patient Safety API

Your patients’ safety is always our top priority. Our patient safety APIs are the foundation of every step in our pharmacy and telehealth process.

While we leverage our own APIs across our internal workflows, we also explore these safety features through our APIs to ensure patient safety is core to your experience.

Patient Safety Survey

As part of being a URAC-accredited pharmacy, you are required to collect specific patient safety details for every Fill Request you submit. This includes current medications, allergies and health conditions and extends to other health conditions that the patient may have experienced.

This can be provided in the patient_survey field on the Fill Request.

A Fill Request for a patient without a completed survey will return a successful response initially, but once the order is processed it will be rejected. You will receive a webhook event detailing the rejection reason.

The survey consists of a series of questions about pre-existing conditions, current medications, allergies, hospitalization incidents, smoking frequency, drinking frequency, and several true or false questions. The more information you provide, the better we can serve you and your patients. However, we understand in many cases there is no information to report. In this case, we only require you to send the fields: conditions, medications, and allergies with the value null. We recommend a UI interaction for the patient to interact with to indicate none.

Fill Request Example with No Patient Survey Information to Report

curl -X POST https://api.truepill.com/v1/fill_request \
   -H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json" \
   -d '{"patient_token": "4526d90a",
      "patient_payment_type": "cash",
      "medications": [
        {
          "prescription_token": "z3q2jr"
        },
        {
          "prescription_token": "3cs873",
        }
      ],
      "patient_survey": {
        "allergies": null,
        "medications": null,
        "conditions": null,
      },
      [...other fields...]
    }'

const body = {
  patient_token: '4526d90a',
  patient_payment_type: 'cash',
  medications: [
    {
      prescription_token: 'z3q2jr'
    },
    {
      prescription_token: '3cs873'
    }
  ],
  patient_survey: {
    medications: null,
    allergies:  null,
    conditions: null
  },
  [...other fields...]
}

fetch('https://api.truepill.com/v1/fill_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))

Fill Request Example with Patient Survey Information to Report

curl -X POST https://api.truepill.com/v1/fill_request \
   -H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json" \
   -d '{"patient_token": "4526d90a",
      "patient_payment_type": "cash",
      "medications": [
        {
          "prescription_token": "z3q2jr"
        },
        {
          "prescription_token": "3cs873",
        }
      ],
      "patient_survey": {
        "allergies": null,
        "medications": null,
        "conditions": null,
        "events":[
          {
            "year":"2019",
            "type":"hospitalization",
            "reason":"food poisoning"
          },
          {
            "year":"2018",
            "type":"surgery",
            "reason":"glaucoma treatment"
          }
        ]
      },
      "drinking_frequency": "Four drinks weekly",
      "smoking_frequency": "One pack weekly",
      "heart_disease": true,
      "diabetes": true,
      [...other fields...]
    }'

const body = {
  patient_token: '4526d90a',
  patient_payment_type: 'cash',
  medications: [
    {
      prescription_token: 'z3q2jr'
    },
    {
      prescription_token: '3cs873'
    }
  ],
  patient_survey: {
    medications: "Glaucoma",
    allergies:  "Bimatoprost",
    conditions: "Hay Fever",
    events: [
      {
        year: '2019',
        type: 'hospitalization',
        reason: 'food poisoning'
      },
      {
        year: '2018',
        type: 'surgery',
        reason: 'glaucoma treatment'
      }
    ]
  },
  drinking_frequency: 'Four drinks weekly',
  smoking_frequency: 'One pack weekly',
  heart_disease: true,
  diabetes: true,
  [...other fields...]
}

fetch('https://api.truepill.com/v1/fill_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))

Field Name	Type	Description and Example	Required?
conditions	String or null	Glaucoma Any pre-existing conditions not listed below.	Yes
medications	Array[JSON] or String or null	See below. Other medications prescribed to the patient.	Yes
allergies	String or null	Hay Fever Any allergies this patient has	Yes
events	Array[JSON] or String	See Events below. Details surgery or hospitalization events.	No
smoking_frequency	String	N/A The frequency of smoking, if any.	No
drinking_frequency	String	One drink nightly The frequency of drinking, if any.	No
asthma_breathing	Boolean	false Whether the patient has asthma or breathing problems	No
heart_disease	Boolean	false Whether the patient has heart disease	No
arthritis	Boolean	false Whether the patient has arthritis	No
lung_disorder	Boolean	false Whether the patient has a lung disorder	No
bleeding_clotting_disorder	Boolean	true Whether the patient has a bleeding/clotting disorder	No
neurological_chronic_headaches	Boolean	false Whether the patient has neurological disorders or chronic headaches	No
blood_transfusion	Boolean	false Whether the patient has had a blood transfusion	No
psychiatric_disorder	Boolean	false Whether the patient has a psychiatric disorder	No
bowel_stomach	Boolean	false Whether the patient has Bowel/Stomach problems	No
pulmonary_embolism	Boolean	false Whether the patient has had a pulmonary embolism	No
cancer	Boolean	false Whether the patient has had cancer	No
stroke	Boolean	false Whether the patient has had a stroke	No
cholesterol_disorder	Boolean	false Whether the patient has a cholesterol disorder	No
seizure_epilepsy	Boolean	false Whether the patient has seizures or epilepsy	No
diabetes	Boolean	false Whether the patient has diabetes	No
thyroid_disorder	Boolean	false Whether the patient has a thyroid disorder	No
eye_disorder	Boolean	true Whether the patient has an eye disorder	No
urinary_kidney_disorder	Boolean	true Whether the patient has a Urinary/Kidney disorder	No
pregnancy	Boolean	true Whether the patient is pregnant or not	No

Events Object Fields

If you choose to provide the patient response in more detail than a freeform text field, the format we expect for the events information is below.

Field Name	Type	Description and Example	Required?
type	String	surgery The type of event, either 'surgery' or 'hospitalization'	Yes
year	Integer or Null	2018 The year of incidence	Yes
reason	String or Null	glaucoma treatment The reason for the event	Yes

Medications Object Fields

If you choose to provide the patient response in more detail than a freeform text field, the format we expect for the other medications field is below. In the medication name field include the length of time the patient has been taking the medication. Additionally, you may provide any over the counter medications or herbal supplements which may interfere with medical treatment through these same fields.

Field Name	Type	Description and Example	Required?
name	String	Tafluprost The name of the medication	Yes
strength	Number	0.05 The strength of the medication	Yes
dosage	String	mg/ml The unit of the strength	Yes
frequency	String	Daily The frequency of medication use	Yes

Search Drugs, Conditions, and Allergies

You can use the Truepill Patient Safety API to search and retrieve a list of Allergens, Conditions, or Medications for your patient safety experience.

Each of these endpoints work similarly in that you pass in a search keyword and you will retrieve a list of related results.

Search results will be limited to 50 entries

Search Allergies

Example of Allergen Search

curl -X GET https://api.truepill.com/v1/patient_safety/allergies?keyword=pea \
   -H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json"

fetch('https://api.truepill.com/v1/patient_safety/allergies?keyword=pea', {
  method: 'GET',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

[
  "Pear",
  "Tea Tree",
  "Palmitamide MEA",
  "Acetamide MEA",
  "Sea Cucumber",
  "Sea Whip",
  "DEA-Cetyl Phosphate",
  "Disodium Ricinoleamido MEA-Sulfosuccinate",
  "Green Tea (Camellia Sinensis)",
  "Red Beet (Beta Vulgaris)",
  "Sea Parsley (Palmaria Palmata)",
  "Urea",
  "Bee Pollens",
  "Pde5 Inhibitor",
  "Prostaglandins F2a",
  "Glucanase-beta",
  "Red Clover",
  "Imidazolidinyl Urea",
  "Diazolidinyl Urea",
  "Beta-Glucan"
]

GET https://api.truepill.com/v1/patient_safety/allergies?keyword={SEARCH_TERM}

Search Conditions

Example of Conditions Search

curl -X GET https://api.truepill.com/v1/patient_safety/conditions?keyword=pea \
   -H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json"

fetch('https://api.truepill.com/v1/patient_safety/conditions?keyword=pea', {
  method: 'GET',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

[
  "Open wound of head",
  "Open wound of knee and lower leg",
  "Pre-eclampsia",
  "Polycythemia vera",
  "Pre-existing hypertension with pre-eclampsia",
  "Fall from bed",
  "Open wound of neck",
  "Indeterminate sex and pseudohermaphroditism",
  "Abnormalities of heart beat",
  "Crushing injury of head",
  "Open wound of thorax",
  "Cholesteatoma of middle ear",
  "Pedal cycle rider injured in collision with other pedal cycle",
  "Pneumothorax and air leak",
  "Superficial injury of head",
  "Foreign body in ear",
  "Exposure to excessive natural heat",
  "Effects of heat and light",
  "Other diseases of inner ear",
  "Otalgia and effusion of ear"
]

GET https://api.truepill.com/v1/patient_safety/conditions?keyword={SEARCH_TERM}

Search Medications

Example of Medications Search

curl -X GET https://api.truepill.com/v1/patient_safety/medications?keyword=pea \
   -H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json"

fetch('https://api.truepill.com/v1/patient_safety/medications?keyword=pea', {
  method: 'GET',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

[
  "PRE-PEN",
  "PEN-VEE K",
  "PEG-LYTE",
  "GRIS-PEG",
  "BYDUREON PEN",
  "HUMALOG PEN",
  "NUTROPIN AQ PEN",
  "SER-A-GEN",
  "HUMULIN R PEN",
  "LUPRON DEPOT-PED",
  "PEG 3350 AND ELECTROLYTES",
  "EPI E Z PEN JR",
  "EPIPEN E Z PEN",
  "HUMULIN 70/30 PEN",
  "HUMALOG MIX 50/50 PEN",
  "PBZ",
  "PBZ",
  "PCE",
  "WERA",
  "HUMALOG MIX 75/25 PEN"
]

GET https://api.truepill.com/v1/patient_safety/medications?keyword={SEARCH_TERM}

Drug Utilization Review

DUR programs play a key role in helping us prioritize your patient's safety. A DUR is used to understand, interpret, evaluate and improve the prescribing, administration and use of medications.

The most common DUR warning types you will receive from our DUR Request API endpoint include:

(1) Drug-disease contraindications
(2) Drug-allergy interactions
(3) Drug-drug interaction warnings

Create a DUR Request

Example of a DUR Request

curl -X POST https://api.truepill.com/v1/patient_safety/dur_request \
   -H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json" \
   -d '{
        "allergies": ["sildenafil"],
        "conditions": ["history of low blood pressure"],
        "medications": ["ritonavir", "uroxatral"],
        "ndc_package_code": "0093534156",
        "patient_token": "5e2b69fc8dd9fe001c1e5ee9"
      }'

const body = {
  allergies: ['sildenafil'],
  conditions: ['history of low blood pressure'],
  medications: ['ritonavir', 'uroxatral'],
  ndc_package_code: '0093534156',
  patient_token: '4526d90a'
}

fetch('https://api.truepill.com/v1/patient_safety/dur_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))

Successful Response

[
  {
    "severity": "moderate",
    "type": "DRUG-DISEASE-CONTRAINDICATION",
    "warning": "Administration of Sildenafil Citrate Oral Tablet 25 MG should be used with extreme caution in Hypotension.  Since Hypotension is related to Asymptomatic Hypotension, Mild to Moderate Hypotension, Severe Initial Hypotension, and Systolic Hypotension, the same precaution may apply.",
    "subjects": [
      {
        "name": "Asymptomatic Hypotension"
      },
      {
        "name": "Hypotension"
      },
      {
        "name": "Mild to Moderate Hypotension"
      },
      {
        "name": "Severe Initial Hypotension"
      },
      {
        "name": "Systolic Hypotension"
      }
    ]
  },
  {
    "status": "moderate",
    "type": "DRUG-ALLERGY-INTERACTION",
    "warning": "The use of Sildenafil Citrate Oral Tablet 25 MG may result in a reaction based on a reported history of allergy to Sildenafil.",
    "subjects": [
      {
        "name": "Sildenafil"
      }
    ]
  },
  {
    "status": "severe",
    "type": "DRUG-DRUG-INTERACTION",
    "warning": "Pharmacologic effects of Sildenafil Citrate Oral Tablet 25 MG may be increased by Lopinavir-Ritonavir and Ritonavir. Elevated plasma concentrations with toxicity characterized by hypotension, visual disturbances, and priapism may occur. Sildenafil Citrate Oral Tablet 25 MG dosing adjustments are recommended. Coadministration of Lopinavir-Ritonavir and Ritonavir with sildenafil or tadalafil used in the treatment of pulmonary arterial hypertension may be contraindicated in official package labeling.",
    "subjects": [
      {
        "name": "Lopinavir-Ritonavir"
      },
      {
        "name": "Ritonavir"
      }
    ]
  },
  {
    "status": "moderate",
    "type": "DRUG-DRUG-INTERACTION",
    "warning": "Phosphodiesterase type-5 inhibitors and alpha blockers may cause additive hypotension when co-administered. Because symptomatic hypotension may occur caution is advised when vardenafil or tadalafil are co-administered with alpha blockers. Sildenafil may also be used cautiously with alpha blockers; however, doses above 25 mg should be avoided within 4 hours of alpha blocker administration. Avanafil should only be initiated in patients on stable alpha blocker therapy and at a dose of 50 mg.",
    "subjects": [
      {
        "name": "Uroxatral"
      }
    ]
  }
]

POST https://api.truepill.com/v1/patient_safety/dur_request

You can request a drug utilization review from Truepill to determine your patient's safety with a certain medication.

On the request, pass in the patient_token and ndc_package_code, along with the patient's current medications, allergies, and conditions.

DUR Request Body Fields

Field Name	Type	Description	Required?
patient_token	String	Token to reference Patient record upon Patient Creation	Yes
conditions	Array of String or null	List of patient pre-existing conditions	Yes
medications	Array of String or null	Other medications that the patient is currently taking	Yes
allergies	Array of String or null	Known patient allergies	Yes
ndc_package_code	String	NDC package code of drug to review	Yes

The processing time is synchronous, and on a successful DUR request response, you will receive a summary of the review based on the patient information provided.

The summary will typically be provided in an array format containing all the DUR warnings found.

Each DUR warning in the response will contain the following fields:

DUR Response Warning Fields

Field Name	Type	Description
severity	String	mild, moderate, severe : Severity of drug warning for this patient
type	String	DUR assessment type. See below for a complete list of DUR types
warning	String	Written description of drug warning
subjects	Array [JSON]	Array of objects that contain subject keywords relating to the given warning

As shown above, each warning object will have a type field. Below is a list of all of the available types that would be expected in a response:

Type
DRUG-DISEASE-CONTRAINDICATION
DRUG-ALLERGY-INTERACTION
DRUG-DRUG-INTERACTION
EXCESSIVE-DOSES
HIGH-OR-LOW-DOSAGES
DUPLICATE-THERAPY
UTILIZATION
DRUG-AGE-PRECAUTIONS
DRUG-GENDER-PRECAUTIONS
THERAPEUTIC-APPROPRIATENESS
APPROPRIATE-GENERIC-USE
INCORRECT-DRUG-DOSAGE
THERAPEUTIC-INTERCHANGE
GENERIC-SUBSTITUTION
INAPPROPRIATE-TREATMENT-DURATION
CLINICAL-MISUSE

Prior Authorization

Truepill leverages it's own internal workflows and uses industry-standard CoverMyMeds for electronic prior authorization workflows.

Our prior authorization and electronic prior authorization (ePA) workflows are based on the NCPDP SCRIPT standard for ePA.

Prospective vs. Retrospective

There are two ways you can trigger a prior authorization request - they are commonly referred to as "prospectively" by a doctor or "retrospectively" after a claim rejection in the pharmacy. A majority of PA's today are still handled retrospectively at the pharmacy. We will cover the retrospective approach in more detail here and cover the prospective approach in more detail in our Telehealth API.

Using Copay Request vs Prior Authorization API

We provide a streamlined approach to managing your PA process within your Copay Request or a more robust process with our Prior Authorization API.

If you know the medication being dispensed has a low or moderate prevalence of PAs, then you may choose to use the copay request since a bulk of your CopayRequests 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 Request

In this section, we will cover the retrospective prior authorization process as a result of a PA-rejected insurance claim at the pharmacy.

Create a Prior Authorization Request

Example of a Prior Authorization Request

curl -X POST https://api.truepill.com/v1/prior_authorization \
   -H "Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json" \
   -d '{
        "patient_token": "4526d90a",
        "insurance_token": "19sienglo92831n5",
        "prescription_token": "z3q2jr",
        "metadata": "cfe146",
        "prescriber_phone": "1-800-123-4567",
        "prescriber_fax": "1-800-234-5678"
      }'

const body = {
  patient_token: '4526d90a',
  insurance_token: '19sienglo92831n5',
  prescription_token: 'z3q2jr',
  metadata: 'cfe146',
  prescriber_phone: '1-800-123-4567',
  prescriber_fax: '1-800-234-5678'
}

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

Successful Response

{
  "request_id": "prior_auth_bd6825a9d66a49b3d7a7",
  "timestamp": 1592183925,
  "status": "success",
  "details": {
    "message": "Your prior authorization request has been processed successfully.",
    "patient_token": "4526d90a",
    "insurance_token": "19sienglo92831n5",
    "prescription_token": "z3q2jr",
    "metadata": "cfe146",
    "prescriber_phone": "1-800-123-4567",
    "prescriber_fax": "1-800-234-5678"
  }
}

POST https://api.falsepill.com/v1/prior_authorization

A prior authorization can be created by making a Prior Authorization Request. Truepill will provide a receipt confirmation of the request, and multiple subsequent webhook events throughout the lifecycle of your PA.

Prior Authorization Request Fields

Field Name	Type	Description and Example	Required?
patient_token	String	Associated patient's record token	Yes
insurance_token	String	Associated patient's insurance record token	Yes
prescription_token	String	Token to reference the prescription	Yes
metadata	String	Customer-side identifier to reference the PA Request in Customer system	No
prescriber_phone	String	Phone number associated with the prescriber	No
prescriber_fax	String	Fax number associated with the prescriber	No

Managing the Prior Authorization Workflow

A Prior Authorization Webhook Event

{
  "request_id": "8y2xc7tp93nc2csacn2hd7afka3nv",
  "status": "new",
  "callback_type": "PRIOR_AUTH",
  "timestamp": 1563916377515,
  "details": {
    "prior_auth_type": "traditional",
    "message": "The PA has been created, but not yet submitted to plan",
    "patient_token": "4526d90a",
    "prescription_token": "z3q2jr",
    "insurance_token": "19sienglo92831n5",
    "metadata": "cfe146",
    "prescriber_phone": "1-800-123-4567",
    "prescriber_fax": "1-800-234-5678"
  }
}

There are two types of PA Requests: ePA, and a traditional PA. Both of them are managed in the Truepill Prior Authorization API. Traditional PA requests are used with payers who have not yet adopted the new digital standard. The major difference between the two approaches is in the workflow as reflected in the different status updates you will receive.

Status updates are sent using a webhook event with the text PRIOR_AUTH in the callback_type field and references your Prior Authorization Request ID.

Prior Authorization Workflow Statuses

Status	Definition
new	The PA has been created, but not yet submitted to plan. Typically a PA in this status is awaiting action by the provider
submitted	The PA has been submitted to the payer for approval
pending	The PA has been submitted to the payer for approval
approved	The PA has been approved by the payer
declined	The PA has been rejected by the payer
cancelled	The PA has been successfully cancelled
appealed	The PA was appealed and the payer is working to make a determination

Initiating a Prior Auth from Copay Request

Example of a Copay Request with Prior Authorization Initiated

curl -X POST https://api.truepill.com/v1/copay_request \
   --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
   -d patient_token='4526d90a' \
   -d insurance_token='["skhsyq83rkd3uht9"]' \
   -d prescriptions='[
        "z3q2jr",
        "3cs873",
        "wz25v2"
   ]' \
   -d metadata='cfe146' \
   -d initiate_prior_auth=true

const body = {
  patient_token: '4526d90a',
  insurance_token: ['skhsyq83rkd3uht9'],
  prescriptions: ['z3q2jr', '3cs873', 'wz25v2'],
  metadata: 'cfe146',
  initiate_prior_auth: true
}

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))

Prior Authorization Webhook Event - New

{
  "request_id": "8y2xc7tp93nc2csacn2hd7afka3nv",
  "status": "new",
  "callback_type": "PRIOR_AUTH",
  "timestamp": 1563916377515,
  "details": {
    "prior_auth_type": "ePA",
    "message": "The PA has been created, but not yet submitted to plan",
    "prescriber_form": "https://www.secure:prior-authorization.com/request/view/A83ADBK4?token_id=n042aqoali9o9vcfr8ef",
    "patient_token": "4526d90a",
    "prescription_token": "z3q2jr",
    "insurance_token": "19sienglo92831n5",
    "metadata": "cfe146",
    "prescriber_phone": "1-800-123-4567",
    "prescriber_fax": "1-800-234-5678"
  }
}

Prior Authorization Webhook Event - Pending

{
  "request_id": "8y2xc7tp93nc2csacn2hd7afka3nv",
  "status": "pending",
  "callback_type": "PRIOR_AUTH",
  "timestamp": 1563916377515,
  "details": {
    "prior_auth_type": "ePA",
    "message": "The PA has been submitted to the payer for approval",
    "patient_token": "4526d90a",
    "prescription_token": "z3q2jr",
    "insurance_token": "19sienglo92831n5",
    "metadata": "cfe146",
    "prescriber_phone": "1-800-123-4567",
    "prescriber_fax": "1-800-234-5678"
  }
}

Prior Authorization Webhook Event - Approved

{
  "request_id": "8y2xc7tp93nc2csacn2hd7afka3nv",
  "status": "approved",
  "callback_type": "PRIOR_AUTH",
  "timestamp": 1563916377515,
  "details": {
    "prior_auth_type": "ePA",
    "message": "The PA has been approved by the payer",
    "patient_token": "4526d90a",
    "prescription_token": "z3q2jr",
    "insurance_token": "19sienglo92831n5",
    "metadata": "cfe146",
    "prescriber_phone": "1-800-123-4567",
    "prescriber_fax": "1-800-234-5678"
  }
}

Successful Copay Request 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",
        "status": "completed",
        "next_fillable_date": "2019-07-23T00:00:00.000Z",
        "insurance_token": "19sienglo92831n5",
        "copay_amount": "21.02",
        "copay_request_prescription_token": "98dagjw",
        "days_supply": "28",
        "quantity": 28
      }
    ]
  }
}

The prior authorization workflow is covered in full detail in the Prior Authorization Guide. If you need a more streamlined way to manage your PA process, you can do so from within your Copay Request.

With a Copay Request, an electronic PA request can automatically be initiated at the point of claim rejection. If you intend to leverage our PA workflow, you can set the initiate_prior_auth field to true on the Copay Request object.

Once a prior authorization is initiated by Truepill, we will notify you at 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. It will be processed seconds after receiving a PA approval.

Coverage Request

There may be scenarios where you do not have valid insurance details for your patient.

In these situations, you can use the Coverage Request endpoint to run a benefits investigation. If we find valid plans and benefit details, we will send them back to you via a webhook event.

Create Coverage Request

Example of a Coverage Request

curl -X POST https://api.truepill.com/v1/coverage_request \
   --header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
   -d patient_token ='4526d90a' \
   -d metadata='cfe146'

const body = {
  patient_token: '4526d90a',
  metadata: 'cfe146'
}

fetch('https://api.truepill.com/v1/coverage_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))

Successful Response

{
  "request_id": "skhsyq83rkd3uht9",
  "timestamp": 1593452421,
  "status": "success",
  "details": {
    "coverage_request_token": "skhsyq83rkd3uht9",
    "message": "Your coverage request has been processed successfully."
  }
}

POST https://api.truepill.com/v1/coverage_request

This endpoint generates a Coverage Request for Truepill to investigate whether a patient has any valid plans or benefit details. Upon successful API submission, Truepill will provide a receipt confirmation of the request. Results will be sent to your webhook server via Coverage Request Webhook Event.

Body Fields

Field Name	Type	Description and Example	Required?
patient_token	String	4526d90a Token to reference Patient record upon Patient Creation	Yes
metadata	String	cfe146 Customer-side identifier to reference the Fill Request in Customer system	Yes

Coverage Request Webhook Events

Successful Coverage Webhook Event - Patient Insurance Retrieved & In-Network

{
  "request_id": "skhsyq83rkd3uht9",
  "status": "success",
  "callback_type": "COVERAGE",
  "timestamp": 1567026972,
  "details": {
    "metadata": "cfe146",
    "patient_token": "4526d90a",
    "coverage_request_token": "skhsyq83rkd3uht9",
    "insurances": [
      {
        "insurance_token": "0db029",
        "cardholder_id": "XBC1009876543",
        "bin": "880099",
        "group_number": "D96009620",
        "pcn": "SP9E6",
        "plan_type": "commercial",
        "effective_date": "2019-03-01T00:00:00.000Z",
        "termination_date": "2020-02-29T00:00:00.000Z",
        "payer_name": "Anthem BC",
        "person_code": "03",
        "patient_relationship": "Child",
        "help_desk_phone_number": "800-300-2000"
      }
    ]
  }
}

Successful Coverage Webhook Event - Patient Insurance Retrieved & Out-of-Network

{
  "request_id": "skhsyq83rkd3uht9",
  "status": "success",
  "callback_type": "COVERAGE",
  "timestamp": 1567026972,
  "details": {
    "metadata": "cfe146",
    "patient_token": "4526d90a",
    "coverage_request_token": "skhsyq83rkd3uht9",
    "insurances": [
      {
        "insurance_token": "0db029",
        "cardholder_id": "XBC1009876543",
        "bin": "880099",
        "group_number": "D96009620",
        "pcn": "SP9E6",
        "plan_type": "commercial",
        "effective_date": "2019-03-01T00:00:00.000Z",
        "termination_date": "2020-02-29T00:00:00.000Z",
        "payer_name": "Anthem BC",
        "person_code": "03",
        "patient_relationship": "Child",
        "help_desk_phone_number": "800-300-2000"
      }
    ]
  }
}

Error Coverage Webhook Event - Patient Insurance Not Found

{
  "request_id": "skhsyq83rkd3uht9",
  "status": "error",
  "message": "Patient insurance is not found",
  "callback_type": "COVERAGE",
  "timestamp": 1567026972,
  "details": {
    "metadata": "cfe146",
    "patient_token": "4526d90a",
    "coverage_request_token": "skhsyq83rkd3uht9",
    "insurances": null
  }
}

Error Coverage Webhook Event - Patient Social Security Number Not Available

{
  "request_id": "skhsyq83rkd3uht9",
  "status": "error",
  "message": "Patient social security number is not available",
  "callback_type": "COVERAGE",
  "timestamp": 1567026972,
  "details": {
    "metadata": "cfe146",
    "patient_token": "4526d90a",
    "coverage_request_token": "skhsyq83rkd3uht9",
    "insurances": null
  }
}

After submitting a Coverage Request, Truepill will send a webhook event upon completion of the coverage check.

The webhook event will contain the text COVERAGE in the callback_type field.

Coverage Request Webhook Event Fields

Field Name	Type	Description
patient_token	String	Associated patient's token
coverage_request_token	String	Associated coverage request token
insurances	Array	Array of Insurance Objects
metadata	String	Provided by customer

Coverage Insurance Object

The coverage insurance field houses an object that contains the following fields:

Field Name	Type	Description
insurance_token	String	Insurance token
bin	String	Insurance bin number
pcn	String	Insurance PCN
group_number	String	Insurance group
cardholder_id	String	Cardholder ID or Member ID
plan_type	String	commercial or government
effective_date	String	Effective date
termination_date	String	Termination date
payer_name	String	Payer name
person_code	String	Person code
patient_relationship	String	Patient relationship (if applicable)
help_desk_phone_number	String	Payer's help desk phone number

Telehealth API

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

1. Create a Patient
2. Create a Consult Request

Consult API

The Truepill Telehealth API will allow you to easily leverage our nationwide provider network for a clinical telehealth consult by a licensed provider.

The process starts when you request a consult, and similarly to our Pharmacy API endpoints, you will receive notifications about your requested consult through our webhook events. These webhook events will provide updates on the lifecycle of your clinical consult.

Assigning a Provider

Assigning a licensed provider to your consult request is handled seamlessly behind the scenes by our technology. If you are looking to bring your own providers onto our platform, please talk to our team about utilizing our EMR platform and programmable EMR APIs.

Once a provider is assigned to your consult request, you will receive a webhook event notifying you of the assigned provider.

Concepts in POSTing a Consult

Consult Types

Truepill offers two types of consults through the API - asynchronous and synchronous.

An asynchronous consult is a clinical consult where patient-provider interaction is not required. Patients will typically submit clinical data in the form of a patient questionnaire. This questionnaire can be reviewed asynchronously and be used to diagnose and prescribe medications and/or lab orders.

A synchronous consult is a clinical consult where patient-provider interaction is required. Visits can be held either by phone or video conference and can be requested on-demand or scheduled.

For on-demand consults, a provider calls a patient based on the SLA. For scheduled consults, in addition to the SLA, a patient specifies the preferred date and time of the consult.

Questionnaires

Consults are customized to your program. We build consults based on agreed clinical protocol, such as your target diagnosis, target treatment, which can be a prescription and/or lab order, and whether the consult is asynchronous or synchronous. Once your program’s consult has been set up, we provide you with a questionnaireId to submit when creating a new consult.

Standard Questions

Prior to submitting a consult, you must collect from your patients answers to our standard questions:

• Medications
• Allergies
• Medical Conditions

These answers are submitted in the standardQuestions field when creating a consult.

Answers Object

Prior to creating a consult, you may ask your patients questions which are required by your program and will be reviewed by the provider. The answers are submitted in the Answers object. The fields will be a camel-cased representation of the question, which are unique to your questionnaireId and therefore your consult setup.

Consult Workflow Status

As a consult goes through the various stages, Truepill sends a status update on the consult via webhooks. Statuses are:

Consult Workflow Statuses

Status	Definition
assigned	Licensed provider has accepted the Consult Request
review	Licensed provider has started the Consult
issue	Licensed provider has run into an issue (technical, clinical, etc.)
resolved	Care team has resolved the issue the provider encountered, allowing the provider to resume the consult
rejected	Licensed provider has rejected the Consult Request. Rejection reason provided under reject_reason
unassigned	Licensed provider has declined the Consult Request after accepting it
completed	Licensed provider has completed the Consult Request
cancelled	Customer/Care team has cancelled the Consult Request - rare, possibly due to bad or test consult

Create a Consult Request

Example of a Create Consult Request

curl -X POST https://api.truepill.com/consults/v0/consult \
   -H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json" \
   -d '{"metadata": "1234",
      "patient": {
      "firstName": "Jane",
      "lastName": "Doe",
      "gender": "female",
      "dob": "2000-01-01",
      "homeZip": "94538",
      "preferredContact": "email",
      "contacts": {
        "email": "test@truepill.com",
        "phone": "415-234-1234",
        "sms": "415-234-1234"
      }
      },
      "shippingAddress": {
      "line1": "Jane Doe",
      "street1": "123 Steiner St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94115"
      },
      "primaryCareProvider": {
      "name": "Dr. Primary Provider",
      "phone": "555-555-5555",
      "fax": "555-555-5555"
      },
      "paymentType": "cash",
      "preferredTreatment": {
        "rx": [
          {
            "ndc": "ndc_code",
            "daysSupply": "90",
            "quantity": "1",
            "numRefills": "1",
            "allowSubstitutions": false
          }
        ]
        "devices": [
          {
            "hcpcs": "hcpcs_billing_code",
            "quantity": "1"
          }
        ]
      },
      "questionnaire": "603971f14e57401334aa16e0",
      "standardQuestions": {
      "medications": "Xarelto",
      "allergies": "Penicillin",
      "conditions": "Diabetes"
      },
      "answers": {
        "whichOfTheFollowingIstrue": {
        "values": [
          "A hereditary cancer syndrome runs in your family",
          "None of the above"
        ],
        "answers": [
        "None of the above"
        ]
      }
      }
      "appointment": {
        "duration": 3600,
        "apptDate": "2021-06-01T17:00:00.000Z"
      },
}'

const body = {
  metadata: '1234'
  patient: {
    firstName: 'Jane',
    lastName: 'Doe',
    gender: 'female',
    dob: '2000-01-01',
    homeZip: '94538',
    preferredContact: 'email',
    contacts: {
    email: 'test@truepill.com',
    phone: '415-234-1234',
    sms: '415-234-1234'
    }
  },
  shippingAddress: {
    line1: 'Jane Doe',
    street1: '123 Steiner St',
    city: 'San Francisco',
    state: 'CA',
    zip: '94115'
  },
  primaryCareProvider: {
    name: 'Dr. Primary Provider',
    phone: '555-555-5555',
    fax: '555-555-5555'
  },
  paymentType: 'cash',
  preferredTreatment: {
    rx: [
      {
        ndc: 'ndc_code',
        daysSupply: '90',
        quantity: '1',
        numRefills: '1',
        allowSubstitutions: false
      }
    ]
    devices: [
      {
        hcpcs: 'hcpcs_billing_code',
        quantity: '1'
      }
    ]
  },
  questionnaire: '603971f14e57401334aa16e0',
  standardQuestions: {
    medications: 'Xarelto',
    allergies: 'Penicillin',
    conditions: 'Diabetes'
  },
  answers: {
    whichOfTheFollowingIstrue: {
    values: [
       'A hereditary cancer syndrome runs in your family',
       'None of the above'
    ],
    answers: [
    'None of the above'
    ]
    }
  },
  appointment: {
    duration: 3600,
    apptDate: '2021-06-01T17:00:00.000Z'
  },
}

fetch('https://api.truepill.com/consults/v0/consult', {
  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))

Successful Response

{
  "consult": "6dcf35ee85c869d281d85d43"
}

Error Response - Request Fails Validation

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "\"patient.contacts.phone\" with value \"12314512\" fails to match the required pattern: /^\\s*(?:\\+?(\\d{1,3}))?[-. (]*(\\d{3})[-. )]*(\\d{3})[-. ]*(\\d{4})(?: *x(\\d+))?\\s*$/"
}

Error Response - User Accessing Prohibited Resource

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "User is not allowed to access this resource"
}

Error Response - Questionnaire Not Found Or Unauthorized

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Questionaire not found (You may not be authorized to it)."
}

POST https://api.truepill.com/consults/v0/consult

A consult can be created using our Consult API endpoint. Truepill will provide a receipt confirmation of the request and multiple subsequent webhook events throughout the lifecycle of the consult.

Consult Request Fields

Field Name	Type	Description and Example	Required for Async Consult?	Required for Sync Consult?
patient	Object	Patient’s demographics	Yes	Yes
shippingAddress	Object	Patient’s address for shipping medications and lab tests	Yes	Yes
questionaire	String	Unique identifier for the type of consult and questions	Yes	Yes
metadata	String or Stringified JSON	Customer-side identifier	No	No
standardQuestions	Object	Questions on patient’s medication, allergies, and medical conditions	Yes	Yes
answers	Object	Program-specific answers provided by patient before the consult	See description	See description
paymentType	String	cash or insurance	Yes	Yes
insurances	Array	Array of Insurance objects. Required if paymentType is set to insurance	See description	See description
isVideoConsult	Boolean	Whether the sync consult is a video consult	Not applicable	No
otherConsultInfo	Object	Additional consult details	No	No
labTests	Array	Array of objects containing the name, result, notes, and observation of the lab tests	Not applicable	No
documents	Object	Supporting documents for the consult	No	No
primaryCareProvider	Object	Patient’s primary care provider	No	No
attribute	String	Additional identifier	No	No
preferredTreatment	Object	Patient’s or Customer’s preferred treatments - devices, rx, or lab tests	No	No
appointment	Object	Patient’s preferred date and time for the sync consult	No	Yes

Consult Webhook Events

Consult Webhook Event - Consult Assigned

{
  "consult_id": "6dcf35ee85c869d281d85d43",
  "timestamp": 1597777734,
  "callback_type": "CONSULT",
  "status": "assigned",
  "details": {
    "message": "Licensed provider has accepted the Consult",
    "provider": "Doogie Howser",
    "metadata": "1234"
  }
}

Consult Webhook Event - Consult Review

{
  "consult_id": "6dcf35ee85c869d281d85d43",
  "timestamp": 1597777734,
  "callback_type": "CONSULT",
  "status": "review",
  "details": {
    "message": "Licensed provider has started the Consult",
    "provider": "Doogie Howser",
    "metadata": "1234"
  }
}

Consult Webhook Event - Consult Rejected

{
  "consult_id": "6dcf35ee85c869d281d85d43",
  "timestamp": 1597777734,
  "callback_type": "CONSULT",
  "status": "rejected",
  "details": {
    "reject_reason": "Patient is not eligible",
    "message": "Licensed provider has rejected the Consult Request. Rejection reason provided under `reject_reason`",
    "provider": "Doogie Howser",
    "metadata": "1234"
  }
}

Consult Webhook Event - Consult Completed

{
  "consult_id": "6dcf35ee85c869d281d85d43",
  "timestamp": 1597777734,
  "callback_type": "CONSULT",
  "status": "completed",
  "details": {
    "state": ["rx_prescribed", "lab_test_authorized"],
    "message": "Licensed provider has completed the Consult Request",
    "provider": "Doogie Howser",
    "metadata": "1234"
  }
}

Our telehealth platform provides real-time visibility into the status of your consults. You will receive a series of webhook events relating to the status of your consult as it is being processed.

Consult Webhook Events will be identified with the text CONSULT in the callback_type field. The status field will indicate the current status of the Consult.

File Interaction Webhook Events

File Interaction Webhook Event - File Uploaded

{
   "timestamp":1625237490,
   "consult_id":"60a81aca1b9368001c503783",
   "callback_type":"FILE",
   "details":{
      "metadata":"METADATA",
      "documents":[
         {
            "status":"UPLOADED",
            "documentId":"60df27f1b5f815001c74b84d",
            "tags":[
               "SELFIE"
            ]
         },
         {
            "status":"UPLOADED",
            "documentId":"60df27f1b5f815001c74b84e",
            "tags":[
               "PHOTO_ID"
            ]
         }
      ]
   }
}

File Interaction Webhook Events are sent when a patient’s photo for identification or selfie is uploaded. The webhook event has the FILE in the callback_type field.

Get a Consult

Example of a Get Consult Request

curl --request GET \
  --url https://api.truepill.com/consults/v0/consult/6010ab456436f5291efa8ab0
  --header 'authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \

fetch('https://api.truepill.com/consults/v0/consult/6010ab456436f5291efa8ab0', {
  method: 'GET',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

{
  "id": "6010ab456436f5291efa8ab0",
  "labTests": [{
    "id": "6010ab456436f5291efa8ab0",
    "name": "A1C",
    "status": "made",
    "created_at": "2000-01-01T23:52:37.982Z",
    "valid_at": "2000-01-01T23:52:37.982Z",
    "expires_at": "2000-01-01T23:52:37.982Z",
    "results": {
      "name": "A1C Result",
      "observation": "Positive",
      "observed_at": "2021-01-26"
    }
  }],
  "prescriptions": [{
    "id": "6010ab456436f5291efa8ab0",
    "ndc": "52817029500",
    "name": "Sildenafil",
    "strength": "20mg",
    "days_supply": 30,
    "refills": 2,
    "sig": "Take 3 tablets as needed 1 hour before sex (max once daily)",
    "quantity": 3,
    "created_at": "2000-01-01T23:52:37.982Z"
  }],
  "provider": {
    "npi": 1306394952,
    "first_name": "Maria"
    "last_name": "ABAD"
  }
}

Error Response - User Is Not Allowed To Access This Resource

{
   "statusCode": 401,
   "error": "Unauthorized",
   "message": "User is not allowed to access this resource"
}

GET https://api.truepill.com/consults/v0/consult/{consult_id}

Once a consult has been created, you can access the associated prescription, lab order, and provider information using the GET consult endpoint. The consultId can be found on the Create Consult response.

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 at-home lab tests.

The process starts when you request a lab kit, and similarly to our Pharmacy API endpoints, you will receive notifications about your requested kit through our webhook events. These webhook events will provide updates on the lifecycle of the diagnostic test.

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

Create a New Order

POST https://api.truepill.com/diagnostics/v0/orders

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.

Example of a Create Order Request

const body = {
  {
    patient_token: "838a906bcc6e7671",
    insurance_token: "9502a8162af55927",
    kit_id: "e457d2e7-ebf4-403c-b2c1-a1970f16d011",
    test_id: "84e14b68-0372-4d5b-9a33-5e3fe5b43247",
    address: {
        name: "Bill Lumbergh",
        street1: "1234 Main St",
        street2: "Apt 9B",
        city: "Austin",
        state: "TX",
        zip: "78744"
    },
    physician: {
        first_name: "Bob",
        last_name: "McDonald",
        npi: "1234567890"
    },
    custom_data_1: "string",
    custom_data_2: "string",
    custom_data_3: "string"
  }
}

fetch('https://api.truepill.com/diagnostics/v0/orders', {
  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))

Create Order Body Fields

Field Name	Type	Description and Example	Required?
patient_token	String	4526d90a Token to reference Patient record upon Patient Creation	Required if patient information isn't provided. Only provide patient OR patient_token
patient	Object	Patient Object	Required if patient token isn't provided. Only provide patient OR patient_token
kit_id	String	ID indicating which kit should be ordered	No
test_id	String	ID indicating which test should to be ordered	Yes
address	Object	Shipping Address Object	No
physician	Object	Physician providing requisition	No
insurance_token	String	Token to reference Insurance record upon Insurance Creation	Only provide insurance OR insurance_token. Neither are required
insurance	Object	Insurance Object	Only provide insurance OR insurance_token. Neither are required
custom_data_1	String	A custom data string for external use. This can be any arbitrary UTF-8 string	No
custom_data_2	String	A custom data string for external use. This can be any arbitrary UTF-8 string	No
custom_data_3	String	A custom data string for external use. This can be any arbitrary UTF-8 string	No

Shipping Address Fields

The address object has the information for where test kits should be shipped. This may not be the same as a patient's normal mailing addresses (as supplied on the patient object), such as if a patient has multiple residences or uses a mailing address that's not able to receive packages. Most partners using this API won't need to care about the distinction, as contact information outside of this shipping address should only be necessary for special cases. In those cases a validation error will be returned.

Field Name	Type	Description and Example	Required?
name	String	Name of diagnostic receiver	Yes
street1	String	1234 Main St	Yes
street2	String	Apt #2	No
city	String	Austin	Yes
state	String	TX	Yes
zip	String	78744	Yes

Physician Fields

Field Name	Type	Description and Example	Required?
first_name	String	Bruce	Yes
last_name	String	Banner	Yes
npi	String	1497742761	Yes

Insurance Fields

Field Name	Type	Description and Example	Required?
payer_name	String	payer name	Yes
group_id	String	Group ID on insurance card	Yes
member_id	String	Member ID on insurance card	Yes
bin	String	RX Bin on card, always 6 characters	Yes

Register a New Order

POST https://api.truepill.com/diagnostics/v0/orders/register

If a kit already exists for a patient, use this endpoint to register a new order using the existing kit serial.

Example of a Register Order Request

const body =
  {
    patient_token: "838a906bcc6e7671",
    insurance: {
        payer_name: "Bruce Banner",
        group_id: "006726",
        member_id: "A9321328",
        bin: "997928"
    },
    kit_id: "e457d2e7-ebf4-403c-b2c1-a1970f16d011",
    kit_serial: "010081187701133017333333101H",
    test_id: "84e14b68-0372-4d5b-9a33-5e3fe5b43247",
    address: {
        name: "Bill Lumbergh",
        street1: "1234 Main St",
        street2: "Apt 9B",
        city: "Austin",
        state: "TX",
        zip: "78744"
    },
    physician: {
        first_name: "Bob",
        last_name: "McDonald",
        npi: "1234567890"
    },
    custom_data_1: "string",
    custom_data_2: "string",
    custom_data_3: "string"
}

fetch('https://api.truepill.com/diagnostics/v0/orders/register', {
  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))

Successful Response from Create and Register Orders

{
      id: "63a2d847-9d95-4b24-a31a-a15e5a8819bd",
      test: {
        id: "84e14b68-0372-4d5b-9a33-5e3fe5b43247",
        name: "Covid Antigen Test"
      },
      kit: {
        id: "f4fa75be-7112-4d0b-8f4d-97fe81bddfa8",
        sku: "Abbott Rapid Antigen Kit"
      },
      status: "PENDING",
      updated_at: "2021-06-08T14:10:08.512Z",
      patient: {
        first_name: "Bruce",
        last_name: "Banner",
        dob: {
          year: 1993,
          month: 10,
          day: 21
        },
        gender: "male",
        zip: "60660"
      },
      address: {
        name: "Bruce Banner",
        street1: "6102 N. Sheridan Rd",
        street2: "Apt 8K",
        city: "San Mateo",
        state: "CA",
        zip: "60660"
      },
      physician: {
        first_name: "Captain",
        last_name: "America",
        npi: "123456"
      },
      insurance: {
        payer_name: "Bruce Banner",
        group_id: "006726",
        member_id: "A9321328",
        bin: "997928"
      },
      custom_data_1: "custom_data_1",
      custom_data_2: "custom_data_2",
      custom_data_3: "custom_data_3"
}

Register Order Fields

Field Name	Type	Description and Example	Required?
patient_token	String	4526d90a Token to reference Patient record upon Patient Creation	Required if patient information isn't provided. Only provide patient OR patient_token
patient	Object	Patient Object	Required if patient token isn't provided. Only provide patient OR patient_token
kit_id	String	ID indicating which kit should be ordered	No
kit_serial	String	Serial number of the kit to associate with this order	No
test_id	String	ID indicating which test should to be ordered	Yes
address	Object	Address Object	No
physician	Object	Physician providing requisition	No
insurance	Object	Insurance Object	Only provide insurance OR insurance_token. Neither are required
insurance_token	String	Token to reference Insurance record upon Insurance Creation	Only provide insurance OR insurance_token. Neither are required
custom_data_1	String	A custom data string for external use. This can be any arbitrary UTF-8 string	No
custom_data_2	String	A custom data string for external use. This can be any arbitrary UTF-8 string	No
custom_data_3	String	A custom data string for external use. This can be any arbitrary UTF-8 string	No

Get Orders

GET https://api.truepill.com/diagnostics/v0/orders

Get Orders Successful Response

{
  next_page_token: "eyJ0eXBlIjoiT3JkZXJTZWFyY2giLCJsaW1pdCI6IjEiLCJxdWVyeVBhcmFtcyI6eyJ1cGRhdGVkX2F0IjoiJGx0ZToyMDIxLTA2LTA4VDE0OjEwOjA4LjUxMloiLCJpZCI6IiRsdDo2M2EyZDg0Ny05ZDk1LTRiMjQtYTMxYS1hMTVlNWE4ODE5YmQifX0=",
  results: [
      id: "63a2d847-9d95-4b24-a31a-a15e5a8819bd",
      test: {
        id: "84e14b68-0372-4d5b-9a33-5e3fe5b43247",
        name: "Covid Antigen Test"
      },
      kit: {
        id: "f4fa75be-7112-4d0b-8f4d-97fe81bddfa8",
        sku: "Abbott Rapid Antigen Kit"
      },
      status: "PENDING",
      updated_at: "2021-06-08T14:10:08.512Z",
      patient: {
        first_name: "Bruce",
        last_name: "Banner",
        dob: {
          year: 1993,
          month: 10,
          day: 21
        },
        gender: "male",
        zip: "60660"
      },
      address: {
        name: "Bruce Banner",
        street1: "6102 N. Sheridan Rd",
        street2: "Apt 8K",
        city: "San Mateo",
        state: "CA",
        zip: "60660"
      },
      physician: {
        first_name: "Captain",
        last_name: "America",
        npi: "123456"
      },
      insurance: {
        payer_name: "Bruce Banner",
        group_id: "006726",
        member_id: "A9321328",
        bin: "997928"
      },
      custom_data_1: "custom_data_1",
      custom_data_2: "custom_data_2",
      custom_data_3: "custom_data_3"
  ]
}

This endpoint accepts the following optional query parameters.

Get Order Optional Query Params

Field Name	Type	Required?
limit	number	No
test_id	DSL	No
kit_id	DSL	No
custom_data_1	String	No
custom_data_2	String	No
custom_data_3	String	No
page_token	String	No

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.

Get Lab Results Successful Response

{
  name: "FEVER CHECK",
  quantitative_value: "100.4",
  qualitative_value: "POSITIVE",
  measured_at: "2011-10-05T14:48:00.000Z"
}

Get Kits

To see all the associated kits, make an API request to GET /v0/kits API endpoint.

Get Kits Successful Response

[
   {
       "id": "84e14b68-0372-4d5b-9a33-5e3fe5b43247",
       "name": "Covid Antigen Test"
   },
   {
       "id": "3bf13fa4-88a4-4d88-9fc1-354e3f5e804f",
       "name": "Smelly Feet Test"
   },
   {
       "id": "e1bb0922-abaf-4cd6-a3ab-4423c4d1cd89",
       "name": "Fecal Immunochemical Test (FIT)"
   },
   {
       "id": "489f88c2-26e5-4054-b785-6a0bbca1d607",
       "name": "Levels Phlebotomy Test"
   }
]

Get Tests

To see all the associated tests, make an API request to GET /v0/tests API endpoint.

Get Tests Successful Response

[
   {
       "id": "5d03c2b9-9a92-4745-83b1-2312599ca1c3",
       "sku": "SampleCorp Covid Antigen Kit"
   },
   {
       "id": "28695dee-0342-433a-9b74-dd4a5ca586dd",
       "sku": "MattCorp Covid Antigen Kit"
   },
   {
       "id": "caf314e4-6c16-4075-a418-a28baa8d0c0a",
       "sku": "SmellyCorp Smell Kit"
   },
   {
       "id": "62463f99-dba5-47bc-a850-b4fdb2d07fda",
       "sku": "MTL Kit"
   },
   {
       "id": "f4fa75be-7112-4d0b-8f4d-97fe81bddfa8",
       "sku": "Abbott Rapid Antigen Kit"
   }
]

Diagnostics Webhook Events

The request_id given in a Diagnostics webhook event will reflect the original order corresponding to this Diagnostics handling. However, since these events can be triggered by our integrations with external partners, a change in the Diagnostics status may not always be reflected by an immediate change in the order status in our system.

Diagnostics Webhook Event - Order Status Update

{
  "request_id": "skhsyq83rkd3uht9",
  "timestamp": 1581019462,
  "callback_type": "DIAGNOSTICS",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "order_token": "b392d",
    "patient_token": "838a906bcc6e7671",
    "diagnostics_order_id": "44db59cb-3ab2-4ef6-8b88-db3130d6ef7b",
    "status": "SHIPPED_TO_CUSTOMER"
  }
}

Diagnostics Webhook Details Fields

Field Name	Type	Description
metadata	String	Metadata value originally given for associated order
order_token	String	Associated order's URL token
patient_token	String	Associated patient's URL token
diagnostics_order_id	String	Diagnostics-specific order UUID (not used by other APIs)
status	String (see Diagnostics Status table)	The updated status of the Diagnostics workflow for this order

Diagnostics Status	Description
PENDING	Nothing has been done with the order yet
AWAITING_SHIPMENT	The order has been processed but the appropriate test kit hasn't been shipped yet
SHIPPED_TO_CUSTOMER	The test kit for the order has been shipped to the patient
CUSTOMER_HAS_KIT	The test kit for the order has been received by the patient
SHIPPED_TO_LAB	The test kit for the order has been completed and sent from the patient to the lab
LAB_HAS_KIT	The lab have received the completed test kits from the patient, but hasn't finished processing it yet
COMPLETED	All test processing on the order's test kit is finished and results are ready
REJECTED	The order's test kit has been rejected from test processing for some reason

Because labs will often have their own unique workflows and processes, we use a very broad set of statuses for Diagnostics processing. These are meant to represent the broad strokes of the process in a way that should be generically compatible with the workflows used by most labs. Usually action will only need to be taken following the COMPLETED status (indicating that results are ready) or the REJECTED status (indicating that some kind of manual intervention is necessary), and other statuses can be used to monitor the flow of test kits through the system. Other statuses should generally only need action taken if an order spends an excessive amount of time at a given status (for example, an order remaining in CUSTOMER_HAS_KIT status because a patient has forgotten to complete and send out the test kit).

Usually the statuses from AWAITING_SHIPMENT to COMPLETED should be received in the order given here. If they aren't, that means some unusual case has happened, such as a test kit needing to be re-sent to a patient.

Some statuses will be skipped depending on the nature of the test and kit. For instance, some kits are able to give an instantaneous result without requiring shipment to a lab. So, while order should be maintained, it is not unusual to skip a few statuses.

Sandbox

An interactive sandbox can be found at https://api.falsepill.com/documentation?tags=diagnostics

If you are interested in obtaining an API key, contact Truepill through our website, or reach out to your Truepill contact directly.

Prescriber

Create a Prescriber

Example of a Create Prescriber Request

const body =
  {
    first_name: "Bruce",
    last_name: "Banner",
    dea: "DEA1234",
    npi: "1497742761",
    active: true,
    address: {
        clinic_name: "Avengers Headquarters",
        street1: "123 Some Lane",
        street2: "Apt. 123",
        city: "Los Angeles",
        state: "CA",
        zip: "99402",
        country: "US",
        phone: "430-304-3949",
        email: "hulkout@hulk.com",
        fax: "fax"
    }
}

fetch('https://api.truepill.com/v1/prescriber', {
  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))

Successful Response

{
  "prescriber_token": "4526d90a"
}

Error Response - Missing Fields

{
  "statusCode": 400,
  "error": "Bad Request",
  "validation_errors": [
    {
      "key": "last_name",
      "message": "is required"
    },
    {
      "key": "state",
      "message": "is required"
    }
  ]
}

POST https://api.truepill.com/v1/prescriber

This endpoint creates a prescriber in the Truepill ecosystem and assigns it to you as a customer.

Upon a successful request, this endpoint returns a prescriber_token for you to reference in subsequent API requests that require this field.

Create Prescriber Body Fields

Field Name	Type	Description and Example	Required?
first_name	String	Bruce	Yes
last_name	String	Banner	Yes
npi	String	1497742761	Yes
active	Boolean	true	Yes
address	Object	Object containing Prescriber Address Fields	Yes
dea	String	DEA1234	No

Create Prescriber Address Fields

Field Name	Type	Description and Example	Required?
clinic_name	String	Avengers Headquarters	No
street1	String	123 Some Lane	Yes
street2	String	Apt. 123	No
city	String	Los Angeles	Yes
state	String	CA	Yes
zip	String	95162	Yes
country	String	US (default)	No
phone	String	430-304-3949	Yes
email	String	hulkout@hulk.com	No
fax	String	430-304-3949	No

Get a Prescriber

Example of a Get Prescriber Request

curl --request GET \
  --url https://api.truepill.com/v1/prescriber/6ce427
  --header 'authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \

fetch('https://api.truepill.com/v1/prescriber/6ce427', {
  method: 'GET',
  headers: {
    Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

{
  "first_name": "Bruce",
  "last_name": "Banner",
  "dea": "DEA1234",
  "npi": "1497742761",
  "address": {
    "name": "Bruce Banner",
    "street1": "123 Some Lane",
    "street2": "Apt. 123",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "94402",
    "country": "US",
    "phone": "430-304-3949",
    "email": "hulkout@hulk.com",
    "fax": "fax"
  },
  "prescriber_token": "6ce427"
}

Error Response - Prescriber Not Found

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Unable to find Prescriber."
}

GET https://api.truepill.com/v1/prescriber/{prescriber_token}

Once a prescriber has been created in the Truepill ecosystem, you can access the prescriber information at any time using the prescriber_token that was provided in the Create Prescriber response.

If the prescriber_token does not map to a patient_record a 404 Not Found will be returned.

Sandbox Testing with Simulations

In the sandbox environment, Truepill's live systems for managing eRx's don't exist. To make up for this, The Sandbox environment houses frameworks to simulate these webhook events and prescriptions.

This will be important and useful as you test your integration end-to-end with Truepill's platform on the Sandbox environment.

Below are the API’s that have simulations in place:

• Patient & Prescription
• Copay Request
• Fill Request
• Direct Transfer

Simulations are available ONLY on the Sandbox environment. As such, the code examples in this section hit api.falsepill.com

Patient & Prescription

Creating a Patient and Two Prescriptions: One with Default Rx Information and One with Custom Information

curl -X PUT https://api.falsepill.com/v1/patient \
   --header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
   -d '{
      "first_name": "David",
      "last_name": "Doe",
      "dob": "19820115",
      "gender": "male",
      "company": "Example Company",
      "street1": "123 Some Lane",
      "street2": "UNIT 301",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "94402",
      "phone": "001000000000",
      "email": "example@email.com",
      "simulation": {
        "newRx": [
          true,
          {
            "medication_sig": "Take one every two hours",
            "prescriber": "Dr. Strange",
            "days_supply": "1",
            "num_refills_filled": "2",
            "refills_remaining": 4,
            "quantity_remaining": 48,
            "number_of_refills_allowed": 4,
            "prescribed_drug_strength": "50 mg",
            "prescribed_ndc": "55555555555",
            "prescribed_quantity": 12,
            "prescribed_unit_text": "EA",
            "prescribed_label_type": "Generic",
            "prescribed_brand_name": "Generic Label",
            "prescribed_written_name": "Generic Label 50mg Tablet",
            "prescribed_generic_name": "Generic 50mg tablet",
            "dispensed_drug_strength": "50 mg",
            "dispensed_ndc": "55555555555",
            "dispensed_quantity": 12,
            "dispensed_days_supply": 1
          }
        ]
      }
    }'

const body = {
  first_name: 'David',
  last_name: 'Doe',
  dob: '19820115',
  gender: 'male',
  company: 'Example Company',
  street1: '123 Some Lane',
  street2: 'UNIT 301',
  city: 'Los Angeles',
  state: 'CA',
  zip: '94402',
  phone: '001000000000',
  email: 'example@email.com',
  simulation: {
    newRx: [
      true,
      {
        medication_sig: 'Take one every two hours',
        prescriber: 'Dr. Strange',
        days_supply: '1',
        num_refills_filled: '2',
        refills_remaining: 4,
        quantity_remaining: 48,
        number_of_refills_allowed: 4,
        prescribed_drug_strength: '50 mg',
        prescribed_ndc: '55555555555',
        prescribed_quantity: 12,
        prescribed_unit_text: 'EA',
        prescribed_label_type: 'Generic',
        prescribed_brand_name: 'Generic Label',
        prescribed_written_name: 'Generic Label 50mg Tablet',
        prescribed_generic_name: 'Generic 50mg tablet',
        dispensed_drug_strength: '50 mg',
        dispensed_ndc: '55555555555',
        dispensed_quantity: 12,
        dispensed_days_supply: 1
      }
    ]
  }
}

fetch('https://api.falsepill.com/v1/patient', {
  method: 'PUT',
  headers: {
    Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

{
    "patient_token": "838a906bcc6e7671"
}

PUT https://api.falsepill.com/v1/patient

Begin the walkthrough by first creating a new Patient and Prescription in the system.

Simulating a Prescription in Sandbox

In the Sandbox environment, prescriptions can be generated by passing in a simulation object on the Create Patient endpoint. Within the simulation object should be an attribute named newRx, which houses an array.

Multiple prescriptions can be generated at once for a singular patient by populating the newRx array with multiple values. If true is passed in within the newRx array, a prescription will be generated with default sample properties.

These properties can be overridden with custom prescription information. The overridable fields are detailed below:

Field Name	Type	Default Value
medication_sig	String	"Take one Daily"
prescriber	String	"Dr. P. Scribe"
days_supply	String	"28"
num_refills_filled	String	"0"
refills_remaining	Integer	2
quantity_remaining	Integer	84
number_of_refills_allowed	Integer	2
prescribed_drug_strength	String	"10 mg"
prescribed_ndc	String	"51862009706"
prescribed_dea_schedule	Integer	0
prescribed_quantity	Integer	42
prescribed_unit_text	String	"EA"
prescribed_label_type	String	"Generic"
prescribed_brand_name	String	"Brand Label"
prescribed_written_name	String	"Brand Label 10 mg Tablet"
prescribed_generic_name	String	"Generic 10 mg tablet"
dispensed_drug_strength	String	"10 mg"
dispensed_ndc	String	"51862009706"
dispensed_quantity	Integer	42
dispensed_dea_schedule	Integer	0
dispensed_days_supply	Integer	28
diagnosis_codes	Object	Diagnosis Codes

Diagnosis Codes

Each prescription in the Truepill ecosystem is usually associated with at least one ICD code (International Statistical Classification of Diseases and Related Health Problems).

This can also be overridden with your own custom ICD10 or ICD9 codes by passing in an object for the attribute diagnosis_codes. The object is composed as follows:

Field Name	Type	Default Value
icd10	Array	["Z30.09"]
icd9	Array	["V85.30"]

Simulated Notify Rx Webhook Events

Notify Rx Webhook Event of Prescription with Default Attributes

{
    "timestamp": 1590784899,
    "callback_type": "NOTIFY_RX",
    "details": {
        "medication_name": "Brand Label 10mg Tablet",
        "prescriber": "Dr. P. Scribe",
        "prescription_token": "7cb7d8ea418d",
        "patient_token": "838a906bcc6e7671",
        "location": "Hayward, CA"
    }
}

Notify Rx Webhook Event of Prescription with Custom Attributes

{
    "timestamp": 1590382349,
    "callback_type": "NOTIFY_RX",
    "details": {
        "medication_name": "Generic Label 50mg Tablet",
        "prescriber": "Dr. Strange",
        "prescription_token": "e9549cca9639",
        "patient_token": "838a906bcc6e7671",
        "location": "Hayward, CA"
    }
}

When the request object containing the simulation object is submitted, a NOTIFY_RX webhook event containing a generated prescription_token will be created shortly afterwards for each prescription. These prescriptions can be used for subsequent API calls via the prescription_token.

Retrieving Patient's Prescriptions

Patient Prescription API Response Containing the Generated Prescriptions

{
  "patient_token": "838a906bcc6e7671",
  "prescriptions": [
    {
      "prescription_token": "7cb7d8ea418d",
      "medication_name": "Brand Label 10mg Tablet",
      "medication_sig": "Take one daily.",
      "prescriber": "Dr. P. Scribe",
      "date_written": "2020-05-18T19:59:56.000Z",
      "refills_remaining": 2,
      "current_rx_status_text": "On Hold",
      "fillable": true,
      "date_filled_utc": "2020-07-30T20:08:55.000Z"
    },
    {
      "prescription_token": "e9549cca9639",
      "medication_name": "Generic Label 50mg Tablet",
      "medication_sig": "Take one every two hours",
      "prescriber": "Dr. Strange",
      "date_written": "2020-05-18T19:59:56.000Z",
      "refills_remaining": 4,
      "current_rx_status_text": "On Hold",
      "fillable": true,
      "date_filled_utc": "2020-07-30T20:08:55.000Z"
    }
  ]
}

A patient’s prescriptions can also be collected by hitting the following API Endpoint:

api.falsepill.com/v1/patient/{patient_token}/prescriptions

A quick check on this endpoint using the existing_patient token will retrieve both prescriptions that were created -- the default values prescription and the custom made prescription.

Get Prescription

Get Prescription Request

curl --request GET \
 --url https://api.falsepill.com/v1/prescription/90aae1c9de75 \
 --header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w'

fetch('https://api.falsepill.com/v1/prescription/90aae1c9de75', {
  method: 'GET',
  headers: {
    Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w'
  }
})
  .then(response => response.json())
  .then(response => console.log(response))

Successful Response

{
  "prescription": {
    "date_written": "2020-05-18T19:59:56.000Z",
    "days_supply": "28",
    "is_refill": 0,
    "last_filled_date": null,
    "medication_sig": "Take one daily.",
    "number_of_refills_allowed": 2,
    "prescribed_brand_name": "Brand Label",
    "prescribed_drug_strength": "10 mg",
    "prescribed_generic_name": "Generic 10mg tablet",
    "prescribed_ndc": "51862009706",
    "prescribed_quantity": 42,
    "prescribed_written_name": "Brand Label 10mg Tablet",
    "prescriber": "Dr. P. Scribe",
    "prescriber_address": {
      "name": "Carol Danvers",
      "company": null,
      "street1": "12345 Avengers Rd",
      "street2": null,
      "city": "San Francisco",
      "state": "CA",
      "zip": "94402",
      "country": "US",
      "phone": "(800) 888-8888",
      "email": "carol.danvers@avengers.com"
    },
    "prescriber_npi": "1497742761",
    "prescriber_order_number": "11111111",
    "quantity_remaining": 84,
    "refills_remaining": 2,
    "rx_number": "452702000",
    "prescription_token": "7cb7d8ea418d",
    "notes": "prescription notes",
    "icd_codes": {
      "icd10": ["Z30.09"],
      "icd9": ["N94.6"]
    },
    "is_daw": false,
    "dea_schedule": 0,
    "date_filled_utc": "2020-07-30T20:08:55.000Z"
  }
}

GET https://api.falsepill.com/v1/prescription/{prescription_token}

If a simulation is used on the Create Patient request, a prescription_token will be generated on the Notify Rx Webhook event. The details of the prescription can then be retrieved with the Get Prescription API Response.

Coverage Request

Sending a Coverage Request to with Custom Simulated Insurance Information

curl -X POST https://api.falsepill.com/v1/coverage_request \
   --header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
   -d '{
          "patient_token": "838a906bcc6e7671",
          "metadata": "metadata",
          "simulation": {
              "insurance": [
                {
                  "cardholder_id": "123456789",
                  "group_number": "DEF9876543",
                  "bin": "555555",
                  "pcn": "PCN456",
                  "payer_name": "Custom Benefits",
                  "plan_type": "government",
                  "effective_date": "20200120",
                  "termination_date": "20201231"
                }
              ]
          }
        }'

const body = {
  patient_token: '838a906bcc6e7671',
  metadata: 'metadata',
  simulation: {
    insurance: [
      {
        cardholder_id: '123456789',
        group_number: 'DEF9876543',
        bin: '555555',
        pcn: 'PCN456',
        payer_name: 'Custom Benefits',
        plan_type: 'government',
        effective_date: '20200120',
        termination_date: '20201231'
      }
    ]
  }
}

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

Sending a Coverage Request to Simulate Error

curl -X POST https://api.falsepill.com/v1/coverage_request \
   --header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
   -d '{
          "patient_token": "838a906bcc6e7671",
          "metadata": "metadata",
          "simulation": {
              "error": "Patient social security number is not available"
          }
        }'

const body = {
  patient_token: '838a906bcc6e7671',
  metadata: 'metadata',
  simulation: {
    error: 'simulated error'
  }
}

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

Successful Response

{
  "request_id": "skhsyq83rkd3uht9",
  "timestamp": 1593452421,
  "status": "success",
  "details": {
    "coverage_request_token": "skhsyq83rkd3uht9",
    "message": "Your coverage request has been processed successfully."
  }
}

POST https://api.falsepill.com/v1/coverage_request

For making a coverage request, the patient_token will be used here.

An empty simulation object can be passed in to simulate a successful Coverage Request retrieval with default sample insurance values.

These insurance properties can be overridden with custom insurance information and should be specified in objects in an insurance array within the simulation object.

The overridable fields are detailed below:

Field Name	Type	Default Value
cardholder_id	String	"9151014609"
group_number	String	"ABC123456789"
bin	String	"999999"
pcn	String	"ABC1234567"
payer_name	String	"Omni Benefits"
plan_type	String	"commercial"
effective_date	String	"20200120"
termination_date	String	"20201231"

To simulate an rejected copay request (retrieving no insurance information for the patient), pass an error string field within the simulations object.

Simulated Coverage Request Webhook Events

When a Coverage Request with simulations is successfully submitted in the Sandbox environment, you will see any custom insurance information provided appear in the Coverage Request webhook event.

For the error scenario, you will retrieve null for the insurances field

Successful Coverage Request Webhook Event with Custom Insurance

{
  "request_id": "skhsyq83rkd3uht9",
  "timestamp": 1596137150,
  "callback_type": "COVERAGE",
  "status": "success",
  "details": {
    "metadata": "metadata",
    "patient_token": "838a906bcc6e7671",
    "coverage_request_token": "skhsyq83rkd3uht9",
    "insurances": [
      {
        "insurance_token": "9502a8162af55927",
        "cardholder_id": "123456789",
        "group_number": "DEF9876543",
        "bin": "555555",
        "pcn": "PCN456",
        "payer_name": "Custom Benefits",
        "plan_type": "government",
        "effective_date": "2020-01-20T00:00:00.000Z",
        "termination_date": "2020-12-31T00:00:00.000Z"
      }
    ]
  }
}

Error Coverage Request Webhook Event

{
  "request_id": "skhsyq83rkd3uht9",
  "status": "error",
  "message": "Patient insurance is not found",
  "callback_type": "COVERAGE",
  "timestamp": 1567026972,
  "details": {
    "metadata": "cfe146",
    "patient_token": "838a906bcc6e7671",
    "coverage_request_token": "skhsyq83rkd3uht9",
    "insurances": null
  }
}

Insurance

Create Insurance Request

curl -X POST https://api.falsepill.com/v1/insurance \
   --header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
   -d patient_token ='838a906bcc6e7671' \
   -d insurance='{
        "cardholder_id": "ABC12345",
        "rx_group": "006543",
        "rx_bin": "997955",
        "pcn": "TEST",
        "phone_number": "(555) 555-1234"
   }'

const body = {
  patient_token: '838a906bcc6e7671',
  insurance: {
    cardholder_id: 'ABC12345',
    rx_group: '006543',
    rx_bin: '997955',
    pcn: 'TEST',
    phone_number: '(555) 555-1234'
  }
}

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

Successful Response

{
  "request_id": "34e36c77fae25da9f8228e3b68b03bd2",
  "status": "success",
  "timestamp": 1590785394,
  "details": {
    "insurance_token": "1a9e3cdba512d862"
  }
}

POST https://api.falsepill.com/v1/insurance

Create an insurance that this “Patient” will have -- using the same patient_token.

This will be used for making a Copay Request and Fill Request.

Copay Request

Sending a Copay Request to Simulate Successful Copay

curl -X POST https://api.falsepill.com/v1/copay_request \
   --header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
   -d patient_token='838a906bcc6e7671' \
   -d insurance_token='["1a9e3cdba512d862"]' \
   -d prescriptions='["7cb7d8ea418d"]' \
   -d metadata='cfe146' \
   -d simulation=`{}`

const body = {
  patient_token: '838a906bcc6e7671',
  insurance_token: ['1a9e3cdba512d862'],
  prescriptions: ['7cb7d8ea418d'],
  metadata: 'cfe146',
  simulation: {}
}

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

Sending a Copay Request to Simulate Rejected Copays

curl -X POST https://api.falsepill.com/v1/copay_request \
   --header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
   -d patient_token='4526d90a' \
   -d insurance_token='["1a9e3cdba512d862"]' \
   -d prescriptions='["7cb7d8ea418d"]' \
   -d metadata='cfe146' \
   -d simulation=`{
     "error": {
       "reject_codes": ["79", "75"]
      }
    }`

const body = {
  patient_token: '4526d90a',
  insurance_token: ['1a9e3cdba512d862'],
  prescriptions: ['7cb7d8ea418d'],
  metadata: 'cfe146',
  simulation: {
    error: {
      reject_codes: ['79', '75']
    }
  }
}

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

Successful Response

{
  "request_id": "c5e0baede8e5efe91c5811e2e67c17b7",
  "status": "success",
  "timestamp": 1590797192,
  "details": {
    "copay_request_token": "6eab1626c278dbeb",
    "copay_request_prescriptions_tokens": [
      {
        "prescription_token": "7cb7d8ea418d",
        "copay_request_prescription_token": "4a38fb2cdc79222d",
        "status": "pending"
      }
    ]
  }
}

POST https://api.falsepill.com/v1/copay_request

The patient_token, insurance_token, and prescription_token all will be used here to create this request.

When a simulation object is passed in, the status of the Copay Request will be updated and an appropriate webhook event will be generated and sent.

An empty simulation object can be passed in to update the status of the Copay Request to “completed” and generate a successful webhook event.

To simulate copay request rejections, pass in a simulation object containing an error object.

You can pass in specific claim rejection codes as they align to NCPDP Claim Codes to simulate receiving different claim codes on a prescription claim rejection. To do this, pass the field reject_codes within the error object containing an array of your NCPDP codes.

All of these claim codes will be applied to each prescription on the webhook event.

Simulated Copay Request Webhook Events

Successful Copay Request Webhook Event

{
  "request_id": "c5e0baede8e5efe91c5811e2e67c17b7",
  "timestamp": 1590797193,
  "callback_type": "COPAY",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "message": "Here is a list of medications that were checked",
    "patient_token": "838a906bcc6e7671",
    "prescriptions": [
      {
        "prescription_token": "7cb7d8ea418d",
        "status": "completed",
        "copay_request_prescription_token": "4a38fb2cdc79222d",
        "insurance_token": "36a0238257986729",
        "next_fill_date": "2020-05-30T00:06:32.000Z",
        "copay_amount": "13.37",
        "days_supply": "28"
      }
    ]
  }
}

Error Copay Request Webhook Event

{
  "request_id": "c5e0baede8e5efe91c5811e2e67c17b7",
  "timestamp": 1590797193,
  "callback_type": "COPAY",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "message": "Here is a list of medications that were checked",
    "patient_token": "838a906bcc6e7671",
    "prescriptions": [
      {
        "prescription_token": "7cb7d8ea418d",
        "status": "rejected",
        "copay_request_prescription_token": "4a38fb2cdc79222d",
        "insurance_token": "36a0238257986729",
        "claim_reject_codes": ["79", "75"]
      }
    ]
  }
}

Note that on the Error Copay Request Webhook Event, the copay request's webhook event status will be "success" -- check the prescriptions array to view the status of each prescription's claim that was run.

Fill Request

Sending a Fill Request to simulate a completely successful order

curl -X POST https://api.falsepill.com/v1/fill_request \
   -H "Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json" \
   -d '{"patient_token": "838a906bcc6e7671",
      "patient_payment_type": "insurance",
      "insurances": [
        {
            "insurance_token":  "1a9e3cdba512d862"
        }
        ],
      "medications": [
        {
          "prescription_token": "7cb7d8ea418d"
        },
        {
          "prescription_token": "e9549cca9639",
        }
      ],
      "shipping_method": "fedex_ground",
      "signature_confirmation": true,
      "address_to_name": "David Doe",
      "address_to_street1": "123 Some Lane",
      "address_to_street1": "UNIT 301",
      "address_to_city": "Los Angeles",
      "address_to_state": "CA",
      "address_to_zip": "94402",
      "address_to_country": "US",
      "address_to_phone": "(555) 555-5555",
      "address_to_email": "example@gmail.com",
      "metadata": "cfe146",
      "patient_survey": {
        "allergies": null,
        "conditions": "Anxiety",
        "medications": "Ibuprofen, Vitamin B 12"
        },
      "simulation": {}
    }'

const body = {
  patient_token: '838a906bcc6e7671',
  patient_payment_type: 'insurance',
  insurances: [
    {
      insurance_token: '1a9e3cdba512d862'
    }
  ],
  medications: [
    {
      prescription_token: '7cb7d8ea418d'
    },
    {
      prescription_token: 'e9549cca9639'
    }
  ],
  shipping_method: 'fedex_ground',
  signature_confirmation: true,
  address_to_name: 'David Doe',
  address_to_street1: '123 Some Lane',
  address_to_street1: 'UNIT 301',
  address_to_city: 'Los Angeles',
  address_to_state: 'CA',
  address_to_zip: '94402',
  address_to_country: 'US',
  address_to_phone: '(555) 555-5555',
  address_to_email: 'example@gmail.com',
  metadata: 'cfe146',
  patient_survey: {
    allergies: null,
    conditions: 'Anxiety',
    medications: 'Ibuprofen, Vitamin B 12'
  },
  simulation: {}
}

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

Sending a Fill Request that will Reject the Entire Order

curl -X POST https://api.falsepill.com/v1/fill_request \
   -H "Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w" \
   -H "Content-Type: application/json" \
   -d '{"patient_token": "838a906bcc6e7671",
      "patient_payment_type": "insurance",
      "insurances": [
        {
            "insurance_token":  "1a9e3cdba512d862"
        }
        ],
      "medications": [
        {
          "prescription_token": "7cb7d8ea418d"
        },
        {
          "prescription_token": "e9549cca9639",
        }
      ],
      "shipping_method": "fedex_ground",
      "signature_confirmation": true,
      "address_to_name": "David Doe",
      "address_to_street1": "123 Some Lane",
      "address_to_street1": "UNIT 301",
      "address_to_city": "Los Angeles",
      "address_to_state": "CA",
      "address_to_zip": "94402",
      "address_to_country": "US",
      "address_to_phone": "(555) 555-5555",
      "address_to_email": "example@gmail.com",
      "metadata": "cfe146",
      "patient_survey": {
        "allergies": null,
        "conditions": "Anxiety",
        "medications": "Ibuprofen, Vitamin B 12"
        },
      "simulation": {
        "order": {
          "error": "passing in error message"
        }
      }
    }'

const body = {
  patient_token: '838a906bcc6e7671',
  patient_payment_type: 'insurance',
  insurances: [
    {
      insurance_token: '1a9e3cdba512d862'
    }
  ],
  medications: [
    {
      prescription_token: '7cb7d8ea418d'
    },
    {
      prescription_token: 'e9549cca9639'
    }
  ],
  shipping_method: 'fedex_ground',
  signature_confirmation: true,
  address_to_name: 'David Doe',
  address_to_street1: '123 Some Lane',
  address_to_street1: 'UNIT 301',
  address_to_city: 'Los Angeles',
  address_to_state: 'CA',
  address_to_zip: '94402',
  address_to_country: 'US',
  address_to_phone: '(555) 555-5555',
  address_to_email: 'example@gmail.com',
  metadata: 'cfe146',
  patient_survey: {
    allergies: null,
    conditions: 'Anxiety',
    medications: 'Ibuprofen, Vitamin B 12'
  },
  simulation: {
    order: {
      error: 'passing in error message'
    }
  }
}

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

Successful Response

{
  "request_id": "fill_request_991e90fa6b367cf72032",
  "timestamp": 1590800011,
  "status": "success",
  "details": {
    "message": "Your fill request has been processed successfully.",
    "metadata": "cfe146"
  }
}

This is the main endpoint used to create orders in the Truepill system. In this API call, patient_token, insurance_token and prescription_token can be passed in.

When a simulation object is passed in, the status of the Fill Request will be updated and the appropriate webhook event will be generated and sent.

An empty simulation object can be passed in to update the status of the Fill Request to complete, generating an order success webhook event along with three shipping webhook events containing information on the status of the delivery.

A simulation object with an “error” field containing a string can be passed in to update the status of the Fill Request to “rejected” and will only generate an error webhook event.

Simulated Fill Request Webhook Events

Successful Fill Request Webhook Event

{
  "request_id": "fill_request_991e90fa6b367cf72032",
  "timestamp": 1590800072,
  "callback_type": "ORDER",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "message": "Your fill request was processed and is pending shipment.",
    "date_filled": "N/A",
    "medications": [
      {
        "medication_name": "Brand Label 10mg Tablet",
        "dispensed_medication_name": "Brand Label 10mg Tablet",
        "requested_medication_name": "prescription_token:7cb7d8ea418d",
        "original_requested_prescription_token": "c8226924vf1a",
        "days_supply": 28,
        "quantity": 42,
        "fill_number": "0",
        "rx_number": "452793000",
        "total_refills_allowed": 2,
        "prescription_token": "7cb7d8ea418d",
        "medication_token": "e2b176d61505",
        "remaining_refills": {
          "total_remaining_refills": 2,
          "total_quantity_remaining": 84
        }
      },
      {
        "medication_name": "Generic Label 50mg Tablet",
        "dispensed_medication_name": "Generic Label 50mg Tablet",
        "requested_medication_name": "prescription_token:e9549cca9639",
        "original_requested_prescription_token": "c9876924vf2c",
        "days_supply": 1,
        "quantity": 12,
        "fill_number": "2",
        "rx_number": "452793000",
        "total_refills_allowed": 2,
        "prescription_token": "e9549cca9639",
        "medication_token": "3fbsz9m613o9",
        "remaining_refills": {
          "total_remaining_refills": 2,
          "total_quantity_remaining": 48
        }
      }
    ],
    "order_token": "3d2c77",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000",
    "patient_token": "838a906bcc6e7671"
  }
}

Error Fill Request Webhook Event

{
  "request_id": "fill_request_991e90fa6b367cf72032",
  "timestamp": 1591763649,
  "callback_type": "ORDER",
  "status": "error",
  "details": {
    "metadata": "cfe146",
    "error_code": "passing in error message",
    "description": "Simulated Error",
    "message": "You requested a simulated error code of passing in error message",
    "order_token": "3d2c77"
  }
}

Shipment Webhook Event -- Arrival to Facility

{
  "request_id": "fill_request_991e90fa6b367cf72032",
  "timestamp": 1590800102,
  "callback_type": "SHIPMENT",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "status": "TRANSIT",
    "message": "Your shipment has arrived at the USPS regional origin facility.",
    "eta": "2020-06-02T00:54:31.838Z",
    "tracking_number": "43904456187100000000000000",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000"
  }
}

Shipment Webhook Event -- In Transit

{
  "request_id": "fill_request_991e90fa6b367cf72032",
  "timestamp": 1590800162,
  "callback_type": "SHIPMENT",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "status": "TRANSIT",
    "message": "In Transit, Arriving On Time",
    "eta": "2020-06-02T00:54:31.838Z",
    "tracking_number": "43904456187100000000000000",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000"
  }
}

Shipment Webhook Event -- Delivered to Patient

{
  "request_id": "fill_request_991e90fa6b367cf72032",
  "timestamp": 1590800222,
  "callback_type": "SHIPMENT",
  "status": "success",
  "details": {
    "metadata": "cfe146",
    "status": "DELIVERED",
    "message": "Your shipment has been delivered at the destination mailbox.",
    "eta": "2020-06-02T00:54:31.838Z",
    "tracking_number": "43904456187100000000000000",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000"
  }
}

It is important to note here that while the three simulated Shipment Webhook Events are provided -- Arrival to Facility, In Transit, Delivered to Patient -- there can me many more Shipment Webhook Events as the specified carrier sends notifications.

Direct Transfer

Direct Transfer Request

curl -X POST https://api.falsepill.com/v1/direct_transfer \
   --header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
   --data '{
   "patient_token": "838a906bcc6e7671",
   "prescriber":{
      "first_name":"Philip",
      "last_name":"Scribe",
      "npi":"1559977654",
      "address":{
         "name":"Philip Scribe",
         "street1":"1234 Scribe St",
         "city":"San Francisco",
         "state":"CA",
         "zip":"94109",
         "country":"US",
         "phone":"5555556789"
      }
   },
   "transfer_from":{
      "name":"Other Pharmacy, LLC",
      "address":{
         "name":"Other Pharmacy, LLC",
         "street1":"123 Pharmacy Lane",
         "city":"Los Angeles",
         "state":"CA",
         "zip":"97229",
         "country":"US",
         "phone":"(555) 555-5555",
         "email":"pharmacy@example.com"
      },
      "id_number":"134123941",
      "pharmacist":"Philip Scribe",
      "dea":"DEA1234"
   },
   "transfer_to":{
      "name":"Truepill",
      "id_number":"1295182590",
      "pharmacist":"Quynh Do"
   },
   "prescription":{
      "medication_name":"COLD HEAD CONGESTION",
      "quantity_written":"50",
      "quantity_dispensed":"50",
      "medication_sig":"50",
      "written_date":"20200527",
      "refills_left":11,
      "refills_transferred":11,
      "number":"12345",
      "can_substitute":true,
         "prescribed_ndc":"12345678912",
         "direct_transfer_url":"http://localhost:8888/api/v1/truepill/transfer-fax/5ece0f1872044339ff784ce6"

   },
  "metadata": "5fc6c6",
  "simulation": {}
}'

const body = {
  patient_token: '838a906bcc6e7671',
  prescriber: {
    first_name: 'Philip',
    last_name: 'Scribe',
    npi: '1559977654',
    address: {
      name: 'Philip Scribe',
      street1: '1234 Scribe St',
      city: 'San Francisco',
      state: 'CA',
      zip: '94109',
      country: 'US',
      phone: '5555556789'
    }
  },
  transfer_from: {
    name: 'Other Pharmacy, LLC',
    address: {
      name: 'Other Pharmacy, LLC',
      street1: '123 Pharmacy Lane',
      city: 'Los Angeles',
      state: 'CA',
      zip: '97229',
      country: 'US',
      phone: '(555) 555-5555',
      email: 'pharmacy@example.com'
    },
    id_number: '134123941',
    pharmacist: 'Philip Scribe',
    dea: 'DEA1234'
  },
  transfer_to: {
    name: 'Truepill',
    id_number: '1295182590',
    pharmacist: 'Quynh Do'
  },
  prescription: {
    medication_name: 'COLD HEAD CONGESTION',
    quantity_written: '50',
    quantity_dispensed: '50',
    medication_sig: '50',
    written_date: '20200527',
    refills_left: 11,
    refills_transferred: 11,
    number: '12345',
    can_substitute: true,
    prescribed_ndc: '12345678912',
    direct_transfer_url:
      'http://localhost:8888/api/v1/truepill/transfer-fax/5ece0f1872044339ff784ce6'
  },
  metadata: '5fc6c6',
  simulation: {}
}

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

When a simulation object is passed in, the status of the Direct Transfer is updated to have “successfully completed”, and a successful Direct Transfer Webhook Event will be generated.

The simulation object can be passed in as an empty object on the request.

Direct Transfer Webhook Events

Successful Direct Transfer Webhook Event

{
  "request_id": "c973dab3c2d8b8ea3ca2e30f14c72149",
  "timestamp": 1591035261,
  "callback_type": "DIRECT_TRANSFER",
  "status": "success",
  "details": {
    "message": "Direct Transfer Accepted.",
    "patient_token": "838a906bcc6e7671",
    "direct_transfer_token": "8134a6ef49",
    "prescription_token": "dfb23987c12e"
  }
}

Error Direct Transfer Webhook Event

{
  "request_id": "c973dab3c2d8b8ea3ca2e30f14c72149",
  "timestamp": 1591035261,
  "callback_type": "DIRECT_TRANSFER",
  "status": "error",
  "details": {
    "message": "Direct Transfer Rejected. duplicate",
    "patient_token": "838a906bcc6e7671",
    "direct_transfer_token": "8134a6ef49",
    "prescription_token": "dfb23987c12e"
  }
}

Transfer

Sending a Transfer Request with Custom Rx Information to Simulate Successful Transfer

curl -X POST https://api.falsepill.com/v1/direct_transfer \
   --header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
   --data '{
    "patient_token": "838a906bcc6e7671",
    "pharmacy_name": "Example Pharmacy",
    "pharmacy_phone": "5555551234",
    "prescriber_name": "Dr. Prescriber",
    "prescriber_phone": "5555554567",
    "metadata": "metadata",
    "notes": "test notes",
    "medications": [
        "Sprintec Tablet",
        "Spironolactone 10mg tablet"
    ],
    "simulation": {}
}'

const body = {
  patient_token: '838a906bcc6e7671',
  pharmacy_name: 'Example Pharmacy',
  pharmacy_phone: '5555551234',
  prescriber_name: 'Dr. Prescriber',
  prescriber_phone: '5555554567',
  metadata: 'metadata',
  notes: 'test notes',
  medications: [
    'Sprintec Tablet',
    'Spironolactone 10mg tablet'
  ],
  simulation: {}
}

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

Sending a Transfer Request to Simulate Rejected Transfer

curl -X POST https://api.falsepill.com/v1/direct_transfer \
   --header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
   --data '{
    "patient_token": "838a906bcc6e7671",
    "pharmacy_name": "Example Pharmacy",
    "pharmacy_phone": "5555551234",
    "prescriber_name": "Dr. Prescriber",
    "prescriber_phone": "5555554567",
    "metadata": "metadata",
    "notes": "test notes",
    "medications": [
        "Sprintec Tablet",
        "Spironolactone 10mg tablet"
    ],
    "simulation": {
    "error": {
      "reject_reason": "Test Rejecting Transfer",
      "reject_reason_other": null
    }
  }
}'

const body = {
  patient_token: '838a906bcc6e7671',
  pharmacy_name: 'Example Pharmacy',
  pharmacy_phone: '5555551234',
  prescriber_name: 'Dr. Prescriber',
  prescriber_phone: '5555554567',
  metadata: 'metadata',
  notes: 'test notes',
  medications: [
    'Sprintec Tablet',
    'Spironolactone 10mg tablet'
  ],
  simulation: {
    error: {
      reject_reason: 'Test Rejecting Transfer',
      reject_reason_other: null
    }
  }
}

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

When a simulation object is passed in, the status of the Transfer is updated to have been "successfully completed", and a successful Transfer Webhook Event will be generated and sent.

The simulation object can be passed in as an empty object on the request. Prescriptions with default generic information will be created for each medication that is passed in on the request.

To simulate a Transfer rejection, pass an error object within the simulation object containing reject_reason and error_code, and optionally reject_reason_other. The information provided in these two fields will be propagated back on the Error Transfer Webhook Event.

Transfer Request with Medication-Specific Scenarios

curl -X POST https://api.falsepill.com/v1/direct_transfer \
   --header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
   --data '{
    "patient_token": "838a906bcc6e7671",
    "pharmacy_name": "Example Pharmacy",
    "pharmacy_phone": "5555551234",
    "prescriber_name": "Dr. Prescriber",
    "prescriber_phone": "5555554567",
    "metadata": "metadata",
    "notes": "test notes",
    "medications": [
        "Sprintec Tablet",
        "Spironolactone 10mg tablet",
    "Ibuprofen"
    ],
    "simulation": {
    "medications": ]
    {
      "medication_sig": "Take one every two hours",
      "prescriber": "Dr. Strange",
      "days_supply": "1",
      "num_refills_filled": "2",
      "refills_remaining": 4,
      "quantity_remaining": 48,
      "number_of_refills_allowed": 4,
      "prescribed_drug_strength": "50 mg",
      "prescribed_ndc": "55555555555",
      "prescribed_quantity": 12,
      "prescribed_unit_text": "EA",
      "prescribed_label_type": "Generic",
      "prescribed_brand_name": "Generic Label",
      "prescribed_written_name": "Generic Label 50mg Tablet",
      "prescribed_generic_name": "Generic 50mg tablet",
      "dispensed_drug_strength": "50 mg",
      "dispensed_ndc": "55555555555",
      "dispensed_quantity": 12,
      "dispensed_days_supply": 1
    },
    true,
    {
      error: {
        "error_code": "RX_NONEXISTANT",
        "rejection_reason": "No Prescription exists at pharmacy",
        "rejection_reason_other": "Patient only has expired prescription"
      }
    }
  }
}'

const body = {
  patient_token: '838a906bcc6e7671',
  pharmacy_name: 'Example Pharmacy',
  pharmacy_phone: '5555551234',
  prescriber_name: 'Dr. Prescriber',
  prescriber_phone: '5555554567',
  metadata: 'metadata',
  notes: 'test notes',
  medications: [
    'Sprintec Tablet',
    'Spironolactone 10mg tablet',
    'Ibuprofen'
  ],
  simulation: {
    medications: [
      {
        medication_sig: 'Take one every two hours',
        prescriber: 'Dr. Strange',
        days_supply: '1',
        num_refills_filled: '2',
        refills_remaining: 4,
        quantity_remaining: 48,
        number_of_refills_allowed: 4,
        prescribed_drug_strength: '50 mg',
        prescribed_ndc: '55555555555',
        prescribed_quantity: 12,
        prescribed_unit_text: 'EA',
        prescribed_label_type: 'Generic',
        prescribed_brand_name: 'Generic Label',
        prescribed_written_name: 'Generic Label 50mg Tablet',
        prescribed_generic_name: 'Generic 50mg tablet',
        dispensed_drug_strength: '50 mg',
        dispensed_ndc: '55555555555',
        dispensed_quantity: 12,
        dispensed_days_supply: 1
      },
      true,
      {
        error: {
          error_code: "RX_NONEXISTANT",
          rejection_reason: 'No Prescription exists at pharmacy',
          rejection_reason_other: 'Patient only has expired prescription'
        }
      }
    ]
  }
}

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

Medication-Specific Simulations

The Transfer simulation also allows for simulating events at the medication level. This is done by passing in a medications array within the simulations object.

The important thing to note here, however, is that when a medications array is passed in the simulations object, the array length must equal the length of the medications array in the Transfer request. This is important, because the information provided within the medications array in the simulation object will correlate the medication provided in the Transfer request at that specific index.

When a simulation object is passed in as an empty object, generic prescriptions are created for each medication that is passed in othe request. This can be overridden with custom prescription information.

You can also choose to use override only some prescriptions in a transfer, and use the default prescription information on others. To use the default prescription information, simply pass true in the medications array.

The following properties can be overridden with custom prescription information:

Field Name	Type	Default Value
medication_sig	String	"Take one Daily"
prescriber	String	"Dr. P. Scribe"
prescriber_npi	String	"1497742761"
days_supply	String	"28"
num_refills_filled	String	"0"
refills_remaining	Integer	2
quantity_remaining	Integer	84
number_of_refills_allowed	Integer	2
prescribed_drug_strength	String	"10 mg"
prescribed_ndc	String	"51862009706"
prescribed_dea_schedule	Integer	0
prescribed_quantity	Integer	42
prescribed_unit_text	String	"EA"
prescribed_label_type	String	"Generic"
prescribed_brand_name	String	"Brand Label"
prescribed_written_name	String	"Brand Label 10 mg Tablet"
prescribed_generic_name	String	"Generic 10 mg tablet"
dispensed_drug_strength	String	"10 mg"
dispensed_ndc	String	"51862009706"
dispensed_quantity	Integer	42
dispensed_dea_schedule	Integer	0
dispensed_days_supply	Integer	28
date_written	Date	Generated real-time
diagnosis_codes	Object	Diagnosis Codes

You can also simulate a medication-level rejection within a Transfer. The overall Transfer will still be approved but, for example, one out of three medications can be rejected during the transfer process.

To do this, pass an object containing an error object much like the error object at the root level of the simulation to simulate rejecting an entire Transfer.

This error object also accepts the fields reject_reason and reject_reason_other. This information is propagated back in the Transfer Webhook Event within the medications array.

Transfer Diagnosis Codes

Each prescription in the Truepill ecosystem is usually associated with at least one ICD code (International Statistical Classification of Diseases and Related Health Problems).

This can also be overridden with your own custom ICD10 or ICD9 codes by passing in an object for the attribute diagnosis_codes. The object is composed as follows:

Field Name	Type	Default Value
icd10	Array	["Z30.09"]
icd9	Array	["V85.30"]

Transfer Webhook Events

Successful Transfer Webhook Event

{
  "request_id": "ae030bc915541154932aad14e622c292",
  "timestamp": 1598311289,
  "callback_type": "TRANSFER",
  "status": "success",
  "details": {
    "metadata": "metadata",
    "message": "Here is a list of medications that were successfully transferred",
    "patient_token": "838a906bcc6e7671",
    "medications": [
      {
        "transfer_medication_id": "39e6856f55e1e9df",
        "transfer_medication_token": "39e6856f55e1e9df",
        "requested_medication_name": "Sprintec Tablet",
        "last_filled_date": "No Data",
        "prescriber": "Dr. Prescriber",
        "medication_sig": "Take one daily.",
        "prescription_token": "de6f66b44b67",
        "medication_name": "Sprintec Tablet",
        "num_refills_remaining": 2,
        "quantity": 42,
        "days_supply": 28
      },
      {
        "transfer_medication_id": "debcadfe3b2dd482",
        "transfer_medication_token": "debcadfe3b2dd482",
        "requested_medication_name": "Spironolactone 10mg tablet",
        "last_filled_date": "No Data",
        "prescriber": "Dr. Prescriber",
        "medication_sig": "Take one daily.",
        "prescription_token": "a1607c465f83",
        "medication_name": "Spironolactone 10mg tablet",
        "num_refills_remaining": 2,
        "quantity": 42,
        "days_supply": 28
      }
    ]
  }
}

Error Transfer Webhook Event

{
  "request_id": "ae030bc915541154932aad14e622c292",
  "timestamp": 1598311289,
  "callback_type": "TRANSFER",
  "status": "error",
  "details": {
    "metadata": "metadata",
    "message": "Test Rejecting Transfer",
    "patient_token": "838a906bcc6e7671"
  }
}

Successful Transfer Webhook Event with Medication-Level Information

{
  "request_id": "ae030bc915541154932aad14e622c292",
  "timestamp": 1598311289,
  "callback_type": "TRANSFER",
  "status": "success",
  "details": {
    "metadata": "metadata",
    "message": "Here is a list of medications that were successfully transferred",
    "patient_token": "838a906bcc6e7671",
    "medications": [
      {
        "transfer_medication_id": "39e6856f55e1e9df",
        "transfer_medication_token": "39e6856f55e1e9df",
        "requested_medication_name": "Sprintec Tablet",
        "last_filled_date": "No Data",
        "prescriber": "Dr. Strange",
        "medication_sig": "Take one every two hours",
        "prescription_token": "de6f66b44b67",
        "medication_name": "Generic Label 50mg Tablet",
        "num_refills_remaining": 4,
        "quantity": 48,
        "days_supply": 1
      },
      {
        "transfer_medication_id": "debcadfe3b2dd482",
        "transfer_medication_token": "debcadfe3b2dd482",
        "requested_medication_name": "Spironolactone 10mg tablet",
        "last_filled_date": "No Data",
        "prescriber": "Dr. Prescriber",
        "medication_sig": "Take one daily.",
        "prescription_token": "a1607c465f83",
        "medication_name": "Spironolactone 10mg tablet",
        "num_refills_remaining": 2,
        "quantity": 42,
        "days_supply": 28
      },
      {
        "transfer_medication_id": "debcadfe3b2dd482",
        "transfer_medication_token": "debcadfe3b2dd482",
        "requested_medication_name": "Spironolactone 10mg tablet",
        "rejection_message": "Patient only has expired prescription"
      }
    ]
  }
}

Note that in the last Transfer Webhook Event example containing medication-level information, the medications array returns:
1. A medication with custom Rx information, supplied in the simulation object on the request
2. A medication with the default Rx information generated
3. A medication simulated to be rejected