NAV Navbar
shell javascript

General

The Truepill API documentation provides a list of all the resources and endpoints that are currently supported. The API is exposed as a collection of RESTful HTTP endpoints that return JSON data.

Authentication

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

To use the API an Authorization HTTP Header is required for all endpoints.

Authorization: ApiKey <API KEY>

HTTP Status Codes and Responses

The API attempts to return appropriate HTTP status codes for every request.

Code Text Description
200 OK Success
401 Unauthorized Authentication credentials were missing or incorrect, i.e. api key is not valid

Fill Request

Create Fill

curl -X POST https://api.truepill.com/v1/fill_request \
   -H "Authorization: ApiKey Your_API_Key_Here" \
   -H "Content-Type: application/json" \
   -d '{"patient_first_name": "Guy", 
      "patient_last_name": "Jones",
      "patient_dob": "19840123",
      "patient_gender": "male",
      "patient_payment_type": "insurance",
      "cardholder_id": "953M81593",
      "rx_bin": "003858",
      "rx_group": "WLHA",
      "medication_name": [
        {
          "medication_name": "Doxycycline Hyclate 100mg Tab",
          "quantity_dispensed": 30,
          "days_supply": 30,
          "is_refill": false,
          "medication_sig": "Take 1 tablet by mouth at the same time every day.",
          "prescribing_doctor" : "Dr. Doctor"
        },
        {
          "medication_name": "Lipitor",
          "quantity_dispensed": 5,
          "days_supply": 30,
          "is_refill": true,
          "medication_sig": "Take 1 tablet by mouth at the same time every day.",
          "prescribing_doctor": "Dr. Doctor"
        }
      ],
      "address_to_name": "Guy Jones",
      "address_to_company": "My Company",
      "address_to_street1": "445 Farrel Ct",
      "address_to_street2": "Apt 456",
      "address_to_city": "San Francisco",
      "address_to_state": "CA",
      "address_to_zip": "94107",
      "address_to_country": "US",
      "address_to_phone": "(347) 610-8896",
      "address_to_email": "sarah@doe.com",
      "shipping_method": "usps_priority",
      "signature_confirmation": false,
      "metadata": "your_internal_identifier",
      "notes": "Here are some special instructions on how to package this order",
      "patient_survey": {
        "medications":[{
          "name": "Tafluprost",
          "strength": 0.015,
          "dosage": "mg/ml",
          "frequency": "Daily"
        }],
        "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_first_name: 'Guy',
  patient_last_name: 'Jones',
  patient_dob: '19840123',
  patient_gender: 'male',
  patient_payment_type: 'insurance',
  cardholder_id: '953M81593',
  rx_bin: '003858',
  rx_group: 'WLHA',
  medication_name: [
    {
      medication_name: 'Doxycycline Hyclate 100mg Tab',
      quantity_dispensed: '30',
      days_supply: '30',
      is_refill: false,
      medication_sig: 'Take 1 tablet by mouth at the same time every day.',
      prescribing_doctor : 'Dr. Doctor'
    },
    {
      medication_name: 'Lipitor',
      quantity_dispensed: '5',
      days_supply: '30',
      is_refill: true,
      medication_sig: 'Take 1 tablet by mouth at the same time every day.',
      prescribing_doctor: 'Dr. Doctor'
    }
  ],
  address_to_name: 'Guy Jones',
  address_to_company: 'My Company',
  address_to_street1: '445 Farrel Ct',
  address_to_street2: 'Apt 456',
  address_to_city: 'San Francisco',
  address_to_state: 'CA',
  address_to_zip: '94107',
  address_to_country: 'US',
  address_to_phone: '(347) 610-8896',
  address_to_email: 'sarah@doe.com',
  shipping_method: 'usps_priority',
  signature_confirmation: false,
  metadata: 'your_internal_identifier',
  notes: 'Here are some special instructions on how to package this order',
  patient_survey: {
    conditions:'Glaucoma', 
    smoking_frequency:'N/A', 
    drinking_frequency:'One drink nightly',
    asthma_breathing:false,
    heart_disease:false,
    arthritis:false,
    lung_disorder:false,
    bleeding_clotting_disorder:true,
    neurological_chronic_headaches:false,
    blood_transfusion:false,
    psychiatric_disorder:false,
    bowel_stomach:false,
    pulmonary_embolism:false,
    cancer:false,
    stroke:false,
    cholesterol_disorder:false,
    seizure_epilepsy:false,
    diabetes:false,
    thyroid_disorder:false,
    eye_disorder:true,
    urinary_kidney_disorder:true,
    events:[{year:'2019',
            type:'hospitalization',
            reason:'food poisoning'
            },
            {year:'2018',
            type:'surgery',
            reason:'glaucoma treatment'
            }
    ],
    medications:[{
      name:'Tafluprost',
      strength:0.015,
      dosage:'mg/ml',
      frequency:'Daily'
    }]
  }
}

