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": "Doxycycline Hyclate 100mg Tab",
      "quantity_dispensed": "30",
      "days_supply": "30",
      "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,
      "patient_known_allergies": "Known Allergies: None, Other Medications: None",
      "patient_other_medications": "Benadryl",
      "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: 'Doxycycline Hyclate 100mg Tab',
  quantity_dispensed: '30',
  days_supply: '30',
  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,
  patient_known_allergies: 'Known Allergies: None, Other Medications: None',
  patient_other_medications: 'Benadryl',
  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)
})

Success Response

{
  "request_id": "fill_request_3434skdfh328rdfkax",
  "status": "success",
  "details": {
      "message": "Your fill request was processed successfully. Please standby for updates to your callback URL"
  }
}

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 (Optional): Required for insurance paying customer
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) 003858 (Optional): RX Bin on card, always 6 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 String Doxycycline 100mg tablet (Optional): 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
quantity_dispensed Number (Integer) 30 (Optional): Required if RX, number of pills requested
days_supply Number (Integer) 30 (Optional): Required if RX, days supply requested
prescribing_doctor String Dr. Smart (Optional): Required if RX
medication_sig String Take up to 4 tablets per 24 hours, do not exceed this amount (Optional): Required if RX
refill_number Number (Integer) 2 (Optional): Required if RX
is_refill Boolean false (Optional): true or false
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_known_allergies String Hay Fever (Optional) Deprecated in favor of patient_survey[allergies]
patient_other_medications String Spironolactone 25mg (Optional) Deprecated in favor of patient_survey[medications]
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.

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 patient_first_name="Guy" \
   -d patient_last_name="Jones" \
   -d patient_dob="19840123" \
   -d patient_gender="male" \
   -d patient_payment_type="insurance" \
   -d cardholder_id="953M81593" \
   -d rx_bin="003858" \
   -d rx_group="WLHA" \
   -d medication_name="Doxycycline Hyclate 100mg Tab"
   -d quantity_dispensed="30" \
   -d days_supply="30"
   -d address_from_name="John Doe" \
   -d address_from_company="Postmeds Inc." \
   -d address_from_street1="31123 Mission Blvd." \
   -d address_from_street2="Suite 201" \
   -d address_from_city="Hayward" \
   -d address_from_state="CA" \
   -d address_from_zip="94043" \
   -d address_from_country="US" \
   -d address_from_email="support@postmeds.com" \
   -d address_from_phone="3018064773" \
   -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" 

const body = {
  request_id: '<FILL_REQUEST_API_TOKEN>',
  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: 'Doxycycline Hyclate 100mg Tab',
  quantity_dispensed: '30',
  days_supply: '30',
  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,
  patient_known_allergies: 'Known Allergies: None, Other Medications: None',
  patient_other_medications: 'Benadryl',
  metadata: 'your_internal_identifier',
  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)
patient_first_name String Sarah (Required)
patient_last_name String Doe (Required)
patient_gender String male or female (Optional): Required for insurance paying customer
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) 003858 (Optional): RX Bin on card, always 6 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 String Doxycycline 100mg tablet (Optional): empty if only requesting OTC products
otc_products Array [{"item": "Lotion", "quantity": "2"}, {"Vitamins": "quantity":"1"}] (Optional): Request must include either RX or OTC
quantity_dispensed Number (Integer) 30 (Optional): Required if RX, number of pills requested
days_supply Number (Integer) 30 (Optional): Required if RX, days supply requested
prescribing_doctor String Dr. Smart (Optional): Required if RX
medication_sig String Take up to 4 tablets per 24 hours, do not exceed this amount (Optional): Required if RX
refill_number Number (Integer) 2 (Optional): Required if RX
is_refill Boolean false (Optional): true or false
check_in Boolean false (Optional): Set to true to request that a pharmacist check in with the patient prior to filling the prescription
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)

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: 'Guy',
  patient_last_name: 'Jones',
  patient_dob: '19840123',
  patient_gender: 'male',
  current_pharmacy_name: 'CBS Pharmacy',
  current_pharmacy_phone: '3018897765'
}

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_c91f2af0a847271bdc0b",
  "status": "success",
  "timestamp": 1502304584, 
  "details": {
    "message": "Your transfer request was processed successfully. Please standby for updates to your callback URL."
  }
}

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

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" : nil,
      "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.

Fill Request

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_3434skdfh328rdfkax",
  "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.

Fill Request 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
9 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

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

There isn't an error shipment

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.

Transfer

Success

{
  "request_id": "transfer_request_c91f2af0a847271bdc0b",
  "status": "success",
  "callback_type": "TRANSFER",
  "timestamp": 1502304584, 
  "details": {
    "message": "Here is a list of medications that were successfully transferred",
    "medication_list": [
      {
        "medication_name": "Spironolactone 10mg tablet",
        "num_refills_remaining": "5",
        "quantity": "30",
        "days_supply": "30",
        "last_filled_date": 1502304584     
      },
      {     
        "medication_name": "Sprintec Tablet",
        "num_refills_remaining": "2",
        "quantity": "28",
        "days_supply": "28",
        "last_filled_date": 1502304584     
      }
    ]
  }
}

Error

{
  "request_id": "transfer_request_c91f2af0a847271bdc0b",
  "status": "error",
  "callback_type": "TRANSFER",
  "timestamp": 1502304584, 
  "details": {
    "message": "No medications were able to be transferred",
    "medication_list": []
  }
}

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.

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.

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