fetch('https://api.truepill.com/v1/fill_request', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey Your_API_Key_Here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
.then(response => {
  if (!response.ok) return false
  return response.json()
})
.then(data => {
  console.log(data)
})

This endpoint generates a Fill Request to fill or refill a prescription. It can also be used to fulfill orders for non-prescription products by supplying an empty string to the medication_name field. This endpoint requests for the medication corresponding to a prescription or a non-prescription product to be shipped to your patient.

HTTP Request

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

Body Fields

Field Name Type Description and Example
patient_first_name String Sarah (Required)
patient_last_name String Doe (Required)
patient_gender String male or female (Required)
patient_payment_type String cash or insurance (Optional): required for insurance paying customer
patient_dob String 19840123 (Required): yyyymmdd format
cardholder_id String XMP223243 (Optional): Member ID number on insurance card
rx_group String 23232 (Optional): RX group on insurance card
rx_bin String(6-8) 003858 (Optional): RX Bin on card, always 6-8 digits
pcn String AXA (Optional): Not present on all insurance cards
insurance_card_image_url String http://imageurl.jpg (Optional): Used to manually troubleshoot any claims issues
medication_name Array[Medication] empty if only requesting OTC products
otc_products Array [{ "item": "Lotion", "quantity": 2 }, { "item": "Vitamins", "quantity": 1 }] (Optional): Request must include either RX or OTC
shipping_method String usps_priority (Optional): Select: usps_priority, usps_first, usps_priority_express, fedex_ground, fedex_standard_overnight, fedex_priority_overnight, Defaults to usps_first
signature_confirmation Boolean true (Optional)
address_from_name String Umar Afridi (Optional): Should use default value
address_from_company String Postmeds Inc. (Optional): Should use default value
address_from_street1 String 1700 S Amphlett Blvd. (Optional): Should use default value
address_from_street2 String Suite 221 (Optional): Should use default value
address_from_city String San Mateo (Optional): Should use default value
address_from_state String CA (Optional): Should use default value
address_from_zip String 94402 (Optional): Should use default value
address_from_country String US (Optional): Use US for all requests, should use default value
address_from_phone String (650) 353 5495 (supports all formats) (Optional): Should use default value
address_from_email String support@postmeds.com (Optional): Should use default value
address_to_name String Sarah Doe (Required)
address_to_company String ABC Inc. (Optional)
address_to_street1 String 449 Farrel Ct (Required)
address_to_street2 String Apt 456 (Required)
address_to_city String San Francisco (Required)
address_to_state String CA (Required)
address_to_zip String 94107 (Required)
address_to_country String US (Required): Use US for all requests
address_to_phone String (347) 676-9989 (Required)
address_to_email String sarah@example.com (Required)
notes String Notes about patient for review (Optional)
metadata String Can be anything but most useful if PO number, eg R0001 (Optional): But recommended
check_in Boolean false (Optional): Set to true to request a consultation with a Truepill Pharmacist prior to completing the Fill Request
patient_survey JSON Required for any Fill Request with a prescription medication if the patient hasn't previously completed a survey. See the section below for more details.

Medication

If you wish to request multiple medications in a single fill, set the medication_name field to an array of JSON objects containing the fields listed below.

Field Name Type Description and Example
medication_name String Doxycycline 100mg tablet (Required)
quantity_dispensed Number (Integer) 30 (Required): Required if RX, number of pills requested
days_supply Number (Integer) 30 (Required): Required if RX, days supply requested
is_refill Boolean false (Optional): true or false
refill_number Number (Integer) 2 (Optional): Required if RX
medication_sig String Take up to 4 tablets per 24 hours, do not exceed this amount (Required): Required if RX
prescribing_doctor String Dr. Smart (Required): Required if RX

Patient Check In

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

Survey Fields

The patient_survey field is required for any Fill Request with a prescription medication if the patient hasn't previously completed a survey. 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 recieve a callback 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.

No Information to Report Patient Survey

{
  "patient_survey": {
    "conditions": null,
    "medications": null,
    "allergies": null
  }
}

Information to Report Patient Survey

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

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
type String surgery (Required): The type of event, either 'surgery' or 'hospitalization'
year Integer or Null 2018 (Required): The year of incidence
reason String or Null glaucoma treatment (Required): The reason for the event

Medications 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
name String Tafluprost (Required): The name of the medication
strength Number 0.05 (Optional): The strength of the medication
dosage String mg/ml (Optional): The unit of the strength
frequency String Daily (Optional): The frequency of medication use

Get Fill

curl --request GET \
  --url https://api.truepill.com/v1/fill_request/<request_id> \
  --header 'Authorization: ApiKey <API KEY>'

curl --request GET \
  --url https://api.truepill.com/v1/fill_request/fill_request_cb619ca2e133d37daefc \
  --header 'Authorization: ApiKey Your_API_Key_Here'
fetch('https://api.truepill.com/v1/fill_request/fill_request_cb619ca2e133d37daefc', {
    method: 'GET',
    headers: {
      'Authorization': 'ApiKey Your_API_Key_Here'
    }
  })
  .then(response => {
    if (!response.ok) return false
    return response.json()
  })
  .then(data => {
    console.log(data)
  })

Success Response

{
  "patient_first_name" : "Alex",
  "patient_last_name" : "Smith",
  "patient_dob" : "19891123",
  "patient_gender" : "Male",
  "patient_payment_type" : "cash",
  "medication_name" : "Lipitor",
  "otc_products" : [
    {
      "item" : "Skittles",
      "quantity" : 1
    }
  ],
  "quantity_dispensed" : 30,
  "days_supply" : 30,
  "prescribing_doctor" : "Dr. Doctor",
  "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" : "Test Company",
  "address_from_street1" : "1700 S AMPHLETT 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" : "Alex Bob",
  "address_to_street1" : "1700 S Amphlett Blvd",
  "address_to_street2" : "#221",
  "address_to_city" : "San Mateo",
  "address_to_state" : "TN",
  "address_to_zip" : "94402",
  "address_to_country" : "United States",
  "address_to_phone" : "(650) 353-5495",
  "address_to_email" : "pharmacy@truepill.com",
  "patient_known_allergies" : "bees",
  "patient_other_medications" : "none",
  "notes" : "",
  "metadata" : "cfe146"
}

Retrieve the Fill Request for which the supplied parameter matches the ‘request_id’ field of an existing Fill Request.

HTTP Request

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

Update Fill

curl -X POST https://api.truepill.com/v1/update_request \
   -d api_key=<YOUR API KEY> \
   -d request_id=<FILL_REQUEST_API_TOKEN> \
   -d address_from_company="Postmeds Inc." \
   -d address_to_name="Guy Jones" \
   -d address_to_company="" \
   -d address_to_street1="445 Farrel Ct" \
   -d address_to_street2="Apt 456" \
   -d address_to_city="San Francisco" \
   -d address_to_state="CA" \
   -d address_to_zip="94107" \
   -d address_to_country="US" \
   -d address_to_phone="(347) 610-8896" \
   -d address_to_email="sarah@doe.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_API_TOKEN>',
  address_from_company: 'Postmeds Inc.',
  address_to_name: 'Guy Jones',
  address_to_company: 'My Company',
  address_to_street1: '445 Farrel Ct',
  address_to_street2: 'Apt 456',
  address_to_city: 'San Francisco',
  address_to_state: 'CA',
  address_to_zip: '94107',
  address_to_country: 'US',
  address_to_phone: '(347) 610-8896',
  address_to_email: 'sarah@doe.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 Your_API_Key_Here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
.then(response => {
  if (!response.ok) return false
  return response.json()
})
.then(data => {
  console.log(data)
})


Success 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. When using this endpoint, all the Fill Request fields must be provided with their appropriate values even if they are not to be updated.

Request Fields

Field Name Type Description and Example
request_id String fill_request_5c4b21b9aecaea155d67 (Required)
address_from_company String Postmeds Inc. (Optional): Should use default value "Postmeds Inc."
address_to_name String Sarah Doe (Required)
address_to_company String ABC Inc. (Optional)
address_to_street1 String 449 Farrel Ct (Required)
address_to_street2 String Apt 456 (Required)
address_to_city String San Francisco (Required)
address_to_state String CA (Required)
address_to_zip String 94107 (Required)
address_to_country String US (Required): Use US for all requests
address_to_phone String (347) 676-9989 (Required)
address_to_email String sarah@example.com (Required)
shipping_method String usps_priority (Optional): Select: usps_priority, usps_first, usps_priority_express, fedex_ground, fedex_standard_overnight, fedex_priority_overnight, Defaults to usps_first
signature_confirmation Boolean true (Optional)
notes String Here are some special instructions on how to package this order (Optional)

Cancel Fill

curl -X POST https://api.truepill.com/v1/cancel_request \
   -d api_key=<YOUR API KEY> \
   -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 Your_API_Key_Here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
.then(response => {
  if (!response.ok) return false
  return response.json()
})
.then(data => {
  console.log(data)
})

Success 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."
}

This endpoint cancels a Fill Request whose “request_id” field matches the respective user provided text parameter. An error is returned if the Fill Request has already been completed.

HTTP Request

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

Request Fields

Field Name Type Description and Example
request_id String transfer_request_c91f2af0a847271bdc0b (Required)

Transfer Prescription

Create Transfer

curl -X POST https://api.truepill.com/v1/transfer_request \
   --header 'Authorization: ApiKey <API KEY>' \
   -d patient_first_name="Guy" \
   -d patient_last_name="Jones" \
   -d patient_dob="19840123" \
   -d patient_gender="male" \
   -d current_pharmacy_name="CBS Pharmacy" \
   -d current_pharmacy_phone="3018897765" 

const body = {
  "patient_first_name": "Test",
  "patient_last_name": "Patient",
  "patient_dob": "20130422",
  "patient_gender": "female",
  "patient_email": "test@test.com",
  "patient_phone": "5124056789",
  "current_pharmacy_name": "Walmart pharmacy ",
  "current_pharmacy_phone": "(949) 837-0504",
  "medication_name": ["Thing1", "Thing 3 400MG"],
  "notes": "This is a sample note."
}

fetch('https://api.truepill.com/v1/transfer_request', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey Your_API_Key_Here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
  })
  .then(response => {
    if (!response.ok) return false
    return response.json()
  })
  .then(data => {
    console.log(data)
  })

Success Response

{
  "request_id": "transfer_request_68e47e32ba93db638259",
  "timestamp": 1564608647,
  "status": "success",
  "details": {
    "message": "Your transfer request has been received.",
    "transfer_id": "d36889c10dcf",
    "transfer_medications": [
      {
        "transfer_medication_id": "1bbda354e8c7",
        "medication_name": "Thiing1"
      },
      {
        "transfer_medication_id": "ea52a1392697",
        "medication_name": "Thing 3 400MG"
      }
    ],
    "patient_id": "0fb778"
  }
}

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.

HTTP Request

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

Request Fields

Field Name Type Description and Example
patient_first_name String Sarah (Required)
patient_last_name String Doe (Required)
patient_gender String female (Required): male or female
patient_dob String 19840123 (Required): yyyymmdd format
current_pharmacy_name String CBS Pharmacy (Required)
current_pharmacy_phone String 3018987787 (Required)
prescriber_name String Dr. Susan Yen (Optional): Must provide either pharmacy or prescriber info
prescriber_phone String 5559998867 (Optional): Must provide either pharmacy or prescriber info
medication_name String or Array Sprintec Tablet or ["Sprintec Tablet", "Spironolactone 10mg tablet"] (Optional): Must provide either pharmacy or prescriber info, if not specified, will transfer all possible prescriptions

Show Transfers

curl -X GET https://api.truepill.com/v1/transfer_request \
   --header 'Authorization: ApiKey <API KEY>'
fetch('https://api.truepill.com/v1/transfer_request', {
  method: 'GET',
  headers: {
    'Authorization': 'ApiKey tp_live_key_576631510d700f77cc8e',
    'Content-Type': 'application/json'
  })
  .then(response => {
    if (!response.ok) return false
    return response.json()
  })
  .then(data => {
    console.log(data)
  })

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

The following endpoint shows any transfer request in the system.

HTTP Request

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

Query Params

Field Name Type Description and Example
page Integer 5 (Optional)

Get Transfer

curl -X GET https://api.truepill.com/v1/transfer_request/98asdf0a9sd \
   --header 'Authorization: ApiKey <API KEY>'
fetch('https://api.truepill.com/v1/transfer_request/98asdf0a9sd', {
  method: 'GET',
  headers: {
    'Authorization': 'ApiKey tp_live_key_576631510d700f77cc8e',
    'Content-Type': 'application/json'
  })
  .then(response => {
    if (!response.ok) return false
    return response.json()
  })
  .then(data => {
    console.log(data)
  })

Success 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_phone": "(704) 982-8948",
    "prescriber_name": "",
    "prescriber_phone": "",
    "notes": "Medication: ",
    "metadata": "a81f78989asdfasdfsada",
    "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": []
  }
]

Direct Transfer Prescription

Create Direct Transfer

curl -X POST https://api.truepill.com/v1/direct_transfer \
   --header 'Authorization: ApiKey <API KEY>' \
   --data '{\n  "prescriber": {\n   "first_name": "Bobby",\n    "last_name": "Tables",\n    "npi": "123123123",\n   "address": {\n      "name": "Pharma One",\n     "street1": "123 Some Lane",\n     "city": "San Mateo",\n      "state": "CA",\n      "zip": "94538"\n    }\n },\n  "patient": {\n    "first_name": "Marky1",\n   "last_name": "Mark",\n    "dob": "19750715",\n    "address": {\n      "name": "Pharma One",\n     "street1": "123 Some Lane",\n     "city": "San Mateo",\n      "state": "CA",\n      "zip": "94538"\n    }\n },\n  "transfer_from": {\n    "name": "Pharma One",\n   "address": {\n      "name": "Pharma One",\n     "street1": "123 Some Lane",\n     "city": "San Mateo",\n      "state": "CA",\n      "zip": "94538"\n    },\n    "id_number": 490382308,\n   "pharmacist": "Dill Droga"\n  },\n  "transfer_to": {\n    "name": "Truepill",\n   "id_number": 490382377,\n   "pharmacist": "Jim Bob"\n },\n  "prescription": {\n   "medication_name": "Finasteride",\n    "quantity_written": "60",\n   "quantity_dispensed": "60",\n   "medication_sig": "Apply Daily.",\n   "written_date": "20190101",\n   "last_fill_date": "20190201",\n   "first_fill_date": "20190115",\n    "refills_left": 5,\n    "refills_transferred": 5,\n   "number": "4567",\n   "can_substitute": true,\n   "direct_transfer_url": "https://user:securelogin@www.assets.com/rx/saijhofiasjfoasoi2f.png"\n }\n}'

const body = {
  "prescriber": {
    "first_name": "Bobby",
    "last_name": "Tables",
    "npi": "123123123",
    "address": {
      "name": "Pharma One",
      "street1": "123 Some Lane",
      "city": "San Mateo",
      "state": "CA",
      "zip": "94538"
    }
  },
  "patient": {
    "first_name": "Marky",
    "last_name": "Mark",
    "dob": "19750715",
    "address": {
      "name": "Pharma One",
      "street1": "123 Some Lane",
      "city": "San Mateo",
      "state": "CA",
      "zip": "94538"
    }
  },
  "transfer_from": {
    "name": "Pharma One",
    "address": {
      "name": "Pharma One",
      "street1": "123 Some Lane",
      "city": "San Mateo",
      "state": "CA",
      "zip": "94538"
    },
    "id_number": 490382308,
    "pharmacist": "Dill Droga"
  },
  "transfer_to": {
    "name": "Truepill",
    "id_number": 490382377,
    "pharmacist": "Jim Bob"
  },
  "prescription": {
    "medication_name": "Finasteride",
    "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",
    "ccan_substitute": true,
    "direct_transfer_url": "https://user:securelogin@www.assets.com/rx/saijhofiasjfoasoi2f.png"
  }
}

fetch('https://api.truepill.com/v1/direct_transfer', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey Your_API_Key_Here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
  })
  .then(response => {
    if (!response.ok) return false
    return response.json()
  })
  .then(data => {
    console.log(data)
  })

Success Response

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

The direct transfer endpoint is a streamlined way to transfer prescriptions from your pharmacy to Truepill without faxes or phone calls.

HTTP Request

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

Request Fields

Field Name Type Description and Example
patient Patient Patient Object
prescriber Prescriber Prescriber Object
transfer_from TransferFrom Transfer From Object
transfer_to TransferTo Transfer To Object
prescription Prescription Prescription Object

Transfer From

Field Name Type Description and Example
name String Pharma One (Required)
address Address Address Object
id_number String 2142134123 (Required)
pharmacist String Dill Droga (Required)
dea String AB8211241234 (Optional for Controlled)

Transfer To

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

Field Name Type Description and Example
name String Truepill (Required)
id_number String 2142134123
pharmacist String Dill Droga (Required)
dea String AB8211241234 (Required for Controlled)

Prescription

Field Name Type Description and Example
medication_name String Finasteride (Required)
quantity_written String 60 (Required)
quantity_dispensed String 60 (Required)
medication_sig String Take one daily. (Required)
written_date String 19840123 (Required): yyyymmdd format
last_fill_date String 19840123 yyyymmdd format
first_fill_date String 19840123 yyyymmdd format
refills_left Integer 5
refills_transferred Integer 5
number String 12321341
direct_transfer_url String https://user:securelogin@www.assets.com/rx/saijhofiasjfoasoi2f.png
can_substitute Boolean true

Insurance

Create Insurance

curl -X POST https://api.truepill.com/v1/insurance \
   --header 'Authorization: ApiKey <API KEY>' \
   -d patient_token ='d9b8a7' \
   -d insurance='{
        "cardholder_id": "A9321328",
        "rx_group": "006726",
        "rx_bin": "997928",
        "pcn": "TXMH",
        "phone_number": "(955) 372-4143"
   }'
const body = {
  patient_token 'd9b8a7',
  insurance: {
    cardholder_id: 'A9321328', 
    rx_group: '006726', 
    rx_bin: '997928',
    pcn: 'TXMH',
    phone_number: '(955) 372-4143'
  }
}

fetch('https://api.truepill.com/v1/insurance', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey Your_API_Key_Here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
.then(response => {
  if (!response.ok) return false
  return response.json()
})
.then(data => {
  console.log(data)
})

Success Response

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

This endpoint stores a patient's insurance information and returns an insurance token.

HTTP Request

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

Body Fields

Field Name Type Description and Example
patient_token String 72b8j2 (Required)
insurance JSON See the section below for more details (Required)

Insurance Fields

The insurance field is required for all Insurance Requests.

Insurance Details

{
  "insurance": {
    "cardholder_id": "A9321328",
    "rx_group": "006726",
    "rx_bin": "997928",
    "pcn": "TXMH",
    "phone_number": "(955) 372-4143",
  }
}
Field Name Type Description and Example
cardholder_id String XMP223243 (Required): Member ID number on insurance card
rx_group String 23232 (Required): RX group on insurance card
rx_bin String(6-8) 003858 (Required): RX Bin on card, always 6-8 digits
pcn String AXA (Required): Member ID number on insurance card
phone_number String (955) 372-4143 (Optional): Insurance provider phone number

Copay Request

Create Copay Request

curl -X POST https://api.truepill.com/v1/copay_request \
   --header 'Authorization: ApiKey <API KEY>' \
   -d patient_token='1d4b33' \
   -d insurance_token='fa05bwp52ae2qaf0' \
   -d prescriptions='[
        "z3q2jr",
        "3cs873",
        "wz25v2"
   ]' \
   -d metadata='z5kp68x5cnxm'
const body = {
  patient_token: '1d4b33',
  insurance_token: 'fa05bwp52ae2qaf0',
  prescriptions: ["z3q2jr", "3cs873", "wz25v2" ],
  metadata: 'z5kp68x5cnxm',
}

fetch('https://api.truepill.com/v1/copay_request', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey Your_API_Key_Here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
.then(response => {
  if (!response.ok) return false
  return response.json()
})
.then(data => {
  console.log(data)
})

Success Response

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

This endpoint generates a Copay Request to retrieve copay information on a patient's prescription(s).

HTTP Request

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

Body Fields

Field Name Type Description and Example
patient_token String 72b8j2 (Required)
insurance_token String jq2ku3mu679543u8 (Required)
prescriptions Array[String] ["4ddy38", "b5q3t2", "h3r55c"] (Required): List of patient's prescription tokens
metadata String j6u2e56gvdbj (Optional) Provided by customer

Patient

Get Patient

curl --request GET \
  --url https://api.truepill.com/v1/patient/:patient_id 
  --header 'authorization: ApiKey <API KEY>' \ 

// polyfill fetch API, or use node `http` library

fetch('https://api.truepill.com/v1/patient/:patient_id', {
    method: 'GET',
    headers: {
      'Authorization': 'ApiKey <API KEY>',
      'Content-Type': 'application/json'
    }
  })
  .then(response => {
    if (!response.ok) return false
    return response.json()
  })
  .then(data => {
    console.log(data)
  })

// e.g.

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

Retrieve the details of a Patient by their patient id.

HTTP Request

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

Success Response

{
    "patient_first_name" : "Alex",
    "patient_last_name" : "Smith",
    "patient_dob" : "19891123",
    "patient_gender" : "Male",
    "rx_history" : [
    { 
      "prescription_id" : "bf1910",
      "patient_id" : "6ce427",
      "transferred_list_id" : null,
      "refill_number" : 0,
      "expiration_date_utc" : "Sat, 08 Jun 2019 07:00:00 UTC +00:00",
      "future_fill" : 0,
      "allow_partial_fills" : 1,
      "refills_remaining" : 1,
      "quantity_remaining" : 90,
      "number_of_refills_allowed" : 1,
      "prescribed_drug_strength" : "0.1 %",
      "prescribed_quantity" : 45,
      "prescribed_brand_name" : "Retin-A",
      "prescribed_written_name" : "Tretinoin 0.1% Cream",
      "prescribed_generic_name" : "Tretinoin 0.1 % Topical Cream",
      "dispensed_drug_strength" : "0.1 %",
      "dispensed_quantity" : 45,
      "dispensed_days_supply" : 30,
      "dispensed_brand_name" : "Retin-A",
      "dispensed_generic_name" : "Tretinoin 0.1 % Topical Cream",
      "dispensed_drug_name" : "Tretinoin 0.1% Cream",
      "date_written" : "Fri, 08 Jun 2018 00:00:00 UTC +00:00"
    }
  ],
  "order_history": [
    {
      "prescription_id" : "bf1910",
      "delivery_address" : "Alex Smith 1700 S Amphlett Blvd #221 San Mateo 94402 TN",
      "status" : "01",
      "created_at" : "Mon, 06 Aug 2018 21:43:04 UTC +00:00",
      "request_id" : "fill_request_869a0547f1bd086d1584",
      "medication_name" : "Lipitor"
    },
    {
    "prescription_id" : "bf1910",
    "delivery_address" : "Alex Smith 1700 S Amphlett Blvd #221 San Mateo 94402 TN",
    "status" : "01",
    "created_at" : "Mon, 07 Aug 2018 21:43:04 UTC +00:00",
    "request_id" : "fill_request_869a0547f1bd086d1584",
    "medication_name" : "Lipitor"
    }
  ]
}

Find Patient

curl --request GET \
  --url https://api.truepill.com/v1/patient?\
              first_name=:patient_first_name&\
              last_name=:patient_last_name&\
              dob=:patient_dob 
  --header 'Authorization: ApiKey <API KEY>'\


// polyfill fetch API, or use node `http` library

fetch('https://api.truepill.com/v1/patient?first_name=:patient_first_name&last_name=:patient_last_name&dob=:patient_dob', {
    method: 'GET',
    headers: {
      'Authorization': 'ApiKey <API KEY>',
      'Content-Type': 'application/json'
    }
  })
  .then(response => {
    if (!response.ok) return false
    return response.json()
  })
  .then(data => {
    console.log(data)
  })


Retrieve the details of a Patient by their first name, last name, and date of birth (dob). Note that the date of birth must be sent as YYYY-MM-DD.

HTTP Request

GET https://api.truepill.com/v1/patient?first_name=:patient_first_name&last_name=:patient_last_name&dob=:patient_dob

Success Response

{
    "patient": {
        "dob_obj": "1950-10-10",
        "first_name": "Example",
        "last_name": "Example",
        "hipaa_packet_accepted": true,
        "patient_id": "lb1695"
    }
}

Customer

Update Customer Information

This endpoint allows you to update your existing webhook configuration by supplying the specific parameters to be updated.

curl --request PATCH \
--url https://api.truepill.com/v1/customer \
--header 'Authorization: ApiKey <API KEY>' \
--header 'content-type: application/json' \
--data '{
     "production_callback_url": "https://www.example.com/callback_listener",
     "test_callback_url": "https://test.example.com/callback_listener",
     "http_basic_auth": "Basic SdsfonasSVONfsodFN1235nsofSDD"
  }'

HTTP Request

PATCH https://api.truepill.com/v1/customer

Body Fields

Field Name Type Description and Example
production_callback_url string https://www.example.com/callback_listener
test_callback_url string https://test.example.com/callback_listener
http_basic_auth string will be sent as an 'Authorization' header on every callback sent Basic SdsfonasSVONfsodFN1235nsofSDD

Callback/Webhook Overview

Register a webhook server to receive callbacks for updates as we process your order. To receive these updates, use the Customer endpoint to set your production_callback_url and http_basic_auth parameters. Alternatively, set these parameters on our customer dashboard.

Order

Success

{
  "request_id": "fill_request_3434skdfh328rdfkax",
  "status": "success",
  "callback_type": "ORDER",
  "timestamp":1502304584,
  "details": {
    "message": "Your fill request was processed and is pending shipment.",
    "patient_copay_amount": "0",
    "product_name": "Doxycycline Hyclate 100mg Tab",
    "medication_name": "Doxycycline Hyclate 100mg Tab",
    "quantity": "30",
    "days_supply": "30",
    "tracking_url": "http://www.usps.com/track/3824738927493234"
  }
}

Error

{
  "request_id": "fill_request_3d549f80db9728b48549",
  "status": "error",
  "callback_type": "ORDER",
  "details": {
    "error_code": "9",
    "description": "Coverage terminated",
    "message": "Insurance coverage terminated, please ask patient for updated coverage"
  }
}

Fill Requests have various statuses as they progress through the prescription fulfillment process. Status updates will be sent as a callback with the text “ORDER” in the “callback_type” field. The first of these updates will indicate whether the order is ready for shipment or if it has instead been rejected. This information is provided through the “status” field with the value of “success” or “error” respectively. In the latter case, where the field indicates rejection, further information needs to be provided for the order to be filled.

Success Details Fields

Field Name Type Description and Example
metadata string Provided by customer
message string Plain english status text
date_filled string Filled Date of RX
days_supply integer number of days supply
medication_name string requested medication name
dispensed_medication_name string dispensed (substitution) medication name
requested_medication_name string requested medication name
quantity integer quantity sent
remaining_refills Remaining Refills rx information
patient_copay_amount integer if insurance order
tracking_url string URL to be used for carrier tracking
patient_token string Associated patient's url token

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 Details Fields

Field Name Type Description and Example
metadata string Provided by customer
message string Plain english status text
error code string Error Codes
patient_token string Associated patient's url token

Order Error Codes

Each rejection callback 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. It is important to note that the same descriptions may correspond to several different error codes. The following table depicts a typical mapping of error codes to descriptions.

Code Message
09 Unknown Error
12 Bad Insurance Details
79 Refill too soon
R0 Order Cancelled by Customer Request
R1 Duplicate Order
R2 Bad Address Details
R3 Out of stock
R4 Returned to sender
PC No e-RX

Common Failures

Batch Medications

You will receive callbacks for each indiviaul medication requested in the medication_name field. Each callback will contain the corresponding medication's name in the message field.

Success

{
  "request_id": "fill_request_2c069215483bb6676a9b",
  "status": "success",
  "callback_type": "ORDER",
  "timestamp":1502304584,
  "details": {
    "message": "Your fill request was processed and is pending shipment.",
    "patient_copay_amount": "0",
    "product_name": "Doxycycline Hyclate 100mg Tab",
    "medication_name": "Doxycycline Hyclate 100mg Tab",
    "quantity": "30",
    "days_supply": "30",
    "tracking_url": "http://www.usps.com/track/3824738927493234"
  }
}

{
  "request_id": "fill_request_2c069215483bb6676a9b",
  "status": "success",
  "callback_type": "ORDER",
  "timestamp":1502304584,
  "details": {
    "message": "Your fill request was processed and is pending shipment.",
    "patient_copay_amount": "0",
    "product_name": "Lipitor",
    "medication_name": "Lipitor",
    "quantity": "5",
    "days_supply": "30",
    "tracking_url": "http://www.usps.com/track/3824738927493234"
  }
}

Error

{
  "request_id": "fill_request_2c069215483bb6676a9b",
  "status": "error",
  "callback_type": "ORDER",
  "details": {
    "error_code": "NR",
    "description": "No Refills Remaining",
    "message": "Error: there was an issue during fulfillment. No Refills Remaining; Doxycycline Hyclate 100mg Tab"
  }
}

{
  "request_id": "fill_request_2c069215483bb6676a9b",
  "status": "error",
  "callback_type": "ORDER",
  "details": {
    "error_code": "NR",
    "description": "No Refills Remaining",
    "message": "Error: there was an issue during fulfillment. No Refills Remaining; Lipitor"
  }
}

Success and Error

{
  "request_id": "fill_request_2c069215483bb6676a9b",
  "status": "success",
  "callback_type": "ORDER",
  "timestamp":1502304584,
  "details": {
    "message": "Your fill request was processed and is pending shipment.",
    "patient_copay_amount": "0",
    "product_name": "Doxycycline Hyclate 100mg Tab",
    "medication_name": "Doxycycline Hyclate 100mg Tab",
    "quantity": "30",
    "days_supply": "30",
    "tracking_url": "http://www.usps.com/track/3824738927493234"
  }
}

{
  "request_id": "fill_request_2c069215483bb6676a9b",
  "status": "error",
  "callback_type": "ORDER",
  "details": {
    "error_code": "NR",
    "description": "No Refills Remaining",
    "message": "Error: there was an issue during fulfillment. No Refills Remaining; Lipitor"
  }
}

Shipment

Success

{
  "request_id": "fill_request_3434skdfh328rdfkax",
  "status": "success",
  "callback_type": "SHIPMENT",
  "timestamp":1502304584,
  "details": {
    "status": "TRANSIT",
    "message": "Your shipment has arrived at the USPS regional destination facility.",
    "eta": "2018-01-05T15:00:00Z",
    "patient_copay_amount": "0",
    "product_name": "Doxycycline Hyclate 100mg Tab",
    "medication_name": "Doxycycline Hyclate 100mg Tab",
    "quantity": "30",
    "days_supply": "30",
    "tracking_url": "http://www.usps.com/track/3824738927493234"
  }
}

Error

  There is no error callback.

While an order is in transit, carrier shipment updates are sent with the text “SHIPMENT” in the “callback_type” field. It’s common to receive multiple shipment callbacks in the same order the updates are provided by the carrier.

Success Details Fields

Field Name Type Description and Example
metadata string Provided by customer
message string Status text from carrier
days_supply integer number of days supply
medication_name string requested medication name
dispensed_medication_name string dispensed (substitution) medication name
requested_medication_name string requested medication name
quantity integer quantity sent
remaining_refills Remaining Refills rx information
patient_copay_amount integer if insurance order
tracking_url string URL to be used for carrier tracking

Transfer

Success

{
    "request_id": "transfer_request_9a813a5a8782d15923da",
    "timestamp": 1564611968,
    "callback_type": "TRANSFER",
    "status": "success",
    "details": {
        "metadata": "0234iu19ui412",
        "message": "Here is a list of medications that were successfully transferred",
        "patient_token": "361fffsa66",
        "medication_list": [
            {
                "transfer_medication_id": "6c34dacasdeb49",
                "requested_medication_name": "Bupropion XL",
                "last_filled_date": "No Data",
                "prescription_token": "123123082b",
                "medication_name": "Bupropion Hcl Xl 300 Mg Tablet",
                "num_refills_remaining": 1,
                "quantity": 150,
                "days_supply": 30
            }
        ]
    }
}

Error

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

Transfer Callbacks are sent on the completion of a prescription transfer with the text “TRANSFER” in the “callback_type” field and, like with other callbacks, the “status” field indicating whether or not it was successful. In a successful transfer, a detailed list of the transferred medications will be provided in the “medication_list” field.

Success Details Fields

Field Name Type Description and Example
metadata string Provided by customer
message string Plain english status text
patient_token string Associated patient's url token
medication_list Medication List rx information

Medication List

An Array of Medications.

Field Name Type Description and Example
transfer_medication_id string medication id
medication_name string name on rx
requested_medication_name string requested medication name
num_refills_remaining integer total refills remaining on rx
last_filled_date integer 1502304584
prescription_token string token used for looking up an rx
quantity integer quantity of rx
days_supply integer days supply of rx

Copay

Success

{
  "request_id": "cnpsa8ms8vbs7f52c8y2xchd77tza3nv",
  "status": "success",
  "callback_type": "COPAY",
  "timestamp": 1563916377515, 
  "details": {
    "metadata": "e5yfdv6b26v8bnj249ze",
    "message": "Here is a list of medications that we have successfully checked the copay amounts for",
    "patient_token": "2f86ob",
    "prescriptions": [
      {
        "prescription_token": "42b21f",
        "status": "completed",
        "next_fillable_date": "2019-07-23T00:00:00.000Z",
        "copay_amount": "21.02",
        "copay_request_prescription_token": "98dagjw"
      },
      {
        "prescription_token": "8a5nzx",
        "status": "completed",
        "next_fillable_date": "2019-08-05T00:00:00.000Z",
        "copay_amount": "1.10",
        "copay_request_prescription_token": "ad92wek"
      },
    ]
  }
}

Error

{
  "request_id": "cnpsa8ms8vbs7f52c8y2xchd77tza3nv",
  "status": "error",
  "callback_type": "COPAY",
  "timestamp": 1563916377515, 
  "details": {
    "metadata": "e5yfdv6b26v8bnj249ze",
    "message": "There was an error retrieving the copays",
    "patient_token": "2f86ob",
    "reject_reason": "Refill too soon"
  }
}

Copay Callbacks are sent on completion of a copay check request with the text COPAY in the “callback_type” field. Like other callbacks, the “status” field indicates if it was successful. In a successful copay check, a detailed list of the transferred medications will be provided in the “prescriptions” field.

Success Details Fields

Field Name Type Description
metadata String Provided by customer
message String Plain english status text
patient_token String Associated patient's url token
prescriptions Prescriptions rx information
copay_request_prescription_token String Token for identifying a prescription in a copay request

Prescriptions

An Array of Prescriptions.

Field Name Type Description
prescription_token string Associated prescription's url token
status string Status of copay request on associated prescription
next_fillable_date String Date the associated prescription is fillable
copay_amount String Copay price for the associated prescription
reject_reason String A string containing the rejection reason

Callback/Webhooks Endpoints

Get Callbacks

curl --request GET \
  --url https://api.truepill.com/v1/callback \
  --header 'Authorization: ApiKey <API KEY>'
fetch('https://api.truepill.com/v1/callback', {
    method: 'GET',
    headers: {
      'Authorization': 'ApiKey Your_API_Key_Here'
    }
  })
  .then(response => {
    if (!response.ok) return false
    return response.json()
  })
  .then(data => {
    console.log(data)
  })

Response

[
 {
    "request_id": "fill_request_be1af2057a5704ae0764",
    "status": "success",
    "details": {
      "metadata": null,
      "message": "Your fill request was processed and is pending shipment.",
      "remaining_refills": {
        "medication_name": "Escitalopram 20 Mg Tablet",
        "total_remaining_refills": 5,
        "total_quantity_remaining": 150
      },
      "days_supply": 30,
      "medication_name": "Escitalopram 20 Mg Tablet",
      "patient_copay_amount": 0,
      "quantity": 30,
      "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=92001902453595000000058875"
    },
    "callback_type": "ORDER",
    "timestamp": 1551399285,
    "status_code": 204,
    "message_id": "580f3ccc-ca18-4780-aa39-40186e818b96"
  },
  {
    "request_id": "fill_request_f85e3c5088eac7654f87",
    "status": "success",
    "details": {
      "metadata": null,
      "status": "DELIVERED",
      "message": "Your shipment has been delivered at the destination mailbox.",
      "eta": null,
      "days_supply": 30,
      "medication_name": "Quetiapine Fumarate 25 Mg Tab",
      "patient_copay_amount": 0,
      "quantity": 30,
      "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=92001902654395000000003214"
    },
    "callback_type": "SHIPMENT",
    "timestamp": 1551399483,
    "status_code": 204,
    "message_id": "8ccbe4b6-fac4-6503-b5ee-cc483d567e29"
  }
]

Use this endpoint to retrieve any callbacks we have sent to your configured webhook URL. This endpoint retrieves the details of up to 500 callbacks matching your supplied parameters. If your webhook URL has never been configured correctly, no callbacks will exist.

HTTP Request

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

Query Parameters

Field Name Type Description and Example
callback_type string ['SHIPMENT', 'ORDER', 'TRANSFER']
order_token string r83dcw
api_token string fill_request_fff9d6baf127cb1dc4e7
start Datetime 2019-03-01 00:00:00 (requires end set) this assumes UTC
end Datetime 2019-03-02T12:00:00-07:00 (requires start set) this would be Pacific Daylight Time

Resend Callbacks

This endpoint resends a specified callback, if it existed historically, to the configured webhook URL. Use all the same fields from the GET as a POST body to resend the same result set.

HTTP Request

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

Return Prescription

Create Return Request

curl --request POST \
  --url https://api.truepill.com/v1/return_request \
  --header 'Authorization: ApiKey <API KEY>' \
  -d request_id="fill_request_5006d850bfee8e87788e"

const body = {
  request_id: 'fill_request_34f68f71f980f78bb0bc'
}

fetch('https://api.truepill.com/v1/return_request', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey Your_API_Key_Here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
})
.then(response => {
  if (!response.ok) return false
  return response.json()
})
.then(data => {
  console.log(data)
})


Success Response

{
  "request_id": "return_request_339e449963aade92b83c",
  "timestamp": 1518052078,
  "status": "error",
  "details": {
    "message": "Accepted: a return label for fill_request_5006d850bfee8e87788e has been created.",
    "label_url": "https://shippo-delivery-east.s3.amazonaws.com/e4a15af4405b4aa3acd5158be2a72909.png?Signature=<AWS SIGNATURE>",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=<USPS TRACKING>",
    "carrier": "usps",
    "tracking_number": "<USPS TRACKING>",
    "metadata": "dJsbiT22"
  }
}

Error Response (Label)

{
  "request_id": "return_request_339e449963aade92b83c",
  "timestamp": 1518052078,
  "status": "error",
  "details": {
    "message": "Error: a return label for fill_request_5006d850bfee8e87788e already exists.",
    "label_url": "https://shippo-delivery-east.s3.amazonaws.com/7f680dca6fb54cc48d70a6dd73d2274c.png?Signature=<AWS SIGNATURE>",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=<USPS TRACKING>",
    "carrier": "usps",
    "tracking_number": "<USPS TRACKING>",
    "metadata": "dJsbiT22"
  }
}

Error Response (Unauthorized)

{
  "request_id": "return_request_339e449963aade92b83c",
  "timestamp": 1518052744,
  "status": "error",
  "details": {
    "message": "Error: a return label for fill_request_5006d850bfee8e87788e could not be created. This API request is not associated with this API key, please contact us at (855) 910-8606 if further assistance is required.",
    "metadata": "dJsbiT22"
  }
}

This endpoint provides a return label for a Fill Request whose "request_id" field matches the user provided text value in the parameter of the same name. A return label can only be provided if the Fill Request was successfully delivered within 30 days of the return label request. After this period or after having already requested a return label, a new request will return an error.

HTTP Request

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

Request Fields

Field Name Type Description and Example
request_id String fill_request_34f68f71f980f78bb0bc (Required): Fill Request ID

Shared Models

Address

Field Name Type Description and Example
name String Sarah Doe (Required)
company String ABC Inc. (Optional)
street1 String 449 Farrel Ct (Required)
street2 String Apt 456 (Optional)
city String San Francisco (Required)
state String CA (Required)
zip String 94107 (Required)
country String US (Required): Use US for all requests
phone String (347) 676-9989 (Optional)
email String sarah@example.com (Optional)

Patient (shared)

Field Name Type Description and Example
first_name String Sarah (Required)
last_name String Doe (Required)
gender String female (Required): male or female
dob String 19840123 (Required): yyyymmdd format
address Address Address Object

Prescriber

Field Name Type Description and Example
first_name String Sarah (Required)
last_name String Doe (Required)
npi String 231421342134 (Required)
dea String ABA09121234 (Required For Controlled)
address Address Address Object

Survey Response Search

Use this API (No Authorization Required) to search for Allergens, Conditions, or Medications.

https://survey-responses.truepill.com

List

GET https://survey-responses.truepill.com/list

This will list all the entries in our system currently. This is useful if you want to build a no delay frontend interface with this information rather than leverage our fuzzy search endpoint.

curl --request GET \
  --url https://survey-responses.truepill.com/list

fetch('https://survey-responses.truepill.com/list', {
  method: 'GET'
})
.then(response => {
  if (!response.ok) return false
  return response.json()
})
.then(data => {
  console.log(data)
})


Success Response

{
  "allergens": [
      "1,2-Hexanediol",
      "1,2-Octanediol",
      "1,3-Butylene Glycol"
  ],
  "medications": [
      "1,2-Hexanediol",
      "1,2-Octanediol",
      "1,3-Butylene Glycol"
  ],
  "conditions": [
      "1,2-Hexanediol",
      "1,2-Octanediol",
      "1,3-Butylene Glycol"
  ]
}

Search Allergens

GET https://survey-responses.truepill.com/allergens?term={term}

curl --request GET \
  --url https://survey-responses.truepill.com/allergens?term=pea

fetch('https://survey-responses.truepill.com/allergens?term=pea', {
  method: 'GET'
})
.then(response => {
  if (!response.ok) return false
  return response.json()
})
.then(data => {
  console.log(data)
})


Success 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"
]

Search Conditions

GET https://survey-responses.truepill.com/conditions?term={term}

curl --request GET \
  --url https://survey-responses.truepill.com/conditions?term=pea

fetch('https://survey-responses.truepill.com/conditions?term=pea', {
  method: 'GET'
})
.then(response => {
  if (!response.ok) return false
  return response.json()
})
.then(data => {
  console.log(data)
})


Success 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"
]

Search Medications

GET https://survey-responses.truepill.com/medications?term={term}

curl --request GET \
  --url https://survey-responses.truepill.com/medications?term=pea

fetch('https://survey-responses.truepill.com/medications?term=pea', {
  method: 'GET'
})
.then(response => {
  if (!response.ok) return false
  return response.json()
})
.then(data => {
  console.log(data)
})


Success 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"
]