Introduction
Welcome to the Truepill API! Our mission is to put patients first. We believe fundamentally that having open and accessible APIs for healthcare is critical to empower our partners to deliver world-class patient experiences.
We’re thrilled to have partners like you that are looking to revolutionize the patient experience. Our API platform is central to our business and we’re excited for you to get started. We hope your integration experience is smooth and if you have any questions please reach out to support@truepill.com.
Overview
The Truepill API is a powerful and robust RESTful JSON-based API. This API will give you the ability to access our healthcare infrastructure to do things like deliver medications to all 50 states, request a prescription refill, transfer a prescription from another pharmacy, request a copay or eligibility information, request a physician consult, create a patient record in our programmable EMR, and much more.
Authentication
API Call with Correct Header Configuration
# Just Pass the Correct Authorization Header
curl "endpoint"
-H "Authorization: ApiKey API KEY"
fetch('https://api.truepill.com/v1/patient', {
method: 'PUT',
headers: {
Authorization: 'ApiKey [YOUR API KEY]',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
API Response When Invalid API Key Is Submitted
{
"statusCode": 401,
"error": "Unauthorized",
"message": "Please Send a Valid Api-Key"
}
The Truepill API uses key-based authentication. Requests are authenticated using HTTP Basic Auth. Provide your API key in an Authorization HTTP header for all requests. If you do not pass in an Authorization HTTP header with a valid API key, your requests will not authenticate successfully.
Versioning
Truepill APIs are currently on version "1". The version is specified in all API requests with /v1/
in the API endpoint.
HIPAA & Security
Truepill takes the security and confidentiality of PHI very seriously. We ensure your data integrity is a top priority — from the moment you initiate an API request, all the way to when your patient receives medication from us.
Truepill uses a set of policies and procedures to safeguard our physical and technical infrastructure to maintain compliance with the HIPAA Privacy Rule, Security Rule, Transactions and Code Sets Rule, and their implementing regulations.
Making Requests
API Response When Empty Field Is Passed In
{
"statusCode": 400,
"error": "Bad Request",
"validation_errors": [
{
"key": "street1",
"message": "is not allowed to be empty"
}
]
}
Production Base Request URL: https://api.truepill.com/v1
In order to access the Truepill API, you will need an API key which will be provisioned and provided to you during the onboarding process. You will be given two unique keys: a sandbox and production API key.
As per RESTful design patterns, the Truepill API implements standard HTTP actions: GET, POST, PUT, DELETE. When making requests, arguments may be passed as params or JSON with the correct Content-Type header. Argument formats can vary by standard HTTP actions. On request responses, the data returned is in JSON format.
Each API endpoint will document optional and required fields that can be passed into the request body.
Errors
400 Bad Request Response
{
"statusCode": 400,
"error": "Bad Request",
"validation_errors": [
{
"key": "last_name",
"message": "is required"
}
]
}
404 Not Found Response
{
"statusCode": 404,
"error": "Not Found",
"message": "Resource Not Found."
}
Our API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON.
Additionally, different API endpoints have specific errors and error codes related to that endpoint. These endpoint-specific errors are covered in more detail as part of our full API reference.
Common HTTP Responses
Code | Text | Description |
---|---|---|
200 | OK | Success |
202 | Accepted | Success |
400 | Bad Request | Request body is not correctly formatted. Potential validation error/missing field |
401 | Unauthorized | Authentication credentials were missing or incorrect, i.e. API key is not valid |
404 | Not Found | Some entity not found In request |
Environments
You can access two separate environments — sandbox and production. You will distinguish which environment you are looking to access by using either your sandbox or production API key provided to you. The only functional difference between the two environments is that the sandbox environment has fake data and simulation error events which you can use to test the end-to-end experience.
Production Base Request URL: https://api.truepill.com/v1
Sandbox Base Request URL: https://api.falsepill.com/v1
Webhook Events
Shipment Webhook Event - Notifying Package Delivery Status
{
"request_id": "fill_request_991e90fa6b367cf72032",
"timestamp": 1590800222,
"callback_type": "SHIPMENT",
"status": "success",
"details": {
"metadata": "cfe146",
"status": "DELIVERED",
"message": "Your shipment has been delivered at the destination mailbox.",
"eta": "2020-06-02T00:54:31.838Z",
"tracking_number": "43904456187100000000000000",
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000",
"carrier": "usps"
}
}
Notify Rx Webhook Event
{
"timestamp": 1581019462,
"callback_type": "NOTIFY_RX",
"details": {
"medication_name": "Atorvastatin 40 mg tablet",
"prescriber": "Dr. Strange",
"prescription_token": "z3q2jr",
"patient_token": "4526d90a",
"transfer_prescription_token": "z3q2jr23",
"location": "Hayward, CA"
}
}
Production environments are integrated with live systems. Through these live systems, Truepill exposes processing events to our customers through webhook events.
Webhook events are asynchronous updates that notify the customer as an order is being processed. Customers may set up a webhook server to receive these events.
There are many different webhook events in the Truepill ecosystem:
These webhook event types will contain a few shared fields for reference, noted below:
Shared Webhook Event Fields
Field Name | Type | Description and Example |
---|---|---|
request_id | String | Token identifier of the request made (Fill request, Direct Transfer, etc.) |
callback_type | String | Type of webhook event |
status | String | Status of the request. Most commonly: success or error |
details | Object | Object containing more information specific to the type of webhook event |
timestamp | Integer | Number representing the number of seconds since midnight January 1, 1970 |
Simulating Webhook Events while Testing
In the sandbox environment, Truepill's live systems for managing eRx's don't exist. To make up for this, the sandbox environment houses frameworks to simulate these webhook events and prescriptions.
This will be important and useful as you test your integration end-to-end with Truepill's platform in the sandbox environment.
For a walkthrough on leveraging simulations, see Sandbox Testing with Simulations.
Managing Your Webhook Endpoint
To set or update your existing webhook configuration
- Sign in to the Truepill Dashboard.
- Select the Gear icon in the upper-right corner, and then select Profile.
- In the Account Details page, you can edit your production and test webhook endpoints, as well as test the integration.
Token Management
Our webhook events will return token representations for different objects with high-level details. Our most common tokens include the Patient token and the Prescription token.
These tokens are unique and ensure we limit the amount of sensitive and patient-identifiable data sent using webhook events.
Requests vs. Notify Webhook Events
Request Webhook Event: Order Success
{
"request_id": "fill_request_991e90fa6b367cf72032",
"timestamp": 1590800072,
"callback_type": "ORDER",
"status": "success",
"details": {
"metadata": "cfe146",
"message": "Your fill request was processed and is pending shipment.",
"date_filled": "N/A",
"medications": [
{
"medication_name": "Brand Label 10mg Tablet",
"dispensed_medication_name": "Brand Label 10mg Tablet",
"requested_medication_name": "prescription_token:7cb7d8ea418d",
"days_supply": 28,
"quantity": 42,
"fill_number": "0",
"rx_number": "452793000",
"total_refills_allowed": 2,
"prescription_token": "7cb7d8ea418d",
"medication_token": "e2b176d61505",
"dispensed_ndc": "1234567890",
"remaining_refills": {
"total_remaining_refills": 2,
"total_quantity_remaining": 84
}
},
{
"medication_name": "Generic Label 50mg Tablet",
"dispensed_medication_name": "Generic Label 50mg Tablet",
"requested_medication_name": "prescription_token:e9549cca9639",
"days_supply": 1,
"quantity": 12,
"fill_number": "2",
"rx_number": "452793000",
"total_refills_allowed": 2,
"prescription_token": "e9549cca9639",
"medication_token": "3fbsz9m613o9",
"dispensed_ndc": "0987654321",
"remaining_refills": {
"total_remaining_refills": 2,
"total_quantity_remaining": 48
}
}
],
"order_token": "3d2c77",
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000",
"tracking_number": "92001902453595000012688153",
"carrier": "usps",
"patient_token": "838a906bcc6e7671"
}
}
Notify Webhook Event: Notify Rx
{
"timestamp": 1581019462,
"callback_type": "NOTIFY_RX",
"details": {
"medication_name": "Atorvastatin 40 mg tablet",
"prescriber": "Dr. Strange",
"prescription_token": "z3q2jr",
"patient_token": "4526d90a",
"transfer_prescription_token": "z3q2jr23",
"location": "Hayward, CA"
}
}
There are two types of webhook events sent by the Truepill system. Request events are asynchronous events that are associated with a request that was made, and thus will always reference a request_id
. Notify events are not tied to a request but may be relevant to your specific workflow.
To the right are two examples of webhook event types — explained in greater detail later.
Get Webhook Events
Get Webhook Events Request
curl --request GET \
--url https://api.truepill.com/v1/webhook_events/notify_rx \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
fetch('https://api.truepill.com/v1/webhook_events/notify_rx', {
method: 'GET',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
}
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"results": [
{
"payload" : {
"timestamp": 1625177130,
"callback_type": "NOTIFY_RX",
"details": {
"medication_name": "Prozac 10 mg tablet",
"prescriber": "Dr. Mockdoc",
"prescription_token": "6c8f8c4e3e8c",
"patient_token": "aa86d0683aba4082",
"patient_token_duplicates": [],
"merged_patients": [],
"location": "hayward",
"rx_link": "rxl_7e26572b556bfc48e611da3a"
}
},
"delivery_data" : {
"status" : "success",
"status_code" : 200
}
},
{
"payload" : {
"timestamp": 1625177135,
"callback_type": "NOTIFY_RX",
"details": {
"medication_name": "Alprazolam 1 mg tablet",
"prescriber": "Dr. Mockdoc",
"prescription_token": "4bee4686e59c",
"patient_token": "aa86d0683aba4082",
"patient_token_duplicates": [],
"merged_patients": [],
"location": "hayward",
"rx_link": "rxl_56ec53ebf66fc9e2c5abaa82"
}
},
"delivery_data" : {
"status" : "success",
"status_code" : 200
}
},
...
{
"payload" : {
"timestamp": 1625177295,
"callback_type": "NOTIFY_RX",
"details": {
"medication_name": "Brand Label 10mg Tablet",
"prescriber": "Dr. P. Scribe",
"prescription_token": "e644ac29ed07",
"patient_token": "aa86d0683aba4082",
"patient_token_duplicates": [],
"merged_patients": [],
"location": "hayward",
"rx_link": "rxl_5fbcf211864b36e4616b1336"
}
},
"delivery_data" : {
"status" : "success",
"status_code" : 200
}
}
],
"next_page_token": "ef14ac4a652141dd"
}
GET https://api.truepill.com/v1/webhook_events/{webhook_type}?{query}={operator}:{value}
Webhook events can be retrieved via API to be reprocessed.
This endpoint returns a list of webhook events and allows for the use of query parameters to scope the results of the request. A request payload
represents the request's timestamp, type, and details. A request delivery_data
represents the request's status information.
The Get Webhook Events endpoint can be scoped to retrieve Notify Rx webhook events only as well.
Webhook Types
Name | Description | Query Parameters |
---|---|---|
notify_rx | Returns only Notify Rx webhook events, in time-ascending order | id, timestamp, next, status |
Query Operators
Name | Description | Value Type |
---|---|---|
$lt | Less than | Integer |
$gt | Greater than | Integer |
$lte | Less than or equal to | Integer |
$lte | Greater than or equal to | Integer |
$eq | Equals | Integer or String |
Fields Returned
Field Name | Type | Description and Example |
---|---|---|
results | Array Callback | List of Callback objects |
next_page_token | String | Token used in query parameter to retrieve the next page of results |
The results
array contains at most 100 entries per page. If the Get Webhooks request returns more than 100 results, next_page_token
can be used in a subsequent query to return the next page of results
.
GET Notify Rx Webhooks Example
GET https://api.truepill.com/v1/webhook_events/notify_rx?timestamp=$gt:1625177120×tamp=$lt:1625177295
Returns a list of Notify Rx callbacks where the timestamp is greater than 1625177120 and less than 1625177295 (and next_page_token
if applicable).
GET https://api.truepill.com/v1/webhook_events/notify_rx?next=ef14ac4a652141dd
Returns the next page using next_page_token
as the value for the next
query parameter.
Electronic Prescription
Notify Rx Webhook Event
{
"timestamp": 1581019462,
"callback_type": "NOTIFY_RX",
"details": {
"medication_name": "Atorvastatin 40 mg tablet",
"prescriber": "Dr. Strange",
"prescription_token": "z3q2jr",
"patient_token": "4526d90a",
"transfer_prescription_token": "z3q2jr23",
"location": "Hayward, CA"
}
}
An electronic prescription (eRx) is the computer-based electronic generation, transmission, and filing of a prescription. In the US, the accepted standard for eRx is the “SCRIPT standard,” governed by the National Council for Prescription Drug Programs (NCPDP).
A licensed US provider can write a new prescription to Truepill pharmacy over the Surescripts network. Once the prescription is received in our system, we will notify you using a Notify Rx webhook event confirming receipt of your patient’s prescription.
Patient
Create a Patient
Create Patient Request
curl -X PUT https://api.truepill.com/v1/patient \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
-d first_name='Bruce' \
-d last_name='Banner' \
-d guardian= 'John' \
-d gender='male' \
-d ssn='123456789' \
-d communications_opt_in=true \
-d id_image='https://user:securelogin@www.assets.com/rx/saijhofiasjfoasoi2f.png' \
-d dob='19691218' \
-d company='Gamma Inc.' \
-d street1='123 Some Lane' \
-d street2='Apt. 123' \
-d city='Los Angeles' \
-d state='CA' \
-d country='US' \
-d zip='94402' \
-d phone='430-304-3949' \
-d email='hulkout@hulk.com' \
-d language_preference ='English' \
-d species="Dog"
const body = {
first_name: 'Bruce',
last_name: 'Banner',
guardian: 'John',
gender: 'male',
dob: '19691218',
street1: '123 Some Lane',
street2: 'Apt. 123',
city: 'Los Angeles',
state: 'CA',
country: 'US',
zip: '94402',
phone: '430-304-3949',
email: 'hulkout@hulk.com' ,
language_preference: 'English',
species: 'Dog',
viewed_notice_of_privacy_practices: true,
viewed_notice_of_privacy_practices_date: '20220101'
}
fetch('https://api.truepill.com/v1/patient', {
method: 'PUT',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"patient_token": "4526d90a"
}
Error Response - Missing Fields
{
"statusCode": 400,
"error": "Bad Request",
"validation_errors": [
{
"key": "last_name",
"message": "is required"
},
{
"key": "gender",
"message": "is required"
},
{
"key": "dob",
"message": "is required"
}
]
}
PUT https://api.truepill.com/v1/patient
This endpoint generates a patient record in the Truepill ecosystem.
Upon a successful request, the endpoint returns a patient_token
for you to reference in subsequent API requests that require this field.
The patient_token
that is returned upon successfully creating a patient record can be used with many of the other endpoints to continue referencing the same record.
If the patient information in the request body matches the information in an existing patient record, the existing patient_token
will be returned in the API response.
Create Patient Body Fields
Field Name | Type | Description and Example | Required? |
---|---|---|---|
first_name | String | Legal patient first name | Yes |
last_name | String | Legal patient last name | Yes |
guardian | String or null | Pet owner first name | No |
dob | String | Legal patient date of birth, YYYYMMDD format | Yes |
gender | String | Assigned gender at birth: male or female |
Yes |
ssn | String | Social Security Number, 123456789 |
No |
communications_opt_in | Boolean | Communications opt in? | No |
id_image | String | URL for image of user ID | No |
ssn_serial | String | Social Security Number (last 4 digits), 3654 |
No |
mbi | String | Medicare Beneficiary ID, 1EG4TE5MK73 |
No |
zip | String | Patient’s zip code | No |
company | String | Name of company associated with patient (if applicable) | No |
street1 | String | Street 1 of patient’s address | No |
street2 | String | Street 2 of patient’s address (if applicable) | No |
city | String | City of patient’s address | No |
state | String | State of patient’s address, two-letter abbreviation | No |
phone | String | Patient’s phone number | No |
String | Patient’s email address | No | |
language_preference | String | Patient’s preferred language: English or Spanish |
No |
species | String | Patient’s pet species. See the Species list. If not specified, the default value is HUMAN |
No |
viewed_notice_of_privacy_practices | Boolean | Received Truepill’s Notice of Privacy Practices? | No |
viewed_notice_of_privacy_practices_date | String | If viewed_notice_of_privacy_practices is true , in YYYYMMDD format, the default value is date of API request |
No |
Species
If you choose to provide pet information for pet records and fulfilling pet medications, we expect one of the following pet species.
- Addax
- African Goshawk
- Alpaca
- Arctic Char
- Atlantic Salmon
- Badger
- Bat
- Bear
- Beaver
- Bison
- Bivalvia
- Bobcat
- Brill
- Budgerigar
- Buffalo
- Camel
- Carp
- Cat/Feline
- Catfish
- Cattle/Bovine
- Cephalopoda
- Chicken
- Chinchilla
- Cockatiel
- Cockatoo
- Cod
- Common Canary
- Cougar
- Crocodile
- Crow
- Crucian Carp
- Dog/Canine
- Donkey/Asinine
- Dormouse
- Duck
- Dwarf Hamster
- Eagle
- Elk
- European Eel
- European Hamster
- European Lynx
- European Rabbit
- Fallow
- Ferret
- Fox
- Frog
- Gerbil
- Gilthead
- Goat/Carpine
- Golden Hamster
- Goldfish
- Goose
- Gudgeon
- Guinea Fowl
- Guinea Pig
- Halibut
- Hare
- Hedgehog
- Horse/Equine
- House Mouse
- Hybrid
- Iguana
- Jackal
- Jaguar
- Kestrel
- Kite
- Largemouth Bass
- Leopard
- Lion
- Lizard
- Llama
- Macaw
- Mink
- Monkey
- Moose
- Mullet
- Ostrich
- Other Arthopoda
- Other Aves
- Other Bovinae
- Other Camelidae
- Other Caprinae
- Other Cervidae
- Other Equidae
- Other Felidae
- Other Leporidae
- Other Mammalia
- Other Mollusca
- Other Mustelidae
- Other Pisces
- Other Rodentia
- Other Suidae
- Owl
- Parakeet
- Parrot
- Partridge
- Perch
- Peregrin Falcon
- Pheasant
- Pig/Porcine
- Pigeon
- Pike
- Puma
- Quail
- Raccoon Dog
- Rat
- Red Deer
- Reindeer
- Roach
- Rockfish/Wolffish
- Roe Deer
- Russian Hamster
- Sea Bream
- Seabass
- Sharpsnout Seabream
- Sheep/Ovine
- Snake
- Snake
- Snipe
- Sole
- Sparrow
- Spider
- Starling
- Sturgeon
- Swan
- Syrian Hamster
- Tench
- Tiger
- Tortoise
- Trout
- Turbot
- Turtle
- Turtle Dove
- Vole
- Wild Boar
- Wild Cat
- Wolf
- Zebra
Update a Patient
Update Patient Request
curl -X POST https://api.truepill.com/v1/patient/c8d36d \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
-d ssn='123456789' \
-d communications_opt_in=true \
-d company='Gamma Inc.' \
-d street1='123 Some Lane' \
-d street2='Apt. 123' \
-d city='Los Angeles' \
-d state='CA' \
-d country='US' \
-d zip='94402' \
-d phone='430-304-3949' \
-d email='hulkout@hulk.com' \
-d language_preference ='English'
const body = {
first_name: 'Bruce',
last_name: 'Banner',
gender: 'male',
dob: '19691218',
street1: '123 Some Lane',
street2: 'Apt. 123',
city: 'Los Angeles',
state: 'CA',
country: 'US',
zip: '94402',
phone: '430-304-3949',
email: 'hulkout@hulk.com',
language_preference: 'English',
viewed_notice_of_privacy_practices: true,
viewed_notice_of_privacy_practices_date: '20220101'
}
fetch('https://api.truepill.com/v1/patient/c8d36d', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"patient_token": "c8d36d",
"timestamp": 1628788977,
"status": "success",
"details": {
"message": "Accepted: Patient c8d36d has been updated"
}
}
Error Response - Restricted Fields
{
"statusCode": 400,
"error": "Bad Request",
"validation_errors": [
{
"key": "last_name",
"message": "is not allowed"
},
{
"key": "gender",
"message": "is not allowed"
},
{
"key": "dob",
"message": "is not allowed"
}
]
}
POST https://api.truepill.com/v1/patient/{patient_token}
This endpoint updates a patient record in the Truepill ecosystem.
Upon a successful request, the endpoint returns the patient_token
of the patient updated, the timestamp, the status, and a message.
Only non-required fields can be updated. Submitting a patient's first name, last name, date of birth, or gender as a field to be updated will be considered a bad request.
Update Patient Body Fields
Field Name | Type | Description and Example | Required? |
---|---|---|---|
ssn | String | Social Security Number, 123456789 |
No |
communications_opt_in | Boolean | Communications opt in? | No |
id_image | String | URL for image of user ID | No |
ssn_serial | String | Social Security Number (last 4 digits), 3654 |
No |
mbi | String | Medicare Beneficiary ID, 1EG4TE5MK73 |
No |
zip | String | Patient’s zip code | No |
company | String | Name of company associated with patient (if applicable) | No |
street1 | String | Street 1 of patient’s address | No |
street2 | String | Street 2 of patient’s address (if applicable) | No |
city | String | City of patient’s address | No |
state | String | State of patient’s address, two-letter abbreviation | No |
phone | String | Patient’s phone number | No |
String | Patient’s email address | No | |
language_preference | String | Patient’s preferred language: English or Spanish |
No |
viewed_notice_of_privacy_practices | Boolean | Received Truepill’s Notice of Privacy Practices? | No |
viewed_notice_of_privacy_practices_date | String | If viewed_notice_of_privacy_practices is true , in YYYYMMDD format, the default value is date of API request |
No |
Get a Patient
Get Patient Request
curl --request GET \
--url https://api.truepill.com/v1/patient/6ce427
--header 'authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
fetch('https://api.truepill.com/v1/patient/6ce427', {
method: 'GET',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"first_name": "Bruce",
"last_name": "Banner",
"guardian": "John",
"gender": "male",
"dob": "19691218",
"mbi": "1EG4TE5MK73",
"address": {
"name": "Bruce Banner",
"street1": "123 Some Lane",
"street2": "Apt. 123",
"city": "Los Angeles",
"state": "CA",
"zip": "94402",
"company": null,
"country": "US",
"phone": "430-304-3949",
"email": "hulkout@hulk.com",
"communications_opt_in": true
},
"patient_token": "4526d90a"
}
Error Response - Patient Not Found
{
"statusCode": 404,
"error": "Not Found",
"message": "Unable to find Patient."
}
Patient of Different Customer
{
"statusCode": 400,
"error": "Unauthorized",
"message": "Patient does not belong to this customer."
}
GET https://api.truepill.com/v1/patient/{patient_token}
Once a patient has been created in the Truepill ecosystem, you can access the patient information at any time using the patient_token
that was provided on the Create Patient response.
If the patient_token
does not map to a patient record, a 404 Not Found
will be returned.
Find a Patient
Find Patient Request
curl --request GET \
--url https://api.truepill.com/v1/patient?\
first_name=Bruce&\
last_name=Banner&\
gender=male&\
dob=19691218&\
zip=94402\
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
fetch(
'https://api.truepill.com/v1/patient?first_name=Bruce&last_name=Banner&dob=19691218&gender=male',
{
method: 'GET',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
}
}
)
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"first_name": "Bruce",
"last_name": "Banner",
"guardian": "John",
"gender": "male",
"dob": "19691218",
"communications_opt_in": true,
"patient_token": "4526d90a",
"species": "Dog"
}
Error Response - Patient Not Found
{
"statusCode": 404,
"error": "Not Found",
"message": "Unable to find Patient."
}
GET https://api.truepill.com/v1/patient?
While the Get Patient endpoint requires a patient_token
to retrieve information, you can also retrieve patient information without a patient_token
, using the Find Patient endpoint.
Search for patient information by appending the following param fields onto the API endpoint, separated with an &
:
Find Patient Params
Field Name | Type | Description and Example | Required? |
---|---|---|---|
first_name | String | Legal patient first name | Yes |
last_name | String | Legal patient last name | Yes |
dob | String | Legal patient date of birth, YYYYMMDD format | Yes |
gender | String | Assigned gender at birth: male or female |
Yes |
zip | String | Patient’s zip code | Yes |
Get Patient Prescriptions
Get Patient Prescriptions Request
curl --request GET \
--url https://api.truepill.com/v1/patient/4526d90a/prescriptions\
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
fetch('https://api.truepill.com/v1/patient/4526d90a/prescriptions', {
method: 'GET',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"patient_token": "4526d90a",
"prescriptions": [
{
"prescription_token": "5ee24e",
"medication_name": "Tafluprost",
"medication_sig": "Wake up at midnight, take then.",
"prescriber": "Dr. Bruce Banner",
"date_written": "2020-02-05T00:00:00.000Z",
"refills_remaining": 1,
"current_rx_status_text": "On Hold",
"fillable": true,
"days_supply": "90",
"is_refill": 1,
"last_filled_date": "2020-04-08T11:00:00.000Z",
"expiration_date_utc": "2021-03-31T11:00:00.000Z",
"number_of_refills_allowed": 3,
"prescribed_brand_name": "Zioptan",
"prescribed_drug_strength": "40 mg",
"prescribed_generic_name": "Tafluprost 40 mg tablet",
"prescribed_ndc": "555555555555",
"prescribed_quantity": 90,
"prescribed_written_name": "Tafluprost 40 Mg Tablet",
"prescriber_npi": "12345678",
"quantity_remaining": 270,
"refills_remaining": 3,
"rx_number": "1144477",
"origin": "5",
"prescriber_order_number": "AE1234",
"original_prescribed_ndc": null,
"date_filled_utc": "2020-04-08T11:00:00.000Z",
"medication_id": "5352bb3b-2aa8-4712-8c01-83883d7cf51f",
"prescribed_quantity_unit": "EA"
},
{
"prescription_token": "7ahb3v",
"medication_name": "Luthera",
"medication_sig": "Take one Tablet by mouth at the same time daily",
"prescriber": "Dr. Strange",
"date_written": "2020-02-05T00:00:00.000Z",
"refills_remaining": 0,
"current_rx_status_text": "Transferred",
"fillable": false,
"days_supply": "90",
"is_refill": 1,
"last_filled_date": "2020-04-08T11:00:00.000Z",
"expiration_date_utc": "2021-03-31T11:00:00.000Z",
"number_of_refills_allowed": 3,
"prescribed_brand_name": "Zioptan",
"prescribed_drug_strength": "40 mg",
"prescribed_generic_name": "Luthera 20 mg tablet",
"prescribed_ndc": "555555555556",
"prescribed_quantity": 90,
"prescribed_written_name": "Luthera 20 Mg Tablet",
"prescriber_npi": "12342678",
"quantity_remaining": 270,
"refills_remaining": 3,
"rx_number": "1144478",
"origin": "5",
"prescriber_order_number": "AE1214",
"original_prescribed_ndc": null,
"date_filled_utc": "2020-04-08T11:00:00.000Z",
"medication_id": "5352bb3b-2aa8-4712-8c01-82883d7cd51f",
"prescribed_quantity_unit": "EA"
}
]
}
Error Response - Patient Not Found
{
"statusCode": 404,
"error": "Not Found",
"message": "Unable to find Patient."
}
GET https://api.truepill.com/v1/patient/{patient_token}/prescriptions
Retrieve the list of patient's prescriptions which includes the prescription token, medication name, medication sig, prescriber, date written, refills remaining, current prescription status, and the fillable status.
Patient's prescriptions must already exist in the Truepill ecosystem in order to be retrieved.
Patient's Prescription Fields Returned
Field Name | Type | Description and Example |
---|---|---|
prescription_token | String | Token to reference the prescription |
fillable | Boolean | Is this prescription fillable? (has not expired, been transferred-out, etc.) |
is_refill | Boolean | Is this prescription a refill? (1 is true, 0 is false) |
medication_name | String | Name of medication prescribed |
rx_number | String | Internal number referencing this prescription |
medication_id | String | Internal GUID referencing this prescription's GPI |
origin | String | Value representing origin of prescription |
prescribed_brand_name | String | Brand name of medication prescribed |
prescribed_drug_strength | String | Drug strength of medication prescribed |
prescribed_generic_name | String | Generic name of medication prescribed |
prescribed_written_name | String | Name of medication prescribed |
prescribed_quantity | Integer | Quantity of medication prescribed |
prescribed_quantity_unit | String | Unit the quantity of medication prescribed is counted in |
prescribed_ndc | String | NDC of medication prescribed |
original_prescribed_ndc | String | NDC of prescribed medication as originally written on eScript (if applicable) |
medication_sig | String | Instructions for taking medication |
prescriber | String | Name of prescriber |
prescriber_npi | String | NPI of prescriber |
prescriber_order_number | String | Order number written by prescriber |
date_written | String | When the prescription was written |
date_filled_utc | String | When the prescription was filled in UTC |
last_filled_date | String | When the prescription was filled |
expiration_date_utc | String | When the prescription expires in UTC |
days_supply | String | Number of days supplied on this prescription |
number_of_refills_allowed | Integer | Number of refills allowed on this prescription |
refills_remaining | Integer | Number of refills on this prescription |
quantity_remaining | Integer | Quantity left on this prescription |
Prescription
Send a Prescription
A valid prescription is required to dispense and ship medications to your patient.
There are 3 different ways for Truepill to obtain a valid prescription described below. Depending on your specific use case, you can navigate down to the appropriate section for your pharmacy fulfillment needs.
Electronic Prescriptions
A licensed US provider sends an electronic prescription or eRx (from within an EMR) into a Truepill pharmacy. This can be one of your own providers, one of ours, or a third-party provider.
Transfer Prescriptions
Your patient has a valid prescription at another pharmacy (i.e. Rite-Aid, Walgreens, CVS) and you provide instructions to Truepill to obtain and transfer this prescription to our pharmacy.
Direct Transfer Prescriptions
You have your own dispensing or non-dispensing pharmacy and want Truepill to ship medications to your patient. This is a programmatic option to transfer a prescription from your pharmacy to ours.
Transfers vs. Direct Transfers
In the Truepill ecosystem, transfers and direct transfers are two different flows albeit sharing certain similarities. A key difference is that a direct transfer is used when you own or operate the pharmacy that holds the prescription. Thus, think of a direct transfer as a programmatic transfer of a prescription between two trusted pharmacy entities — your pharmacy and ours.
Notify Rx Webhook Events
When a prescription is received and processed by Truepill, we will provide a webhook event with the text NOTIFY_RX
in the callback_type
field.
The Notify Rx webhook event will contain the prescription_token
to reference the prescription when making Fill and Copay requests.
Notify Rx webhook events can be retrieved and re-processed using the Get Webhook Events endpoint.
Notify Rx Webhook Event
{
"timestamp": 1581019462,
"callback_type": "NOTIFY_RX",
"details": {
"medication_name": "Atorvastatin 40 mg tablet",
"prescriber": "Dr. Strange",
"prescription_token": "z3q2jr",
"patient_token": "4526d90a",
"transfer_prescription_token": "z3q2jr23",
"location": "Hayward, CA"
}
}
Notify Rx Webhook Event Fields
Field Name | Type | Description |
---|---|---|
prescription_token | String | Associated prescription's token |
patient_token | String | Associated patient's token |
transfer_prescription_token | String | New prescription token created when an Rx has been transferred. Store this number to ensure you this token for future requests. Not present on all Rx notify events, only when the Rx has been transferred and a new Rx is created. The original token should be saved for association but will be discontinued. |
medication_name | String | Medication name on prescription |
prescriber | String | Name of the prescribing doctor |
location | String | The pharmacy's city name and state |
Get a Prescription
Get Prescription Request
curl --request GET \
--url https://api.truepill.com/v1/prescription/3e0ad68b28e0 \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
fetch('https://api.truepill.com/v1/prescription/0910788a5ea3', {
method: 'GET',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
}
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"prescription": {
"date_written": "2020-02-05T00:00:00.000Z",
"expiration_date": "2021-02-05T00:06:00.000Z",
"days_supply": "84",
"is_refill": 0,
"last_filled_date": null,
"medication_sig": "Take one Tablet by mouth at the same time daily",
"number_of_refills_allowed": 0,
"origin": "Electronic",
"prescribed_brand_name": "Lutera (28)",
"prescribed_drug_strength": "0.1 mg-20 mcg",
"prescribed_generic_name": "levonorgestrel-ethinyl estradiol 0.1 mg-20 mcg tablet",
"prescribed_ndc": "51862002806",
"prescribed_quantity": 84,
"prescribed_written_name": "Lutera-28 Tablet",
"prescriber": "Dr. Strange",
"prescriber_address": {
"name": "Dr. Strange",
"company": null,
"street1": "12345 Avengers Rd",
"street2": null,
"city": "San Francisco",
"state": "CA",
"zip": "94402",
"country": "US",
"phone": "(800) 888-8888",
"email": "dr.strange@avengers.com"
},
"prescriber_npi": "1639349256",
"prescriber_order_number": "11111111",
"quantity_remaining": 0,
"refills_remaining": 0,
"rx_number": "1966785",
"prescription_token": "z3q2jr",
"notes": "prescription notes",
"icd_codes": {
"icd10": ["Z30.09"],
"icd9": ["N94.6"]
},
"is_daw": false,
"fillable": true,
"dea_schedule": 0,
"original_prescribed_ndc": "43547041110",
"date_filled_utc": "2020-07-30T20:08:55.000Z",
"prescribed_quantity_unit": "EA",
"formulary": {
"on_formulary": true,
"formulary_ndc": "51862002806"
}
}
}
Error Response - Prescription Not Found
{
"statusCode": 404,
"error": "Not Found",
"message": "Unable to find Prescription."
}
GET https://api.truepill.com/v1/prescription/{prescription_token}
Once a specific prescription is in the Truepill ecosystem — either via eRx, Direct Transfer, or Transfer — the prescription information can be retrieved at any time through an API request.
This endpoint requires a prescription_token
. You will receive a prescription_token
through one of the following scenarios:
- A Notify-Rx callback which is sent when a prescription is received by the pharmacy through SureScripts.
- A Direct Transfer callback which is sent when a Direct Transfer has been successfully processed.
- A Transfer callback which is sent when a Transfer has been successfully processed.
Prescription Fields Returned
Field Name | Type | Description and Example |
---|---|---|
prescription_token | String | Token to reference the prescription |
rx_number | String | Rx number of prescription |
fillable | Boolean | Is this prescription fillable? (has not expired, been transferred-out, etc.) |
prescribed_brand_name | String | Name of medication prescribed |
prescribed_generic_name | String | Name of generic medication prescribed |
prescribed_ndc | String | NDC of prescribed medication |
prescribed_quantity | Integer | Quantity of prescribed medication |
prescribed_written_name | String | Name of medication prescribed as written |
prescribed_drug_strength | String | Drug strength prescribed |
medication_sig | String | Instructions for taking medication |
days_supply | String | Number of days the medication covers |
date_written | String | When the prescribed was written |
expiration_date | String | When the prescription will expire |
refills_remaining | Integer | Number of refills on this prescription |
quantity_remaining | Integer | Quantity of doses remaining on prescription |
is_refill | Boolean | Is prescription a refill or new fill? |
last_filled_date | String | When prescription was last filled (null if not) |
date_filled_utc | String | When prescription was last filled (null if not) in UTC |
number_of_refills_allowed | Integer | Number of refills allowed for prescription |
prescriber | String | Name of prescriber |
prescriber_address | Object | Object containing Prescriber Address information |
prescriber_npi | String | NPI of prescriber |
prescriber_order_number | String | Prescriber order number of escript |
notes | String | Prescription notes associated with Rx |
icd_codes | Object | Object containing ICD Information associated with Rx |
origin | String | Original source of prescription |
is_daw | Boolean | Is prescription dispense-as-written (null if historical Rx) |
dea_schedule | Integer | Controlled Substance Act drug schedule |
original_prescribed_ndc | String | NDC of prescribed medication as originally written on eScript (if applicable) |
prescribed_quantity_unit | String | Unit the quantity of medication prescribed is counted in |
formulary | Object | Object containing Formulary information associated with the Rx |
Prescriber Address Fields
Field Name | Type | Description and Example |
---|---|---|
name | String | Name of prescriber |
company | String | Clinic name (if available) |
street1 | String | Street 1 of prescribing clinic address |
street2 | String | Street 2 of prescribing clinic address (if applicable) |
city | String | City of prescribing clinic address |
state | Integer | State of prescribing clinic address |
zip | String | Zip code of prescribing clinic address |
country | String | "US" |
phone | String | Prescriber/clinic phone contact information |
String | Prescriber/clinic email contact information |
ICD Codes Fields
Field Name | Type | Description and Example |
---|---|---|
icd10 | Array (String) | Array of ICD10 codes associated with the prescription |
icd9 | Array (String) | Array of ICD9 codes associated with the prescription |
Formulary
Field Name | Type | Description and Example |
---|---|---|
on_formulary | Boolean | Whether or not the prescribed_ndc is on the formulary |
formulary_ndc | String or Null | The NDC found on the formulary for the prescribed_ndc (if found on the formulary) |
Electronic Prescription
An electronic prescription (eRx) is the computer-based electronic generation, transmission, and filing of a prescription. In the US, the accepted standard for eRx is the “SCRIPT standard,” governed by the National Council for Prescription Drug Programs (NCPDP).
A licensed US provider can write a new prescription to Truepill pharmacy over the Surescripts network. Once the prescription is received in our system, we will notify you using a Notify Rx webhook event confirming receipt of your patient’s prescription.
Notify Rx Webhook Event
{
"timestamp": 1581019462,
"callback_type": "NOTIFY_RX",
"details": {
"medication_name": "Atorvastatin 40 mg tablet",
"prescriber": "Dr. Strange",
"prescription_token": "z3q2jr",
"patient_token": "4526d90a",
"transfer_prescription_token": "z3q2jr23",
"location": "Hayward, CA"
}
}
Matching a Prescription to Your Patient
Matching the incoming electronic prescription relies on a number of fields including provider name, address, clinic name, medication, patient name, patient date of birth, patient address, and patient phone taken directly from the electronic prescription.
Once the prescription has been successfully matched to your patient, we generate a prescription_token
, which is a tokenized representation of the Prescription object.
Transfer a Prescription
A “transfer” (as it’s commonly referred to in the pharmacy industry) is a pharmacy-to-pharmacy exchange of the prescription between a third-party pharmacy and a Truepill pharmacy. This transfer is typically initiated by the pharmacy requesting the prescription.
In simple terms, your patient has a prescription at Rite-Aid, Walgreens, CVS and you’d like to transfer that patient’s prescription to Truepill.
In the Truepill API, the prescription transfer is initiated by you on behalf of your patient, who has opted in to receiving their prescription via a home delivery option like Truepill.
Once the prescription has been transferred, you receive a Transfer webhook event notifying you of the prescription(s) successfully transferred into our pharmacy.
Create a Transfer
Create Transfer Request for Multiple Prescriptions with Pharmacy Details
curl -X POST https://api.truepill.com/v1/transfer_request \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
-d patient_token= "4526d90a" \
-d pharmacy_name="Walmart Pharmacy" \
-d pharmacy_phone="3018897765" \
-d pharamcy_fax="3018897765" \
-d notes="transfer notes"
const body = {
patient_token: '4526d90a',
pharmacy_name: 'Walmart Pharmacy',
pharmacy_phone: '(949) 837-0504',
pharmacy_fax: '(949) 837-0504',
medication_name: ['Finasteride, 1 mg', 'Sucralfate'],
metadata: 'cfe146',
notes: 'transfer notes'
}
fetch('https://api.truepill.com/v1/transfer_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"request_id": "transfer_request_68e47e32ba93db638259",
"timestamp": 1564608647,
"status": "success",
"details": {
"message": "Your transfer request has been received.",
"transfer_token": "d36889c10dcf",
"transfer_medications": [
{
"transfer_medication_token": "1bbda354e8c7",
"medication_name": "Finasteride, 1 mg"
},
{
"transfer_medication_token": "ea52a1392697",
"medication_name": "Sucralfate"
}
],
"patient_token": "4526d90a"
}
}
POST https://api.truepill.com/v1/transfer_request
A transfer request can be created using our transfer_request
API endpoint. Truepill will provide a receipt confirmation of the request, but please note the subsequent webhook event notifying you of a successful transfer may take 1-3 days.
The following endpoint requests the transfer of a prescription from a third-party pharmacy to Truepill pharmacy. If the prescription in question was generated by a physician contracted by the API user, then this endpoint does not need to be called; otherwise, this request is necessary for the Fill request to be fulfilled.
Request Fields
Field Name | Type | Description and Example | Required? |
---|---|---|---|
patient_token | String | Token to reference Patient record | Yes |
pharmacy_name | String | Name of pharmacy to transfer prescription(s) from | See Note |
pharmacy_phone | String | Pharmacy’s phone number | See Note |
prescriber_name | String | Name of prescriber on prescription | See Note |
prescriber_phone | String | Prescriber’s phone number | See Note |
pharmacy_fax | String | Pharmacy’s fax number | No |
prescriber_fax | String | Prescriber’s fax number | No |
medications | Array | List of prescription(s) to transfer to Truepill ["Sprintec Tablet", "Spironolactone 10mg tablet"] |
No |
metadata | String | Customer-side identifier to reference the transfer in customer system | No |
notes | String | Additional transfer notes to specify | No |
Transfer Webhook Events
Notify Rx Webhook Event
{
"timestamp": 1590784899,
"callback_type": "NOTIFY_RX",
"details": {
"medication_name": "Bupropion Hcl Xl 300 Mg Tablet",
"prescriber": "Dr. P. Scribe",
"prescription_token": "z3q2jr",
"patient_token": "4526d90a",
"location": "Hayward, CA"
}
}
Successful Transfer Webhook Event
{
"request_id": "transfer_request_9a813a5a8782d15923da",
"timestamp": 1564611968,
"callback_type": "TRANSFER",
"status": "success",
"details": {
"metadata": "cfe146",
"message": "Here is a list of medications that were successfully transferred",
"patient_token": "4526d90a",
"medications": [
{
"transfer_medication_token": "6c34dacasdeb49",
"requested_medication_name": "Bupropion XL",
"last_filled_date": "No Data",
"prescription_token": "z3q2jr",
"prescriber": "Dr. P. Scribe",
"medication_name": "Bupropion Hcl Xl 300 Mg Tablet",
"medication_sig": "Take one daily.",
"num_refills_remaining": 1,
"quantity": 150,
"days_supply": 30,
"dea_schedule": 0
}
]
}
}
Error Transfer Webhook Event
{
"request_id": "transfer_request_c91f2af0a847271bdc0b",
"status": "error",
"callback_type": "TRANSFER",
"timestamp": 1502304584,
"details": {
"metadata": "cfe146",
"message": "No medications were able to be transferred",
"patient_token": "4526d90a"
}
}
Transfer webhook events are sent on the completion of a prescription transfer with the text TRANSFER
in the callback_type
field and, like with other webhook events, the status
field indicating whether or not it was successful.
In a successful transfer, you will receive a Notify Rx webhook event for each prescription that is transferred to Truepill, along with a transfer webhook event that contains a detailed list of the transferred medications in the medications
field.
Successful Transfer Webhook Event Fields
Field Name | Type | Description and Example |
---|---|---|
patient_token | String | Associated patient's URL token |
medications | Array of Medications objects | Rx information |
metadata | String | Customer-side identifier to reference the transfer in customer system |
message | String | Plain English status text |
Medications
The medications
field returns an array of objects that contain the following fields:
Field Name | Type | Description and Example |
---|---|---|
prescription_token | String | Token used for looking up an Rx |
medication_name | String | Medication name |
requested_medication_name | String | Requested medication name |
quantity | Integer | Quantity prescribed |
days_supply | Integer | Number of days supply |
num_refills_remaining | Integer | Total refills remaining on Rx |
last_filled_date | Integer | Last filled date of Rx |
transfer_medication_token | String | Token of requested medication on transfer |
dea_schedule | Integer | Controlled Substances Act drug schedule |
Transfer Error Codes
Each rejection webhook event contains an error code denoting the type of error in the error_code
field. These codes are accompanied by a text description detailing the error in the description
field.
If there is additional information that can accompany the error code and description, it will be provided in the message
field. This occurs on certain rejections such as 'Other Reason' (rejection specifics).
Table of Error Codes & Associated Information
Code | Description | Message (Additional Information) |
---|---|---|
RX_DOSAGE_MISMATCH | Dosage doesn't match prescription | N/A |
RX_FORMULA_MISMATCH | Formulation doesn't match prescription | N/A |
RX_NO_REFILLS | No refills remaining | N/A |
RX_NONEXISTANT | Prescription doesn't exist at specified pharmacy | N/A |
RX_EXPIRED | Prescription has expired | N/A |
RX_IS_DAW | Prescription is dispense as written for brand | N/A |
PATIENT_RECORD_NONEXISTANT | No patient record at pharmacy | N/A |
PATIENT_CANCELLED_RX | Patient cancellation request | N/A |
PATIENT_INFO_MISMATCH | Patient information doesn't match prescription | N/A |
PATIENT_CONTACT_REQUESTED | Pharmacy/prescriber requesting patient contact | N/A |
PHARMACY_NO_RESPONSE | Pharmacy did not respond after 6 days | N/A |
PHARMACY_DECLINED | Pharmacy refuses transfer | N/A |
PRESCRIBER_DECLINED | Prescriber declined to provide prescription | N/A |
PRESCRIBER_NO_RESPONSE | Prescriber did not respond after 6 days | N/A |
TRANSFER_DUPLICATE | Duplicate transfer | N/A |
TRANSFER_CONTACT_INFO_INCORRECT | Incorrect pharmacy/prescriber contact information | N/A |
TRANSFER_OTHER_REASON | Other reason | Rejection specifics |
List of Failures
There are a number of reasons why a Transfer request may fail. A full list of rejections for transfers is:
- Dosage doesn’t match prescription
- Duplicate transfer
- Formulation doesn’t match prescription
- Incorrect pharmacy/prescriber contact information
- No patient record at pharmacy
- No refills remaining
- Patient cancellation request
- Patient information doesn’t match prescription
- Patient requested qty higher than prescribed
- Pharmacy did not respond after 6 days
- Pharmacy refuses transfer
- Pharmacy/prescriber requesting patient contact
- Prescriber declined to provide prescription
- Prescriber did not respond after 6 days
- Prescription doesn’t exist at specified pharmacy
- Prescription has expired
- Prescription is dispense as written for brand
- Others
Transfer Contact Webhook Events
Successful Transfer Contact Webhook Event
{
"request_id": "transfer_request_9a813a5a8782d15923da",
"timestamp": 1564611968,
"callback_type": "TRANSFER_CONTACT",
"status": "success",
"details": {
"metadata": "cfe146",
"message": "A transfer contact was successfully made",
"patient_token": "4526d90a",
"transfer_token": "59222e5807",
"contact_name": "Walmart",
"contact_method": "fax",
"contact_number": "6235474583"
}
}
Error Transfer Contact Webhook Event
{
"request_id": "transfer_request_9a813a5a8782d15923da",
"timestamp": 1564611968,
"callback_type": "TRANSFER_CONTACT",
"status": "error",
"details": {
"error_code": "RX_NO_REFILLS",
"metadata": "cfe146",
"transfer_token": "59222e5807",
"message": "No refills remaining",
}
}
Transfer Contact webhook events are sent when a transfer's pharmacies/doctors are contacted via phone or fax. The webhook event has the TRANSFER_CONTACT
in the callback_type
field and, like with other webhook events, the status
field indicating whether or not it was successful.
Successful Transfer Contact Webhook Event Fields
Field Name | Type | Description and Example |
---|---|---|
patient_token | String | Associated patient's URL token |
transfer_token | String | Associated transfer's URL token |
contact_name | String | The contacted pharmacy/doctor's name |
contact_method | String | The contact method: Fax or Phone |
contact_number | String | The contact's fax or phone number |
metadata | String | Customer-side identifier to reference the transfer in customer system |
message | String | Plain English status text |
Common Failures
There are the following situations that a Transfer Contact request may fail:
- Transfer is not in
pending
status - Transfer contact method is not supported
Transfer a Prescription from a Provider
As you can see above the two fields we require for a pharmacy-to-pharmacy transfer are the name and phone number of the pharmacy. Alternatively, you can also “transfer” a prescription from a doctor's office which means instead of reaching out to the pharmacy, Truepill will reach out to the patient’s doctor to request a new prescription to Truepill.
In this scenario, you would pass in the provider’s name and phone number into the Transfer request.
List Transfers
List Transfers Request
curl -X GET https://api.truepill.com/v1/transfer_request \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
fetch('https://api.truepill.com/v1/transfer_request', {
method: 'GET',
headers: {
'Authorization': 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
})
.then(response => response.json())
.then(response => console.log(response))
Using Pagination on List Transfers Request
curl -X GET https://api.truepill.com/v1/transfer_request?page=2 \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
fetch('https://api.truepill.com/v1/transfer_request?page=2', {
method: 'GET',
headers: {
'Authorization': 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
[
{
"created_at": "2019-05-09T19:35:49.000Z",
"url_token": "582ee42c9537",
"status": "rejected",
"transfer_medications": [
{
"url_token": "15b79ebc94fb",
"medication_name": "Thing1"
},
{
"url_token": "867712a0f21c",
"medication_name": "Thing 3 400MG"
}
]
},
{
"created_at": "2019-05-30T20:54:02.000Z",
"url_token": "74d8f1424291",
"status": "rejected",
"transfer_medications": [
{
"url_token": "f6ab259d253d",
"medication_name": "Thing1"
},
{
"url_token": "35563b59d80d",
"medication_name": "Thing 3 400MG"
}
]
}
]
Response When Pagination Value Surpasses Number of Transfers in the System
[]
GET https://api.truepill.com/v1/transfer_request
This endpoint retrieves a list of all the transfer requests you have made to the Truepill ecosystem.
List transfers utilizes an optional pagination functionality when retrieving a large number of transfers. By default, this endpoint retrieves 50 transfers at a time, starting with the earliest transfers.
For example, if you were looking to retrieve the 70-80th transfers made to Truepill, you would use a pagination of 1 (zero base indexing).
To paginate, append a ?
at the end of the API endpoint along with the page=[PAGE_NUMBER]
, and replace [PAGE_NUMBER]
with an integer.
If the pagination value surpasses the number of transfers in the system, an empty array []
will be returned.
Query Params
Field Name | Type | Description and Example | Required? |
---|---|---|---|
page | Integer | 5 'page' of transfers to receive. Zero-based indexing |
No |
Get a Transfer
Get Transfer Request
curl -X GET https://api.truepill.com/v1/transfer_request/98asdf0a9sd \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
fetch('https://api.truepill.com/v1/transfer_request/98asdf0a9sd', {
method: 'GET',
headers: {
'Authorization': 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
[
{
"created_at": "2019-05-29T21:14:11.000Z",
"url_token": "0b8341246895",
"status": "completed",
"cancel_reason": null,
"cancel_reason_other": null,
"pharmacy_name": "Walmart Pharmacy",
"pharmacy_phone": "(704) 982-8948",
"prescriber_name": "",
"prescriber_phone": "",
"notes": "Medication: ",
"metadata": "cfe146",
"transfer_medications": [
{
"url_token": "10cb9171ee0c",
"rejection_reason": null,
"rejection_reason_other": null,
"medication_name": "Prednisone",
"prescription": {
"num_refills_remaining": 5,
"medication_name": "Prednisone",
"prescription_date": null,
"prescriber": null,
"last_filled_date": "2019-05-23",
"url_token": null,
"days_supply": "30",
"num_refills_filled": "0",
"prescribed_quantity": 60,
"prescribed_written_name": "prednisone 5 mg tablet",
"prescribed_generic_name": "prednisone 5 mg tablet"
}
}
],
"messages": []
}
]
Error Response - Transfer Not Found
{
"statusCode": 404,
"error": "Not Found",
"message": "Transfer not found."
}
GET https://api.truepill.com/v1/transfer_request/{transfer_token}
Once a transfer has been created in the Truepill ecosystem, you can access the transfer information at any time using the transfer_token
that was provided on the Create Transfer response.
If the transfer_token
does not map to a transfer record, a 404 Not Found
will be returned.
Direct Transfer a Prescription
A direct transfer is a pharmacy-to-pharmacy transfer of the prescription between your pharmacy and a Truepill pharmacy. This method works best for customers that operate their own pharmacies and are looking for a programmatic way to transfer a prescription. This approach does however require a digital copy of the original prescription.
And similar to a traditional transfer request, there are required fields related to the pharmacist transferring out the prescription, and the pharmacist transferring in the prescription.
Create a Direct Transfer
Direct Transfer Request
curl -X POST https://api.truepill.com/v1/direct_transfer \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
--data '{
"prescriber": {
"first_name": "Stephen",
"last_name": "Strange",
"npi": "123123123",
"prescriber_type": "OD",
"address": {
"name": "Stephen Strange",
"street1": "123 Some Lane",
"city": "San Mateo",
"state": "CA",
"zip": "94538"
}
},
"patient_token: "4526d90a",
"transfer_from": {
"name": "Walmart Pharmacy",
"address": {
"name": "",
"street1": "123 Some Lane",
"city": "San Mateo",
"state": "CA",
"zip": "94538"
},
"id_number": 490382308,
"pharmacist": "Dr. Storm"
},
"transfer_to": {
"name": "Truepill",
"id_number": 490382377,
"pharmacist": "Dr. Strange"
},
"prescription": {
"medication_name": "Finasteride",
"quantity_written": "60",
"days_supply": 30,
"quantity_dispensed": "60",
"medication_sig": "Apply Daily.",
"written_date": "20190101",
"expiration_date": "20191231"
"last_fill_date": "20190201",
"first_fill_date": "20190115",
"fills_left": 5,
"fills_transferred": 5,
"number": "4567",
"can_substitute": true,
"direct_transfer_url": "https://user:securelogin@www.assets.com/rx/saijhofiasjfoasoi2f.png",
"prescribed_ndc": "12345678912",
"icd10_code": "G43.909",
"notes": "A note here",
"diagnosis": "Male pattern baldness"
},
"metadata": "5fc6c6"
}'
const body = {
prescriber: {
first_name: 'Stephen',
last_name: 'Strange',
npi: '123123123',
prescriber_type: 'OD',
address: {
name: 'Stephen Strange Practice',
street1: '123 Some Lane',
city: 'San Mateo',
state: 'CA',
zip: '94538'
}
},
patient_token: '4526d90a',
transfer_from: {
name: 'Walmart Pharmacy',
address: {
name: 'Walmart Pharmacy',
street1: '123 Some Lane',
city: 'San Mateo',
state: 'CA',
zip: '94538'
},
id_number: '490382308',
pharmacist: 'Dr. Storm'
},
transfer_to: {
name: 'Truepill',
id_number: '1295182590',
pharmacist: 'Quynh Do'
},
prescription: {
medication_name: 'Finasteride',
prescribed_ndc: '12345678912',
days_supply: 30,
quantity_written: '60',
quantity_dispensed: '60',
medication_sig: 'Apply Daily.',
written_date: '20190101',
expiration_date: '20191231',
last_fill_date: '20190201',
first_fill_date: '20190115',
fills_left: 5,
fills_transferred: 5,
number: '4567',
can_substitute: true,
direct_transfer_url:
'https://user:securelogin@www.assets.com/rx/saijhofiasjfoasoi2f.png',
icd10_code: 'G43.909',
notes: 'A note here',
diagnosis: 'Male pattern baldness'
},
metadata: '5fc6c6'
}
fetch('https://api.truepill.com/v1/direct_transfer', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"request_id": "5a9a79a446f5d554",
"timestamp": 1559580965,
"status": "success",
"details": {
"direct_transfer_id": "c8a73a55dc"
}
}
POST https://api.truepill.com/v1/direct_transfer
This endpoint requests the transfer of a prescription from your pharmacy and a Truepill pharmacy. We will provide a receipt confirmation of the request, but please note the subsequent webhook event notifying you of a successful transfer may take 1-3 days.
Request Fields
Field Name | Type | Description and Example | Required? |
---|---|---|---|
patient_token | String | Token to reference Patient record | Yes |
prescriber | Prescriber | Prescriber object | Yes |
transfer_from | TransferFrom | Transfer From object | Yes |
transfer_to | TransferTo | Transfer To object | Yes |
prescription | Prescription | Prescription object | Yes |
metadata | String | Field to provide internal identifiers for additional reference. This field does not mutate | No |
Prescriber
Field Name | Type | Description and Example | Required? |
---|---|---|---|
first_name | String | Prescriber's first name | Yes |
last_name | Prescriber | Prescriber's last name | Yes |
address | Address | Address object | Yes |
npi | String | Prescriber's NPI | Yes |
prescriber_type | String | Prescriber's type. Supported values: OD , PMHNP , MBBS , DNP , D.O. , DPT , D.D.S. , F.N.P. , CPP , N.D. , P.A. , APNP , V.M.D. , RPh , APRN , DC APC , PsyD , CRNA , PharmD , B.V.M.S. , WHNP , PhD , ARNP , PT , CRNP , DPM , CNP , N.P. , CDH , D.M.D. , D.V.M. , M.D. , CNM |
No |
Transfer From
Field Name | Type | Description and Example | Required? |
---|---|---|---|
name | String | Name of pharmacy to transfer prescription(s) from | Yes |
address | Address | Address object | Yes |
id_number | String | Pharmacy NPI | Yes |
pharmacist | String | Pharmacist's name | Yes |
Transfer To
This object must match Truepill's records. Contact us for more details.
Field Name | Type | Description and Example | Required? |
---|---|---|---|
name | String | Truepill |
Yes |
id_number | String | Truepill Pharmacy NPI: 1295182590 by default |
Yes |
pharmacist | String | Name of Truepill pharmacist in charge: Quynh Do |
Yes |
Prescription
Field Name | Type | Description and Example | Required? |
---|---|---|---|
medication_name | String | Medication name on prescription | Yes |
prescribed_ndc | String | NDC as prescribed | Yes |
days_supply | Integer | Day supply of prescription | Yes |
quantity_written | String | Quantity prescribed | Yes |
quantity_dispensed | String | Quantity dispensed so far on prescription | Yes |
medication_sig | String | Prescription usage instructions | Yes |
fills_left | Integer | Number of fills remaining on the prescription | Yes |
fills_transferred | Integer | Number of fills being transferred to Truepill | Yes |
number | String | 12321341 Rx number of prescription at outbound Pharmacy |
Yes |
can_substitute | Boolean | false if prescription is dispense as written (DAW) |
Yes |
written_date | String | Written date of prescription, YYYYMMDD format: 19840123 |
Yes |
original_refills | Integer | Number of refills originally prescribed by provider | Yes |
quantity_transferred | String | Quantity of prescription being transferred. Best used for partial-fill prescriptions | No |
expiration_date | String | Expiration date of prescription, YYYYMMDD format: 19840123 |
No |
direct_transfer_url | String | URL to digital copy of prescription. Note: Make sure it's a valid URL | No |
last_fill_date | String | Date of prescription’s last fill, YYYYMMDD format 19840123 |
No |
first_fill_date | String | Date of prescription’s first fill, YYYYMMDD format 19840123 |
No |
icd10_code | String | Diagnosis code for patient G43.909 |
No |
notes | String | Additional details to accompany request | No |
diagnosis | String | Patient diagnosis as it relates to prescription Male pattern baldness |
No |
Address
Field Name | Type | Description and Example | Required? |
---|---|---|---|
name | String | Name of clinic or pharmacy | Yes |
street1 | String | Street 1 of address | Yes |
city | String | City of address | Yes |
state | String | State of address, two-letter abbreviation | Yes |
zip | String | Zip code of address | Yes |
company | String | Customer's name | No |
street2 | String | Street 2 of address (if applicable) | No |
phone | String | Phone number of clinic or pharmacy 5035558923 |
No |
String | Patient’s email address | No |
Direct Transfer Webhook Events
Notify Rx Webhook Event
{
"timestamp": 1590784899,
"callback_type": "NOTIFY_RX",
"details": {
"medication_name": "Bupropion Hcl Xl 300 Mg Tablet",
"prescriber": "Dr. P. Scribe",
"prescription_token": "z3q2jr",
"patient_token": "4526d90a",
"location": "Hayward, CA"
}
}
Successful Direct Transfer Webhook Event
{
"request_id": "9a813a5a8782d15923da",
"timestamp": 1564611968,
"callback_type": "DIRECT_TRANSFER",
"status": "success",
"details": {
"metadata": "cfe146",
"message": "Direct Transfer Accepted.",
"patient_token": "4526d90a",
"direct_transfer_token": "dff0a98124",
"prescription_token": "z3q2jr"
}
}
Error Direct Transfer Webhook Event
{
"request_id": "c91f2af0a847271bdc0b",
"status": "error",
"callback_type": "DIRECT_TRANSFER",
"timestamp": 1502304584,
"details": {
"metadata": "cfe146",
"message": "Direct Transfer Rejected. duplicate",
"patient_token": "4526d90a",
"direct_transfer_token": "9e6d606fva"
}
}
You will receive a Notify Rx webhook event for each prescription that is transferred to Truepill.
After a Direct Transfer request has been successfully completed, you will receive a Notify Rx webhook event for the prescription transferred to Truepill, along with a Direct Transfer webhook event. This will contain the prescription_token
to utilize the prescription within Truepill.
If a Direct Transfer is unable to be successfully processed, only an error Direct Transfer webhook event will be sent.
Direct Transfer webhook events are sent with text DIRECT_TRANSFER
in the callback_type
field and, like with other webhook events, the status
field indicating whether or not it was successful.
Success Direct Transfer Webhook Event Fields
Field Name | Type | Description and Example |
---|---|---|
prescription_token | String | Associated prescription token if accepted |
patient_token | String | Associated patient's token |
metadata | String | Customer-side identifier to reference the Fill request in customer system |
message | String | Plain English status text |
direct_transfer_token | String | Associated direct transfer token |
Fill Request
Overview
Conceptually, a Fill request is just a set of instructions you are providing to Truepill related to a patient order. In addition to the product(s) being dispensed you will also provide details like shipping address, custom packaging requirements, OTC bundled products, and anything else needed to achieve your desired patient experience.
Truepill will provide a receipt confirmation of the request, and several subsequent webhook events throughout the life cycle of the order.
Create a Fill Request
Create Fill Request Containing Multiple Insurances, both Medications and OTC Items
curl -X POST https://api.truepill.com/v1/fill_request \
-H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json" \
-d '{"patient_token": "4526d90a",
"patient_payment_type": "insurance",
"insurances": [
{
"insurance_token": "19sienglo92831n5"
},
],
"medications": [
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873",
}
],
"otc_products": [
{
"sku": "EXAMPLESKU001",
"quantity": 30
}
],
"address_to_name": "Bruce Banner",
"address_to_company": "Avengers",
"address_to_street1": "1700 S Amphlett Blvd",
"address_to_street2": "#221",
"address_to_city": "San Mateo",
"address_to_state": "CA",
"address_to_zip": "94402",
"address_to_country": "US",
"address_to_phone": "(347) 610-8896",
"address_to_email": "bruce.banner@avengers.com",
"communications_opt_in": true,
"shipping_method": "usps_priority",
"signature_confirmation": false,
"replacement_order": "fill_request_cb619ca2e133d37daefc",
"metadata": "cfe146",
"notes": "Here are some special instructions on how to package this order",
"patient_survey": {
"allergies": "Penicillian",
"medications": "Tafluprost",
"conditions": "Glaucoma",
"smoking_frequency": "N/A",
"drinking_frequency": "One drink nightly",
"bleeding_clotting_disorder": true,
"thyroid_disorder": false,
"events":[
{
"year":"2019",
"type":"hospitalization",
"reason":"food poisoning"
},
{
"year":"2018",
"type":"surgery",
"reason":"glaucoma treatment"
}
]
}
}'
const body = {
patient_token: '4526d90a',
patient_payment_type: 'insurance',
insurances: [
{
insurance_token: '19sienglo92831n5'
},
{
cardholder_id: '112233445566',
rx_bin: '172020',
pcn: 'HDMI',
rx_group: '444555'
}
],
medications: [
{
prescription_token: 'z3q2jr'
},
{
prescription_token: '3cs873'
}
],
otc_products: [
{
sku: 'EXAMPLESKU001',
quantity: 30
}
],
address_to_name: 'Bruce Banner',
address_to_company: 'Avengers',
address_to_street1: '1700 S Amphlett Blvd',
address_to_street2: '#221',
address_to_city: 'San Mateo',
address_to_state: 'CA',
address_to_zip: '94402',
address_to_country: 'US',
address_to_phone: '(347) 610-8896',
address_to_email: 'bruce.banner@avengers.com',
shipping_method: 'usps_priority',
signature_confirmation: false,
replacement_order: 'fill_request_cb619ca2e133d37daefc',
metadata: 'cfe146',
notes: 'Here are some special instructions on how to package this order',
patient_survey: {
medications: 'Tafluprost',
allergies: 'Penicillian',
conditions: 'Glaucoma'
}
}
fetch('https://api.truepill.com/v1/fill_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"request_id": "fill_request_bd6825a9d66a49b3d7a7",
"timestamp": 1592183925,
"status": "success",
"details": {
"message": "Your fill request has been processed successfully.",
"metadata": "cfe146"
}
}
Error Response - Missing Fields
{
"statusCode": 400,
"error": "Bad Request",
"validation_errors": [
{
"key": "address_to_name",
"message": "is required"
},
{
"key": "address_to_street1",
"message": "is required"
},
{
"key": "address_to_city",
"message": "is required"
},
{
"key": "address_to_state",
"message": "is required"
},
{
"key": "patient_survey",
"message": "is required"
}
]
}
POST https://api.truepill.com/v1/fill_request
This endpoint generates a Fill request to fill/refill prescriptions and order over-the-counter products. The prescriptions and products requested can be shipped to your patient with various shipping methods.
When making a Fill request, the patient will be referenced with a patient_token
being passed into the request body. If you do not have a patient_token
for your patient, one can be created using the Patient Create endpoint.
On a successful submission of the Fill request, a fill request token will be provided that is used to reference the Fill request (similar to prescription_token
and patient_token
).
This attribute is returned under the request_id
field.
Fill Request Body Fields
Field Name | Type | Description and Example | Required? |
---|---|---|---|
patient_token | String | Token to reference Patient record upon Patient Creation 4526d90a |
Yes |
patient_payment_type | String | Patient’s payment method: cash or insurance |
Yes |
insurances | Array | Array of Insurance objects Required if patient_payment_type is set to insurance |
See Description |
medications | Array | Array of Medications objects to fill | See Description |
otc_products | Array | Array of OTC objects to fill. Request must include either medications or otc_products |
See Description |
address_to_name | String | Patient’s name as it should appear on shipping label | Yes |
address_to_street1 | String | Street 1 of patient’s shipping address | Yes |
address_to_city | String | City of patient’s shipping address | Yes |
address_to_state | String | State of patient’s shipping address | Yes |
address_to_zip | String | Zip code of patient’s shipping address | Yes |
address_to_phone | String | Patient's phone number | Yes |
patient_survey | JSON | Required information on patient's current health. See Patient Survey section for details | Yes |
address_to_company | String | ABC Inc. Desired return name to display on package shipping label sent to patient |
No |
address_from_company | String | Desired name to display in the Return section of shipping label | No |
address_to_street2 | String | Street 2 of patient's shipping address (if applicable) | No |
address_to_email | String | Patient's email | No |
metadata | String | Customer-side identifier to reference the Fill request in customer system | No |
shipping_method | String | One of the following: usps_priority ,usps_ground_advantage ,usps_priority_express ,fedex_2_day ,fedex_ground ,fedex_smart_post ,fedex_standard_overnight ,fedex_priority_overnight ,ups_ground ,ups_next_day_air ,ups_second_day_air Defaults to usps_ground_advantage |
No |
signature_confirmation | Boolean | true if signature should be required by patient upon delivery; false otherwise |
No |
notes | String | Additional information customer wishes to convey relating to this Fill request | No |
medication_packaging_type | String | standard vial , custom vial custom bottle single dose pouch multi-dose pouches Multi-dose packaging options |
No |
is_custom_order | Boolean | Set to true for custom orders only. Contact Truepill for more details |
No |
is_priority | Boolean | Please contact your Truepill representative to disussing ability to submit orders with priority status. | No |
packaging_instructions | String | Specify details of your packaging process for a specific order (Limit 40 characters). Custom packaging | No |
packaging_materials | Array | Array of Packing Material objects to fill. | No |
replacement_order | String | fill_request_cb619ca2e133d37daefc Fill Request token of the order that this Fill request is replacing |
No |
check_in | Boolean | false : Set to true to request a consultation with a Truepill pharmacist prior to completing the Fill request. Patient Check-In |
No |
Insurances
Fill Request Body with Insurance
{
"patient_token": "4526d90a",
"patient_payment_type": "insurance",
"insurances": [
{
"insurance_token": "19sienglo92831n5"
}
],
"medications": [
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873"
}
],
["...other fields..."]
}
The insurances
field accepts an array of objects with the following fields:
Field Name | Type | Description and Example | Required? |
---|---|---|---|
insurance_token | String | Token to reference a patient's insurance Required if cardholder_id and rx_bin are not provided |
See Description |
cardholder_id | String | A9321328 Member ID number on insurance cardRequired if insurance_token is not provided |
See Description |
rx_bin | String | 997928 Rx BIN on card, always 6 charactersRequired if insurance_token is not provided |
See Description |
rx_group | String | 006726 Rx group on insurance card |
No |
pcn | String | AXA Member ID number on insurance card |
No |
phone_number | String | (955) 372-4143 Insurance provider phone number |
No |
insurance_card_image_url | String | http://imageurl.jpg Used to manually troubleshoot any claims issues |
No |
Fill Request Medications
Using Prescription Tokens with Fill Request
{
"patient_token": "4526d90a",
"patient_payment_type": "cash",
"medications": [
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873"
}
],
["...other fields..."]
}
The medications
field accepts an array of objects with the following field.
When providing the prescription_token
only, we will attempt to dispense exactly what was prescribed by the doctor.
You can also control the quantity dispensed on a fill. See Refills for more information.
Field Name | Type | Description and Example | Required? |
---|---|---|---|
prescription_token | String | Token to reference exact prescription. See the Prescription section for more details | Yes |
Patient Check-In
Indicating Patient Check-In on Fill Request
{
"patient_token": "4526d90a",
"patient_payment_type": "insurance",
"insurances": [
{
"insurance_token": "19sienglo92831n5"
}
],
"medications": [
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873"
}
],
"check_in": true,
["...other fields..."]
}
Patient check-in is available should the patient want to discuss with a pharmacist before dispensing on a refill. Before sending us a refill for an existing patient you must ask them the following questions:
- Have you started taking any new medication?
- Have you experienced any new allergies?
- Have you experienced any side effects?
- Have you been in the hospital or experienced transitions of care?
- Have you started using another pharmacy since the last fill?
- Do you believe the medication is effective?
If your patient wishes to have a consultation with a pharmacist you must either provide them with our phone number or set the check_in
field to true
on their next Fill request. Although the responses to these questions are not required, our pharmacists expect API Users to use good faith determination on whether or not to provide our pharmacists with responses in order to help facilitate a patient's treatment.
By setting the check_in
field to true
, a Truepill pharmacist will reach out to your patient for a consultation before the Fill request is processed.
Patient Survey
Fill Request with No Patient Survey Information to Report
curl -X POST https://api.truepill.com/v1/fill_request \
-H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json" \
-d '{"patient_token": "4526d90a",
"patient_payment_type": "cash",
"medications": [
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873",
}
],
"patient_survey": {
"allergies": null,
"medications": null,
"conditions": null,
},
[...other fields...]
}'
const body = {
patient_token: '4526d90a',
patient_payment_type: 'cash',
medications: [
{
prescription_token: 'z3q2jr'
},
{
prescription_token: '3cs873'
}
],
patient_survey: {
medications: null,
allergies: null,
conditions: null
},
[...other fields...]
}
fetch('https://api.truepill.com/v1/fill_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Fill Request with Patient Survey Information to Report
curl -X POST https://api.truepill.com/v1/fill_request \
-H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json" \
-d '{"patient_token": "4526d90a",
"patient_payment_type": "cash",
"medications": [
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873",
}
],
"patient_survey": {
"allergies": null,
"medications": null,
"conditions": null,
"events":[
{
"year":"2019",
"type":"hospitalization",
"reason":"food poisoning"
},
{
"year":"2018",
"type":"surgery",
"reason":"glaucoma treatment"
}
]
},
"weight": {
"value": "64.55",
"unit: "oz",
},
[...other fields...]
}'
const body = {
patient_token: '4526d90a',
patient_payment_type: 'cash',
medications: [
{
prescription_token: 'z3q2jr'
},
{
prescription_token: '3cs873'
}
],
patient_survey: {
medications: "Glaucoma",
allergies: "Bimatoprost",
conditions: "Hay Fever",
events: [
{
year: '2019',
type: 'hospitalization',
reason: 'food poisoning'
},
{
year: '2018',
type: 'surgery',
reason: 'glaucoma treatment'
}
]
},
weight: {
value: '64.55',
unit: 'oz',
},
[...other fields...]
}
fetch('https://api.truepill.com/v1/fill_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
As part of being a URAC-accredited pharmacy, you are required to collect specific patient safety details for every Fill request you submit. This includes current medications, allergies, and health conditions.
This can be provided in the patient_survey
field on the Fill request.
A Fill request for a patient without a completed survey will return a successful response initially, but once the order is processed it will be rejected. You will receive a webhook event detailing the rejection reason.
The survey consists of a series of questions about pre-existing conditions, current medications, allergies, hospitalization incidents, smoking frequency, drinking frequency, and several true or false questions. The more information you provide, the better we can serve you and your patients. However, we understand in many cases there is no information to report. In this case, we only require you to send the fields: conditions
, medications
, and allergies
with the null
value. We recommend a UI interaction for the patient to interact with to indicate none.
Field Name | Type | Description and Example | Required? |
---|---|---|---|
conditions | String or null | Glaucoma Any pre-existing conditions not listed below |
Yes |
medications | Array [JSON] or String or null | See below. Other medications prescribed to the patient | Yes |
allergies | String or null | Hay Fever Any allergies this patient has |
Yes |
events | Array [JSON] or String | See Events below. Details surgery or hospitalization events | No |
smoking_frequency | String | N/A The frequency of smoking, if any. |
No |
drinking_frequency | String | One drink nightly The frequency of drinking, if any |
No |
asthma_breathing | Boolean | false Whether the patient has asthma or breathing problems |
No |
heart_disease | Boolean | false Whether the patient has heart disease |
No |
arthritis | Boolean | false Whether the patient has arthritis |
No |
lung_disorder | Boolean | false Whether the patient has a lung disorder |
No |
bleeding_clotting_disorder | Boolean | true Whether the patient has a bleeding/clotting disorder |
No |
neurological_chronic_headaches | Boolean | false Whether the patient has neurological disorders or chronic headaches |
No |
blood_transfusion | Boolean | false Whether the patient has had a blood transfusion |
No |
psychiatric_disorder | Boolean | false Whether the patient has a psychiatric disorder |
No |
bowel_stomach | Boolean | false Whether the patient has bowel/stomach problems |
No |
pulmonary_embolism | Boolean | false Whether the patient has had a pulmonary embolism |
No |
cancer | Boolean | false Whether the patient has had cancer |
No |
stroke | Boolean | false Whether the patient has had a stroke |
No |
cholesterol_disorder | Boolean | false Whether the patient has a cholesterol disorder |
No |
seizure_epilepsy | Boolean | false Whether the patient has seizures or epilepsy |
No |
diabetes | Boolean | false Whether the patient has diabetes |
No |
thyroid_disorder | Boolean | false Whether the patient has a thyroid disorder |
No |
eye_disorder | Boolean | true Whether the patient has an eye disorder |
No |
urinary_kidney_disorder | Boolean | true Whether the patient has a urinary/kidney disorder |
No |
pregnancy | Boolean | true Whether the patient is pregnant or not |
No |
weight | Object | See Weight below. Details about pet's weight | No |
Events Fields
If you choose to provide the patient response in more detail than a freeform text field, the format we expect for the events information is below.
Field Name | Type | Description and Example | Required? |
---|---|---|---|
type | String | surgery The type of event, either surgery or hospitalization |
Yes |
year | Integer or Null | 2018 The year of incidence |
Yes |
reason | String or Null | glaucoma treatment The reason for the event |
Yes |
Medications Fields
Fill Request Body with Expanded Patient Survey Medication Information
{
"patient_token": "4526d90a",
"patient_payment_type": "cash",
"medications": [
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873"
}
],
"patient_survey": {
"medications": [
{
"name": "Sildenafil",
"strength": 20,
"dosage": "mg",
"frequency": "Daily"
}
],
"allergies": "Bimatoprost",
"conditions": "Hay Fever",
},
["...other fields..."]
}
If you choose to provide the patient response in more detail than a freeform text field, the format we expect for the other medications field is below. In the medication name
field, include the length of time the patient has been taking the medication. Additionally, you may provide any over-the-counter medications or herbal supplements which may interfere with medical treatment through these same fields.
Field Name | Type | Description and Example | Required? |
---|---|---|---|
name | String | Tafluprost The name of the medication |
Yes |
strength | Number | 0.05 The strength of the medication |
Yes |
dosage | String | mg/ml The unit of the strength |
Yes |
frequency | String | Daily The frequency of medication use |
Yes |
Weight Fields
If you choose to provide the pet details, the format we expect for the weight information is below.
Field Name | Type | Description and Example | Required? |
---|---|---|---|
value | Float | 64.55 The value of weight |
No |
unit | String | oz The unit of weight |
No |
Fill Request Webhook Events
Successful Order Webhook Event with both Dispensed and Rejected Medications
// Note that this completed order has one medication that was unable to be filled
{
"request_id": "fill_request_0fbbde7492c8b024d800",
"timestamp": 1571251314,
"callback_type": "ORDER",
"status": "success",
"details": {
"metadata": "cfe146",
"message": "Your fill request was processed and is pending shipment.",
"date_filled": "Mon, 01 Jun 2020 17:45:06 GMT",
"order_token": "b392d",
"medications": [
{
"quantity": 14,
"medication_name": "Metronidazole 500 mg oral tablet",
"dispensed_medication_name": "Metronidazole 500 mg oral tablet",
"original_requested_prescription_token": "c8226924vf1a",
"days_supply": 7,
"requested_medication_name": "Metronidazole 500 mg oral tablet",
"medication_token": "310ca0fa",
"dispensed_ndc": "1234567890",
"remaining_refills": {
"total_remaining_refills": 0,
"total_quantity_remaining": 0
},
"fill_number": "0",
"rx_number": "1484947",
"total_refills_allowed": 3,
"prescription_token": "z3q2jr",
"patient_cash_amount": null
},
{
"quantity": 14,
"medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
"dispensed_medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
"original_requested_prescription_token": "bas8292xd",
"days_supply": 7,
"requested_medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
or "medication_token": "5d466090",
"remaining_refills": {
"total_remaining_refills": 0,
"total_quantity_remaining": 0
},
"fill_number": "0",
"rx_number": "1483253",
"total_refills_allowed": 3,
"prescription_token": "3cs873",
"patient_cash_amount": null
},
{
"requested_medication_name": "Fluconazole 150 mg oral tablet",
"reject_reason": "Refill too soon",
"medication_token": "7ebc894e"
}
],
"otc_products": [
{
"sku": "TPIBPN20",
"quantity_ordered": 5
}
],
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=92001902453595000012688153",
"tracking_number": "92001902453595000012688153",
"carrier": "usps",
"location": "Hayward, CA",
"patient_token": "4526d90a"
}
}
Error Order Webhook Event - No Refills Remaining
// No additional information required/accompanying this rejection reason
{
"request_id": "fill_request_2c069215483bb6676a9b",
"status": "error",
"timestamp": 1585608018,
"callback_type": "ORDER",
"details": {
"metadata": "cfe146",
"error_code": "NR",
"description": "Rejected: No Refills Remaining",
"message": null,
"order_token": "b392d",
"medications": [
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873"
}
],
"otc_products": [
{
"sku": "TPIBPN20",
"quantity_ordered": 5
}
],
}
}
Error Order Webhook Event - High Copay
// Rejection reason along with specified copay amount
{
"request_id": "fill_request_2c069215483bb6676a9b",
"status": "error",
"timestamp": 1585608018,
"callback_type": "ORDER",
"details": {
"metadata": "cfe146",
"error_code": "R009",
"description": "Rejected: High Copay",
"message": "$87.49",
"order_token": "b392d",
"medications": [
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873"
}
]
}
}
Upon receiving a Fill request, the Truepill pharmacy gets to work on running a claim with the patient’s insurance, reviewing the patient and the prescription, and packaging the prescription for delivery.
When an order is successfully processed and packaged, the order is deemed “completed” and is awaiting delivery to the patient. A success webhook event notification will be sent to the customer as well as three additional Shipment webhook events as the order journeys to the patient address.
If an issue occurs during processing that prevents the prescription from being filled and packaged, the Fill request may be rejected. In this case, an error webhook event will be sent to the customer detailing the rejection of the Fill request.
If an order is blocked by an extraneous circumstance, but is believed to be resolved soon, the order may be moved to a triage
status. A webhook event notification will be sent for Triaged Orders as well.
Successful Fill Request Webhook Event Fields
Field Name | Type | Description and Example |
---|---|---|
order_token | String | Associated order's URL token |
patient_token | String | Associated patient's URL token |
medications | Array of Medications | Array of Medication details |
otc_products | Array of OTC Products | Array of OTC item details |
tracking_url | String | URL to be used for carrier tracking |
tracking_number | String | Carrier Tracking number |
carrier | String | Carrier |
metadata | String | Provided by customer |
date_filled | String | Filled date of Rx |
location | String | Location where the order was filled |
message | String | Plain English status text |
Medication
A successfully filled Medications object is as follows:
Field Name | Type | Description and Example |
---|---|---|
prescription_token | String | Token used for looking up an Rx |
medication_name | String | Medication name |
requested_medication_name | String | Requested medication name |
dispensed_medication_name | String | Dispensed (substitution) medication name |
original_requested_prescription_token | String | Original prescription token (if applicable) |
rx_number | String | Rx number of prescription |
patient_copay_amount | Integer | Patient amount paid if insurance order |
patient_cash_amount | Integer | Patient amount paid if cash order |
days_supply | Integer | Number of days supply |
quantity | Integer | Quantity sent |
fill_number | String | Prescription refill No. (0 is first fill) |
remaining_refills | Remaining Refills | Rx information |
total_refills_allowed | Integer | Number of refills allowed |
medication_token | String | Associated token for the prescription request |
dispensed_ndc | String | NDC of the medication dispensed |
A rejected Medications object is as follows:
Field Name | Type | Description and Example |
---|---|---|
error_code | String | Error code for rejection |
reject_reason | String | Reason details for medication rejection |
requested_medication_name | String | Requested medication name |
medication_token | String | Associated token for the prescription request |
OTC Products
An OTC product object is as follows:
Field Name | Type | Description and Example |
---|---|---|
item_name | String | Item name of OTC item as specified on Fill request |
sku | String | SKU of OTC item as specified on Fill request |
quantity_requested | Integer | Requested quantity of product |
Remaining Refills
Field Name | Type | Description and Example |
---|---|---|
total_remaining_refills | Integer | Total refills remaining on Rx |
total_quantity_remaining | Integer | Total quantity across all refills on Rx |
Error Webhook Event Fields
Field Name | Type | Description and Example |
---|---|---|
order_token | String | Associated order's URL token |
description | String | Rejection reason |
message | String | Additional information regarding rejection, if possible — otherwise null |
medications | Array | Array of objects containing prescription token (if available) |
metadata | String | Provided by customer |
error_code | String | Error Codes |
Order Error Codes
Each rejection webhook event contains an error code denoting the type of error in the error_code
field. These codes are accompanied by a text description detailing the error in the description
field.
If there is additional information that can accompany the error code and description, it will be provided in the message
field. This occurs on certain rejections such as 'Refill Too Early' (date of refill eligibility), 'High Copay' (copay amount), or 'Other Reason' (rejection specifics).
Table of Error Codes & Associated Information
Code | Description | Message (Additional Information) |
---|---|---|
R2 | Bad Address Details | N/A |
12 | Bad Insurance Details | Will contain at least one of the following: 'Missing/Invalid Group Number', 'Missing/Invalid PCN', 'Non-Matched Cardholder ID', 'Missing/Invalid DOB' |
R004 | Coverage Not Effective | N/A |
R003 | Closed Network | N/A |
09 | Date of Birth Mismatch | N/A |
DI | Drug Interactions | Description of impeding drug interactions |
R1 | Duplicate Order | The order number of duplicate order |
DT | Duplicate Therapy | Description of other duplicate therapy |
R009 | High Copay | The high copay amount in question |
R010 | Mail Order Fills Exceeded | N/A |
PC | Missing eRx | N/A |
NR | No Refills Remaining | N/A |
R0 | Order Cancelled by Customer | N/A |
R005 | Order Rejected by Truepill for Customer | N/A |
R019 | Other Reason | Specifics of reason |
R3 | Out of Stock/Unavailable to Order | N/A |
62 | Patient Name Mismatch | N/A |
75 | Prior Authorization Required | N/A |
R015 | Quantity Limited by Insurance | Limited quantity information |
79 | Refill Too Early | Date of refill availability |
R4 | Returned to sender | N/A |
R022 | Sig Clarification Needed | Description of required instructions or missing instructions |
R017 | Test | N/A |
R5 | Transferred Out of Pharmacy | N/A |
R024 | Prescription Expired | N/A |
R025 | Coverage Terminated | N/A |
R026 | Quantity Mismatch | N/A |
Common Failures
Commonly found rejections for orders are:
- Coverage terminated
- Incorrect name or DOB
- Medication is not on approved formulary
- No eRx in prescription
- No refills remaining
- Non-matched cardholder ID
- Prior authorization required
- Refill too soon
- Reimbursement issue
Triage
Triaged Order Webook Event
// No additional information required/accompanying this triage webhook event
{
"request_id": "fill_request_2c069215483bb6676a9b",
"timestamp": 1585608018,
"callback_type": "ORDER",
"status": "triage",
"details": {
"metadata": "cfe146",
"message": "This order has been moved to Triage status",
"code": "T001",
"description": "Invalid Address",
"additional_information": null,
"order_token": "b392d",
"medications": [
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873"
}
]
}
}
// Triage webhook event along with additional information
{
"request_id": "fill_request_2c069215483bb6676a9b",
"timestamp": 1585608018,
"callback_type": "ORDER",
"status": "triage",
"details": {
"metadata": "cfe146",
"message": "This order has been moved to Triage status",
"code": "T005",
"description": "Out of Stock",
"additional_information": "2020-04-12",
"order_token": "b392d",
"medications": [
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873"
}
]
},
}
Certain orders may be blocked from being processed further due to external dependencies, but can be resolved in a timely manner. These orders are moved into the triage
status to be identified quickly, and triaged by proper personnel.
A webhook event will be sent to the customer when an order is moved to the triage
status. Similarly to the Order Error Rejection webhook event, the Triage webhook event contains a code denoting the triage reason in the code
field. These codes are accompanied by a text description detailing the reason in the description
field.
If there is additional information that can accompany the triage code and description, it will be provided in the additional_information
field.
Table of Triage Codes & Associated Information
Code | Description | Additional Information |
---|---|---|
T001 | Invalid Address | N/A |
T003 | Prior Authorization Required | May include description of Prior Authorization |
T004 | Customer Clarification Needed | May include description of desired customer clarification |
T005 | Out of Stock | Date of stock availability |
T006 | Clinical Outreach to MD | Description/reason of clinical outreach |
T007 | Other Reason | Specifics of reason |
Shipment Webhook Events
Shipment Webhook Event - Arrival to Facility
{
"request_id": "fill_request_991e90fa6b367cf72032",
"timestamp": 1590800102,
"callback_type": "SHIPMENT",
"status": "success",
"details": {
"metadata": "cfe146",
"status": "TRANSIT",
"message": "Your shipment has arrived at the USPS regional origin facility.",
"eta": "2020-06-02T00:54:31.838Z",
"tracking_number": "43904456187100000000000000",
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000",
"carrier": "usps"
}
}
Shipment Webhook Event - Package in Transit
{
"request_id": "fill_request_991e90fa6b367cf72032",
"timestamp": 1590800162,
"callback_type": "SHIPMENT",
"status": "success",
"details": {
"metadata": "cfe146",
"status": "TRANSIT",
"message": "In Transit, Arriving On Time",
"eta": "2020-06-02T00:54:31.838Z",
"tracking_number": "43904456187100000000000000",
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000",
"carrier": "usps"
}
}
Shipment Webhook Event - Package Delivered
{
"request_id": "fill_request_991e90fa6b367cf72032",
"timestamp": 1590800222,
"callback_type": "SHIPMENT",
"status": "success",
"details": {
"metadata": "cfe146",
"status": "DELIVERED",
"message": "Your shipment has been delivered at the destination mailbox.",
"eta": "2020-06-02T00:54:31.838Z",
"tracking_number": "43904456187100000000000000",
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000",
"carrier": "usps"
}
}
When an order is successfully processed and packaged, the order is deemed “completed” and is awaiting delivery to the patient. After a successful Order webhook event is sent, additional shipment webhook events will also be sent as the order journeys to the patient address.
These callbacks will have callback_type
of SHIPMENT
.
Shipment Webhook Event Fields
Field Name | Type | Description and Example |
---|---|---|
tracking_url | String | URL to be used for carrier tracking |
tracking_number | String | Carrier tracking number |
carrier | String | Carrier |
status | String | Status of package delivery from carrier |
eta | String | ETA of package delivery to patient's address |
message | String | Text description of package delivery status from carrier |
metadata | String | Customer-side identifier to reference the Fill request in customer system |
Shipment Webhook Event Statuses
Although uncommon, it is possible to receive an error status on a Shipment webhook event. The Shipment webhook event may have one of the following status values:
Status | Definition |
---|---|
UNKNOWN | Status of shipment is unknown or unavailable |
PRE_TRANSIT | Carrier is waiting to receive shipment at designated |
TRANSIT | Shipment shipping is in progress |
DELIVERED | Shipment has been delivered to destination |
RETURNED | Shipment was returned to sender |
FAILURE | There was an issue with shipment delivery |
Refills
Fill Request with Refill Management
curl -X POST https://api.truepill.com/v1/fill_request \
-H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json" \
-d '{"patient_token": "4526d90a",
"patient_payment_type": "insurance",
"insurances": [
{
"insurance_token": "19sienglo92831n5"
},
],
"medications": [
{
"prescription_token": "z3q2jr",
"quantity": 300
},
{
"prescription_token": "3cs873",
"quantity: 15
}
],
"address_to_name": "Bruce Banner",
[...other fields...]
}'
const body = {
patient_token: '4526d90a',
patient_payment_type: 'insurance',
insurances: [
{
insurance_token: '19sienglo92831n5'
}
],
medications: [
{
prescription_token: 'z3q2jr',
quantity: 90
},
{
prescription_token: '3cs873',
quantity: 15
}
],
address_to_name: 'Bruce Banner',
[...other fields...]
}
fetch('https://api.truepill.com/v1/fill_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Order Webhook Event with Refill Management
// Note that the quantity fields in the medications array
{
"request_id": "fill_request_0fbbde7492c8b024d800",
"timestamp": 1571251314,
"callback_type": "ORDER",
"status": "success",
"details": {
"metadata": "cfe146",
"message": "Your fill request was processed and is pending shipment.",
"date_filled": "Mon, 01 Jun 2020 17:45:06 GMT",
"order_token": "b392d",
"medications": [
{
"quantity": 90,
"medication_name": "Metronidazole 500 mg oral tablet",
"dispensed_medication_name": "Metronidazole 500 mg oral tablet",
"days_supply": 7,
"requested_medication_name": "Metronidazole 500 mg oral tablet",
"medication_token": "310ca0fa",
"dispensed_ndc": "1234567890",
"remaining_refills": {
"total_remaining_refills": 0,
"total_quantity_remaining": 0
},
"fill_number": "0",
"rx_number": "1484947",
"total_refills_allowed": 3,
"prescription_token": "z3q2jr",
"patient_cash_amount": null
},
{
"quantity": 15,
"medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
"dispensed_medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
"days_supply": 7,
"requested_medication_name": "Nitrofurantoin macrocrystals-monohydrate 100 mg oral capsule",
"medication_token": "5d466090",
"remaining_refills": {
"total_remaining_refills": 0,
"total_quantity_remaining": 0
},
"fill_number": "0",
"rx_number": "1483253",
"total_refills_allowed": 3,
"prescription_token": "3cs873",
"patient_cash_amount": null
},
{
"requested_medication_name": "Fluconazole 150 mg oral tablet",
"reject_reason": "Refill too soon",
"medication_token": "7ebc894e"
}
],
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=92001902453595000012688153",
"tracking_number": "92001902453595000012688153",
"carrier": "usps",
"location": "Hayward, CA",
"patient_token": "4526d90a"
}
}
The only difference between a refill and a first fill is that this time around you already have a Patient token and Prescription token, so you are all set! Just send in a Fill request and follow the same process as before and repeat this until you have no remaining refills on a given prescription.
Managing Refill Quantities
Depending on whether your patients are paying for their prescriptions with cash or insurance, you have some control over the quantity of medication dispensed. For cash prescriptions, you can dispense multiple fills and custom quantities as needed.
A Fill request can also be partially filled as well.
To dispense multiple fills or partial fills, include the quantity
field in the medications
object.
For insurance prescriptions, the payer will determine the appropriate quantity that you can dispense to the patient. Typically, this is a 30-90 day supply of medication. In the event you request a quantity greater than allowed by the patient’s insurance, we will dispense the maximum allowable limit and send the quantity
as part of your Fill request webhook event.
Your Medications object passed in on the Fill request would look like this:
Field Name | Type | Description and Example | Required? |
---|---|---|---|
prescription_token | String | Token to reference exact prescription. See the Prescription section for more details | Yes |
quantity | Integer | Quantity to dispense | Yes (For Fill Control) |
Multi-Dose Packaging
Fill Request with Multi-Dose Packaging
curl -X POST https://api.truepill.com/v1/fill_request \
-H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json" \
-d '{"patient_token": "4526d90a",
"patient_payment_type": "cash",
"medications": [
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873"
}
],
"medication_packaging_type": "standard vial",
[...other fields...]
}'
const body = {
patient_token: '4526d90a',
patient_payment_type: 'cash',
medications: [
{
prescription_token: 'z3q2jr'
},
{
prescription_token: '3cs873'
}
],
medication_packaging_type: 'standard vial',
[...other fields...]
}
fetch('https://api.truepill.com/v1/fill_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Truepill can support a range of medication packaging types including standard vials, custom branded vials and bottles, branded single-dose pouch packaging and multi-dose strip style packaging.
You can specify the packaging type for your order using the medication_packaging_type
field.
Custom Packaging
Fill Request with Custom Packaging
curl -X POST https://api.truepill.com/v1/fill_request \
-H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json" \
-d '{"patient_token": "4526d90a",
"patient_payment_type": "cash",
"medications": [
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873"
}
],
"packaging_instructions": "promotional Vitamin B product sample",
[...other fields...]
}'
const body = {
patient_token: '4526d90a',
patient_payment_type: 'cash',
medications: [
{
prescription_token: 'z3q2jr'
},
{
prescription_token: '3cs873'
}
],
packaging_instructions: 'promotional Vitamin B product sample',
[...other fields...]
}
fetch('https://api.truepill.com/v1/fill_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Many customers provide their own packaging materials to our facilities. We can also design and procure custom packaging for you.
We can support a range of needs including different brand box types and styles, marketing collateral and inserts, new vs. existing customer packaging, new customer welcome letter, seasonal products and inserts, promotional and other brand materials, OTC product samples — just to name a few example of how our partners bring their brands to life with Truepill.
You can use the packaging_instructions
field in the Fill Request API to provide specific details of your packaging process for a specific order. This field is limited to 40 characters so it can be propagated to the shipping label.
Over-the-Counter Products
Fill Request with OTC Products
curl -X POST https://api.truepill.com/v1/fill_request \
-H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json" \
-d '{"patient_token": "4526d90a",
"patient_payment_type": "cash",
"otc_products": [
{
"sku": "EXAMPLESKU001",
"quantity": 30
}
],
[...other fields...]
}'
const body = {
patient_token: '4526d90a',
patient_payment_type: 'cash',
otc_products: [
{
sku: 'EXAMPLESKU001',
quantity: 30
}
],
[...other fields...]
}
fetch('https://api.truepill.com/v1/fill_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Fill Request with OTC Products for Guest Patient
curl -X POST https://api.truepill.com/v1/fill_request \
-H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json" \
-d '{"patient_first_name": "Tony",
"patient_last_name": "Stark",
"otc_products": [
{
"quantity": 2,
"sku": "{your sku id}"
}
],
"address_to_name": "Attn: Tony Stark",
"address_to_street1": "123 Hero Lane",
"address_to_street2": " ",
"address_to_city": "San Ramon",
"address_to_state": "CA",
"address_to_zip": "94582",
"address_to_country": "US",
"address_to_phone": "5551234555",
"address_to_company": "",
"metadata": "1245",
"shipping_method": "fedex_2_day",
"notes": "notes",
"patient_payment_type": "cash",
"patient_survey":
{
"medications": null,
"allergies": null,
"conditions": null
}
}'
const body = {
patient_first_name: 'Tony',
patient_last_name: 'Stark',
otc_products: [
{
sku: '{your sku id}',
quantity: 30
}
],
address_to_name: 'Attn: Tony Stark',
address_to_street1: '123 Hero Lane',
address_to_street2: '',
address_to_city: 'San Ramon',
address_to_state: 'CA',
address_to_zip: '94582',
address_to_country: 'US',
address_to_phone: '5551234555',
address_to_company: '',
shipping_method: 'fedex_2_day',
metadata: '1245',
notes: 'Here are some special instructions on how to package this order',
patient_payment_type: 'cash',
patient_survey: {
medications: 'null',
allergies: 'null',
conditions: 'null'
}
}
fetch('https://api.truepill.com/v1/fill_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Truepill can support a broad range of nonprescription OTC products in addition to the full formulary of prescription products.
A prescription is not required for an OTC product. Thus, you do not need to pass in a prescription_token
for an order that contains only OTC products.
Also, a patient_token
is not required for such orders and you can use guest patients, which consists of the patient_first_name
and patient_last_name
.
If a Fill request only contains OTC items, submit the patient_survey
as null
.
For Fill requests containing OTCs, populate the otc_products
field with an array of objects with the following fields:
Field Name | Type | Description and Example | Required? |
---|---|---|---|
sku | String | SKU of OTC item | See note |
item | String | Product name | See note |
quantity | Integer | Quantity requested | Yes |
days_supply | Integer | Number of days the product and quantity should cover | No |
customer_item_id | String | Customer item ID | No |
Packing Materials
Fill Request with Packing Materials
curl -X POST https://api.truepill.com/v1/fill_request \
-H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json" \
-d '{"patient_token": "4526d90a",
"patient_payment_type": "cash",
"medications": [
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873"
}
],
"packing_materials": [
{
"sku": "EXAMPLESKU001",
"quantity": 30
}
],
[...other fields...]
}'
const body = {
patient_token: '4526d90a',
patient_payment_type: 'cash',
medications: [
{
prescription_token: 'z3q2jr'
},
{
prescription_token: '3cs873'
}
],
packing_materials: [
{
"sku": "EXAMPLESKU001",
"quantity": 30
}
],
[...other fields...]
}
fetch('https://api.truepill.com/v1/fill_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
For Fill requests containing Packing Materials, populate the packing_materials
field with an array of objects with the following fields:
Field Name | Type | Description and Example | Required? |
---|---|---|---|
sku | String | Store keeping unit | Yes |
quantity | Integer | Quantity (Must be greater than 0) | Yes |
Replacing Fill Requests
Indicating a Replacement on Fill Request
curl -X POST https://api.truepill.com/v1/fill_request \
-H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json" \
-d '{"patient_token": "4526d90a",
"patient_payment_type": "insurance",
"insurances": [
{
"insurance_token": "19sienglo92831n5"
},
],
"medications": [
{
"prescription_token": "z3q2jr",
"quantity": 300
},
{
"prescription_token": "3cs873",
"quantity: 15
}
],
"replacement_order": "fill_request_cb619ca2e133d37daefc",
[...other fields...]
}'
const body = {
patient_token: '4526d90a',
patient_payment_type: 'insurance',
insurances: [
{
insurance_token: '19sienglo92831n5'
},
{
cardholder_id: '112233445566',
rx_bin: '172020',
pcn: 'HDMI',
rx_group: '444555'
}
],
medications: [
{
prescription_token: 'z3q2jr',
quantity: 90
},
{
prescription_token: '3cs873',
quantity: 15
}
],
replacement_order: 'fill_request_cb619ca2e133d37daefc',
[...other fields...]
}
fetch('https://api.truepill.com/v1/fill_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
If an order is lost or damaged on delivery, it can be replaced with a new Fill request.
When making a new Fill request to replace a previous one, include the request_id
received on the previous Fill request that the new Fill request is intended to replace.
You will receive the standard Fill request API response containing a new request_id
to use as the Fill Request token.
Get a Fill Request
Get Fill Request
curl --request GET \
--url https://api.truepill.com/v1/fill_request/fill_request_cb619ca2e133d37daefc \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
fetch(
'https://api.truepill.com/v1/fill_request/fill_request_cb619ca2e133d37daefc',
{
method: 'GET',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
}
}
)
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"patient_first_name": "Bruce",
"patient_last_name": "Banner",
"patient_dob": "19891123",
"patient_gender": "male",
"patient_payment_type": "cash",
"medication_name": "Lipitor",
"otc_products": [
{
"item": "Vitamin C",
"quantity": 1
}
],
"quantity_dispensed": 30,
"days_supply": 30,
"prescribing_doctor": "Dr. Strange",
"medication_sig": "Take 1 tablet by mouth at the same time every day.",
"refill_number": 12,
"is_refill": true,
"check_in": true,
"shipping_method": "usps_ground_advantage",
"address_from_name": "",
"address_from_company": "Avengers",
"address_from_street1": "1700 S Ampnlett Blvd",
"address_from_street2": "#221",
"address_from_city": "San Mateo",
"address_from_state": "CA",
"address_from_zip": "94402",
"address_from_country": "US",
"address_from_phone": "1-800-368-0038",
"address_from_email": "support@pharmacy.com",
"address_to_name": "Peter Parker",
"address_to_street1": "1700 S Amphlett Blvd",
"address_to_street2": "#221",
"address_to_city": "San Mateo",
"address_to_state": "CA",
"address_to_zip": "94402",
"address_to_country": "United States",
"address_to_phone": "(650) 353-5495",
"address_to_email": "pharmacy@truepill.com",
"patient_known_allergies": "Hay Fever",
"patient_other_medications": "none",
"notes": "",
"metadata": "cfe146",
"url_token":"a1b2c3",
"status": "pending",
"created_at": "2021-01-01T00:00:00.000Z",
"error_code": "R021",
"rejection_reason": "Drug Interactions",
"additional_rejection_details": "Rejected on 01/01/2021",
"triage_reason": "Missing information",
"additional_triage_details": "Need insurance information",
"tracking_url": "https://tools.usps.com/origTrackNum=111111111111111",
"carrier": "fedex"
}
GET https://api.truepill.com/v1/fill_request/{request_id}
Once a Fill request has been submitted, you can look up the request payload that was submitted at any time for reference with an API request.
This endpoint requires a request_token
. You will receive a request_token
upon a successful Fill request API submission response in the request_id
field.
Get Fill Request Webhook Events
Get Fill Request Webhook Events
curl --request GET \
--url https://api.truepill.com/v1/fill_request/fill_request_cb619ca2e133d37daefc/webhook_events \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
fetch(
'https://api.truepill.com/v1/fill_request/fill_request_cb619ca2e133d37daefc/webhook_events',
{
method: 'GET',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
}
}
)
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"results": [
{
"payload": {
"timestamp": 1628540166,
"callback_type": "ORDER",
"details": {
"metadata": "Unique Identifier of Client side",
"message": "Your fill request was processed and is pending shipment.",
"date_filled": "Mon, 01 Jan 2021 20:16:06 GMT",
"order_token": "t0k3n",
"medications": [
{
"medication_name": "Sildenafil 100 Mg Tablet",
"dispensed_medication_name": "Sildenafil 100 Mg Tablet",
"requested_medication_name": "Sildenafil Tab 100mg Torr 30@",
"original_requested_prescription_token": "pr3scr1pt10n",
"days_supply": 30,
"quantity": 6,
"fill_number": "1",
"rx_number": "1376688",
"total_refills_allowed": 5,
"prescription_token": "pr3scr1pt10n",
"medication_token": "a4024b355184",
"dispensed_ndc": "1234567890",
"remaining_refills": {
"total_remaining_refills": 4,
"total_quantity_remaining": 24
},
"rx_link": "rxl_e173b34762298c2d2c863983"
}
],
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=11111111111111111111111111",
"tracking_number": "11111111111111111111111111",
"carrier": "usps",
"location": "Hayward, CA",
"patient_token": "p4t13ntt0k3n"
}
},
"delivery_data": {
"status": "success",
"status_code": 200
}
},
{
"payload": {
"timestamp": 1628695007,
"callback_type": "SHIPMENT",
"details": {
"metadata": "Unique Identifier of Client side",
"status": "TRANSIT",
"message": "Your shipment has arrived at the USPS regional origin facility.",
"eta": "2021-01-02T04:00:00Z",
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=11111111111111111111111111",
"tracking_number": "11111111111111111111111111",
"carrier": "usps",
}
},
"delivery_data": {
"status": "success",
"status_code": 200
}
},
],
"next_page_token": null
}
GET https://api.truepill.com/v1/fill_request/{request_id}/webhook_events?{query}={operator}:{value}
This endpoint returns a list of webhook events and allows for the use of query parameters to scope the results of the request.
A request payload
represents the request's timestamp, type, and details.
A request delivery_data
represents the request's status information.
See Get Webhook Events documentation for query parameter details.
Update a Fill Request
Update Fill Request
curl -X POST https://api.truepill.com/v1/update_request \
-d api_key=tp_live_key_dwXajyzag6mhXQi1z0Gq9w \
-d request_id="fill_request_aecafb34372151077db8" \
-d address_from_company="Avengers" \
-d address_to_name="Peter Parker" \
-d address_to_company="" \
-d address_to_street1="1700 S Amphlett Blvd" \
-d address_to_street2="#221" \
-d address_to_city="San Mateo" \
-d address_to_state="CA" \
-d address_to_zip="94402" \
-d address_to_country="US" \
-d address_to_phone="(347) 610-8896" \
-d address_to_email="peter.parker@avengers.com" \
-d shipping_method="usps_priority" \
-d signature_confirmation="false" \
-d notes="Here are some special instructions on how to package this order"
const body = {
request_id: 'fill_request_aecafb34372151077db8',
address_from_company: 'Avengers',
address_to_name: 'Peter Parker',
address_to_company: '',
address_to_street1: '1700 S Amphlett Blvd',
address_to_street2: '#221',
address_to_city: 'San Mateo',
address_to_state: 'CA',
address_to_zip: '94402',
address_to_country: 'US',
address_to_phone: '(347) 610-8896',
address_to_email: 'peter.parker@avengers.com',
shipping_method: 'usps_priority',
signature_confirmation: false,
notes: 'Here are some special instructions on how to package this order'
}
fetch('https://api.truepill.com/v1/update_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"request_id": "update_request_bc22b83aeb5fc2970920",
"timestamp": 1511916806,
"status": "success",
"details": {
"message": "Accepted: Order fill_request_7fe917b47ac87a9f3c5a has been updated with the new request parameters."
}
}
Error Response
{
"timestamp": 1511913120,
"status": "error",
"message": "There was an error updating this request (fill_request_e841dbbf56e1365f69b5), either you are not the owner of the request, or the request has already been processed as either shipped or cancelled. Please contact us at (855) 910-8606 for help if neither is the case."
}
This endpoint amends the fields of an existing Fill request, such as correcting an address or changing the shipping method to expedite your order.
Request Fields
Field Name | Type | Description and Example | Required? |
---|---|---|---|
request_id | String | Fill request ID: fill_request_5c4b21b9aecaea155d67 |
Yes |
address_to_name | String | Patient’s name as it should appear on shipping label | Yes |
address_to_street1 | String | Street 1 of patient’s shipping address | Yes |
address_to_street2 | String | Street 2 of patient’s shipping address (if applicable) | Yes |
address_to_city | String | City of patient’s shipping address | Yes |
address_to_state | String | State of patient’s shipping address | Yes |
address_to_zip | String | Zip code of patient’s shipping address | Yes |
address_to_country | String | US : Use US for all requests |
Yes |
address_to_phone | String | Patient’s phone number (347) 676-9989 |
Yes |
address_to_email | String | Patient’s email address | Yes |
address_to_company | String | ABC Inc. Desired return name to display on package shipping label sent to patient |
No |
address_from_company | String | Desired name to display in the Return section of shipping label | No |
shipping_method | String | usps_priority , usps_ground_advantage , usps_priority_express , fedex_ground , fedex_standard_overnight , fedex_priority_overnight , ups_ground , ups_next_day_air , ups_second_day_air Defaults to usps_ground_advantage |
No |
signature_confirmation | Boolean | true if signature should be required by patient upon delivery; false otherwise |
No |
notes | String | Special instructions on how to package this order | No |
Cancel a Fill Request
Cancel Fill Request
curl -X POST https://api.truepill.com/v1/cancel_request \
-d api_key="ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-d request_id="fill_request_34f68f71f980f78bb0bc"
const body = {
request_id: 'fill_request_34f68f71f980f78bb0bc'
}
fetch('https://api.truepill.com/v1/cancel_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Cancel Fill Request for Specific Medications
curl -X POST https://api.truepill.com/v1/cancel_request \
-d api_key="ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-d request_id="fill_request_34f68f71f980f78bb0bc"
-d medications='[
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873"
}
]'
const body = {
request_id: 'fill_request_34f68f71f980f78bb0bc',
medications: [
{
prescription_token: 'z3q2jr'
},
{
prescription_token: '3cs873'
}
]
}
fetch('https://api.truepill.com/v1/cancel_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"request_id": "cancel_request_3a8bc280d8e959287db0",
"timestamp": 1511224340,
"status": "success",
"details": {
"code": "03",
"description": "Order Cancelled by Customer Request",
"message": "Accepted: Order fill_request_34f68f71f980f78bb0bc has been cancelled."
}
}
Error Response
{
"timestamp": 1511226167,
"status": "error",
"message": "There was an error cancelling this request, either you are not the owner of the request, or have already cancelled the request. Please contact us at (855) 910-8606 for help if neither is the case."
}
POST https://api.truepill.com/v1/cancel_request
This endpoint cancels a Fill request whose request_id
field matches the respective user-provided text parameter.
Request Fields
Field Name | Type | Description and Example | Required? |
---|---|---|---|
request_id | String | Fill request ID: fill_request_5c4b21b9aecaea155d67 |
Yes |
medications | Array | Array of Medications objects to cancel | No |
Cancelling Medications in Fill Request
Optionally, specific medications can be cancelled on the order itself rather than the entire order.
To do this, pass a medications
field on the Cancel Fill request containing one or more objects with a prescription_token
associated with the order that should be cancelled.
If the medications
array contains all the prescriptions on the order, the entire Fill request will be cancelled.
If the medications
array contains a prescription that is not associated with the specific Fill request, it will be ignored and the remaining valid prescriptions will be cancelled on the specific Fill request.
The medications
field accepts an array of objects with the following field:
Field Name | Type | Description and Example | Required? |
---|---|---|---|
prescription_token | String | Token to reference exact prescription to be cancelled. See the Prescription section for more details | Yes |
Insurance Fulfillment
Patient Consent
Fill Request with Patient Consent and Copay Payment
{
"patient_token": "571ce37390db1316",
"shipping_method": "usps_priority",
"address_to_name": "Bruce Banner",
"address_to_company": "",
"address_to_street1": "3121 Diablo Ave",
"address_to_street2": "",
"address_to_city": "Hayward",
"address_to_state": "AK",
"address_to_zip": "94545",
"address_to_country": "US",
"address_to_phone": "111-222-3333",
"address_to_email": "example@gmail.com",
"patient_payment_type": "cash",
"signature_confirmation": false,
"address_from_company": "testl",
"patient_payment_type": "insurance",
"insurances": [
{
"insurance_token": "139jdk20s3"
}
],
"patient_survey": {
"conditions": null,
"events": null,
"medications": null,
"allergies": null
},
"medications": [
{
"prescription_token": "015f4cc7b065",
"patient_consent": {
"consent_statement": "Patient Bruce Banner consented that Truepill pharmacy will bill their insurance in order to provide a fill of medication sildenafil 10mg for a quantity of 10.",
"patient_name": "Bruce Banner",
"consent_provided_by": "Bruce Banner",
"item": "sildenafil 10mg",
"consent_method": "ONLINE",
"consent_date": " 2023-02-25 15:17:51.000Z",
"consent_type": "FILL"
},
"copay_payment": {
"cardholder_name": "Bruce Banner",
"payment_type": "CARD",
"last_four_digits": "6789",
"transaction_id": "10f410zj3018s2",
"transaction_amount": 17.00
"transaction_date": "2023-02-25 15:17:51.000Z"
}
},
{
"prescription_token": "015f4cc7b066",
"patient_consent": {
"consent_statement": "Patient Bruce Banner consented that Truepill pharmacy will bill their insurance in order to provide a fill of medication metoprolol 25mg for a quantity of 30.",
"patient_name": "Bruce Banner",
"consent_provided_by": "Bruce Banner",
"item": "metoprolol 25mg",
"consent_method": "ONLINE",
"consent_date": " 2023-02-25 15:17:51.000Z",
"consent_type": "PAY_IN_CASH"
},
"copay_payment": {
"cardholder_name": "Bruce Banner",
"payment_type": "CARD",
"last_four_digits": "6789",
"transaction_id": "10f410zj3018s2",
"transaction_amount": 8.51,
"transaction_date": "2023-02-25 15:17:51.000Z"
}
}
]
}
Due to evolving requirements from PBMs that online pharmacies demonstrate active consent to fill and refill prescriptions, Truepill now requires that all prescriptions for insurance orders must be accompanied by proof of active consent.
For each prescription in the medications
array, the patient_consent
block is required as part of the Fill request payload, which will include a consent statement, name of person providing consent, patient name, item or medication name, consent method, consent type, and consent date of when the consent was provided by the patient.
For medications that are desired to be filled with billing to be processed against insurance, the consent type will be FILL
.
Patient Consent Object Fields
Field Name | Type | Description and Example | Required? |
---|---|---|---|
consent_statement | String | Statement of patient providing consent. This explicitly needs to confirm that Truepill is the pharmacy of choice. | Yes |
patient_name | String | Full legal name of the patient | Yes |
consent_provided_by | String | Full legal name of the person providing consent (must be the patient or the patient's appointed or authorized representative) | Yes |
item | String | Name of medication(s) or item(s) being requested. Include strength/dosage and quantity where possible. May include multiple medications in a text string. | Yes |
consent_method | String | One of the following: VERBAL , TEXT , ONLINE , EMAIL |
Yes |
consent_date | String | Date and time of when patient consent is given | Yes |
consent_type | String | Type of consent: FILL for insurance |
Yes |
Copay Payment Object Fields
Confirmation of copay collection can also be collected on the fill request in the copay_payment
block.
Field Name | Type | Description and Example | Required? |
---|---|---|---|
cardholder_name | String | Name on credit card. Example: Bruce Banner |
Yes |
payment_type | String | CARD only |
Yes |
last_four_digits | Integer | Last four digits on credit card that is used. Example: 1571 |
Yes |
transaction_id | String | Stripe transaction ID or similar that references a unique payment transaction. Can be provided in lieu of last_four_digits . Example: 10f410zj3018s2 |
Yes |
transaction_amount | Float | Transaction amount in dollars. Example: 23.58 |
Yes |
transaction_date | Integer | Date and time of when card transaction was processed | Yes |
Expediting Orders After Insurance Failure
In the scenario where a Fill request is rejected due to insurance-related issues, you can decide to re-submit a Fill request if either:
- Insurance resolution has been achieved with the patient.
- Patient is willing to proceed with cash.
In these circumstances, you can choose to have this Fill request prioritized in the processing queue by specifying the Fill Request token of the previously failed Fill request in the reference_order
field on the Fill request API call.
For a new Fill request to be successfully prioritized, the provided Fill Request token in the reference_order
field must match the following criteria:
- Must be a valid Fill Request token.
- Fill Request token must reference an already rejected Client order.
Failure to meet the criteria will result in the new Fill request being created without intended prioritization.
Expiring Orders and Lack of Patient Payment
Fill Request with Reference Fill Request
{
"reference_order": "fill_request_ads3fu13yoasd62yo",
"patient_token": "571ce37390db1316",
"shipping_method": "usps_priority",
"address_to_name": "Bruce Banner",
"address_to_company": "",
"address_to_street1": "3121 diablo ave",
"address_to_street2": "",
"address_to_city": "hayward",
"address_to_state": "AK",
"address_to_zip": "94545",
"address_to_country": "US",
"address_to_phone": "111-222-3333",
"address_to_email": "example@gmail.com",
"patient_payment_type": "cash",
"signature_confirmation": false,
"address_from_company": "testl",
"patient_survey": {
"conditions": null,
"events": null,
"medications": null,
"allergies": null
},
"medications": [
{
"prescription_token": "015f4cc7b065",
"patient_consent": {
"consent_statement": "Patient consented to paying the full cash cost of the medication of $56.70.",
"consent_method": "VERBAL",
"consent_type": "PAY_IN_CASH",
"consent_date": "2021-01-25 15:17:51.000Z"
},
"copay_payment": {
"cardholder_name": "Bruce Banner",
"payment_type": "CARD",
"last_four_digits": "6789",
"transaction_amount": "17.00",
"card_type": "VISA",
"transaction_date": "2021-01-25 15:17:51.000Z"
}
},
{
"prescription_token": "015f4cc7b066",
"patient_consent": {
"consent_statement": "Patient Bruce Banner consented for a fill of the following medications with copay of $47.00",
"consent_method": "VERBAL",
"consent_date": " 2021-01-25 15:17:51.000Z",
"consent_type": "COPAY"
},
"copay_payment": {
"cardholder_name": "Bruce Banner",
"payment_type": "CARD",
"last_four_digits": "6789",
"transaction_amount": "23.50",
"card_type": "VISA",
"transaction_date": "2021-01-25 15:17:51.000Z"
}
}
]
}
Patient’s insurance claims can be kept open for up to 10 days. When an insurance order is not updated with patient payment details within 10 days from receiving the Order Claim Webhook event, The patient’s insurance claim will be reversed and the order will be cancelled. An Order Error webhook event will be fired documenting this.
Error Fill Request Webhook Event
{
"request_id": "fill_request_2c069215483bb6676a9b",
"status": "error",
"timestamp": 1585608018,
"callback_type": "ORDER",
"details": {
"metadata": "cfe146",
"error_code": "R028",
"description": "Rejected: Patient Payment for Insurance Claim not Provided",
"message": "$87.49",
"order_token": "b392d",
"medications": [
{
"prescription_token": "z3q2jr"
},
{
"prescription_token": "3cs873"
}
]
}
}
Insurance Billing
Create an Insurance
Create Insurance Request
curl -X POST https://api.truepill.com/v1/insurance \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
-d patient_token ='4526d90a' \
-d insurance='{
"cardholder_id": "A9321328",
"rx_group": "006726",
"rx_bin": "997928",
"pcn": "AXA",
"relationship_code": 1,
"phone_number": "(955) 372-4143"
}'
const body = {
patient_token: '4526d90a',
insurance: {
cardholder_id: 'A9321328',
rx_group: '006726',
rx_bin: '997928',
pcn: 'AXA',
relationship_code: 1,
phone_number: '(955) 372-4143'
}
}
fetch('https://api.truepill.com/v1/insurance', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"request_id": "cnpsa8ms8vbs7f52c8y2xchd77tza3nv",
"status": "success",
"timestamp": 1560356149,
"details": {
"insurance_token": "skhsyq83rkd3uht9"
}
}
Error Response - Patient Not Found
{
"message": "Patient not found"
}
Error Response - Missing Fields
{
"statusCode": 400,
"error": "Bad Request",
"validation_errors": [
{
"key": "insurance.cardholder_id",
"message": "is required"
},
{
"key": "insurance.rx_bin",
"message": "is required"
}
]
}
POST https://api.truepill.com/v1/insurance
With a Patient created in the Truepill ecosystem, you can associate an Insurance to that patient with the Create Insurance API endpoint using the patient_token
.
Upon a successful response, an insurance_token
is provided that can be used along with the existing patient_token
for Copay and Fill requests.
Body Fields
Field Name | Type | Description and Example | Required? |
---|---|---|---|
patient_token | String | Token to reference Patient record upon Patient creation | Yes |
insurance | Object | See Insurance object fields below | Yes |
Insurance Fields
The insurance
object is required for all Insurance requests.
Field Name | Type | Description and Example | Required? |
---|---|---|---|
cardholder_id | String | A9321328 Member ID number on insurance card |
Yes |
rx_bin | String | 997928 Rx BIN on card, always 6 characters |
Yes |
rx_group | String | 006726 Rx group on insurance card |
No |
pcn | String | AXA Member ID number on insurance card |
No |
relationship_code | Number | 1 Relationship to primary cardholder (1 for Cardholder, 2 for Spouse, 3 for Child, etc) |
No |
phone_number | String | (955) 372-4143 Insurance provider phone number |
No |
insurance_card_image_url | String | http://imageurl.jpg Used to manually troubleshoot any claims issues |
No |
Get Insurance Details
Get Insurance Details Request
curl --request GET \
--url https://api.truepill.com/v1/insurance/skhsyq83rkd3uht9 \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
fetch('https://api.truepill.com/v1/insurance/skhsyq83rkd3uht9', {
method: 'GET',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
}
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"cardholder_id": "A9321328",
"rx_group": "006726",
"rx_bin": "997928",
"pcn": "AXA"
}
Error Response - Insurance Not Found
{
"statusCode": 404,
"error": "Not Found",
"message": "Unable to find Insurance."
}
GET https://api.truepill.com/v1/insurance/{insurance_token}
Once an insurance has been associated with a patient in the Truepill ecosystem, you can access the insurance information at any time using the insurance_token
that was provided on the Create an Insurance response.
Get Insurance Claim Details
Get Insurance Claim Request
curl --request GET \
--url https://api.truepill.com/v1/prescription/29djd02dndu/fill/3/claims \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
fetch(
'https://api.truepill.com/v1/prescription/29djd02dndu/fill/3/claims',
{
method: 'GET',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
}
}
)
.then(response => response.json())
.then(response => console.log(response))
Successful Response
[
{
"patient_copay_amount":2.42,
"transaction_code":"B1",
"transaction_status":"PAID",
"claim_type":"BILLING",
"transmission_date":"2023-07-16T12:41:30.000Z",
"insurance_type":"PRIMARY",
"insurance":{
"group_number":"RX881A",
"bin":"17142",
"pcn":null,
"cardholder_id": "ABC123456"
},
"payor":"Health Partners",
"payor_adjudication_amount":2.5
},
{
"patient_copay_amount":null,
"transaction_code":"B1",
"transaction_status":"REJECTED",
"claim_type":"BILLING",
"transmission_date":"2023-07-16T12:41:30.000Z",
"insurance_type":"SECONDARY",
"insurance":{
"group_number":"RX393",
"bin":"3939",
"pcn":null,
"cardholder_id": "ABC123456"
},
"payor":"Some Secondary Partner",
"payor_adjudication_amount":null,
"claim_reject_codes":[
"70",
"75"
]
},
{
"patient_copay_amount":2.42,
"transaction_code":"B2",
"transaction_status":"APPROVED",
"claim_type":"REVERSAL",
"transmission_date":"2023-07-16T12:41:30.000Z",
"insurance_type":"PRIMARY",
"insurance":{
"group":"RX881A",
"bin":"17142",
"pcn":null,
"cardholder_id": "ABC123456"
},
"payor":"Health Partners",
"payor_adjudication_amount":2.5
}
]
GET https://api.truepill.com/v1/prescription/{prescription_token}/fill/{fill_number}/claims
Given a prescription token and a fill number, the claim information associated with a prescription and that particular fill can be retrieved via API.
All claim information correlating to a specific fill is made available here, including claim rejections and reversals. Claim information is displayed in array format, with each object representing a claim record.
If a claim is rejected, NCPDP codes are also displayed for the particular claim rejection within the claim_reject_codes
field.
Claim records are displayed in chronological order. If no claim information is available for a provided prescription_token
and fill_number
, an empty array is returned.
Available fields in each Claim object:
Claim Object Fields
Field Name | Type | Description and Example |
---|---|---|
patient_copay_amount | Float | Expected patient copay amount from claim if adjudication is successful. null if claim is rejected (no copay amount) |
transaction_code | String | Adjudication transaction type. Typically B1 and B2 |
transaction_status | String | Status of claim: APPROVED , REJECTED , PAID |
claim_type | String | Insurance claim type: BILLING or REVERSAL |
transmission_date | Datetime | Transmission date of adjudication |
insurance_type | String | Patient’s insurance type: PRIMARY , SECONDARY , TERTIARY |
insurance | Object | Insurance Details |
payor | String | Payor's name |
payor_adjudication_amount | Float | Payor adjudication amount. null if claim is rejected |
claim_reject_codes | Array | Array of NCPDP error codes |
Claim Insurance Details
Field Name | Type | Description |
---|---|---|
bin | String | Insurance BIN number associated to claim |
pcn | String | Insurance PCN associated to claim |
group_number | String | Insurance group number associated to claim |
cardholder_id | String | Cardholder ID associated to claim |
Copay Request
Create a Copay Request
Copay Request with Multiple Prescriptions
curl -X POST https://api.truepill.com/v1/copay_request \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
-d patient_token='4526d90a' \
-d insurance_token='["skhsyq83rkd3uht9"]' \
-d prescriptions='[
"z3q2jr",
"3cs873",
"wz25v2"
]' \
-d metadata='cfe146' \
-d notes='This is a note' \
-d ship_to_state='CA'
const body = {
patient_token: '4526d90a',
insurance_token: ['skhsyq83rkd3uht9'],
prescriptions: ['z3q2jr', '3cs873', 'wz25v2'],
metadata: 'cfe146',
notes: 'This is a note',
ship_to_state: 'CA'
}
fetch('https://api.truepill.com/v1/copay_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"request_id": "cnpsa8ms8vbs7f52c8y2xchd77tza3nv",
"status": "success",
"timestamp": 1560356149,
"details": {
"copay_request_token": "ef6p8y6wz7x3hpng",
"copay_request_prescription_tokens": [
{
"prescription_token": "z3q2jr",
"copay_request_prescription_token": "an7hj7gp63yjhgpw",
"status": "pending"
},
{
"prescription_token": "3cs873",
"copay_request_prescription_token": "r6fjmdx6ub99kksk",
"status": "pending"
},
{
"prescription_token": "wz25v2",
"copay_request_prescription_token": "xw6m893xt7tjtybu",
"status": "pending"
}
]
}
}
POST https://api.truepill.com/v1/copay_request
This endpoint generates a Copay request to retrieve copay information on a patient's prescription(s). We can support multiple insurances on a copay request.
Body Fields
Field Name | Type | Description and Example | Required? |
---|---|---|---|
patient_token | String | Token to reference Patient record: 4526d90a |
Yes |
insurance_token | Array [String] | ["skhsyq83rkd3uht9", "ubqfc1a0a17hjb1c", "oi4aafwcsv5zzvvj"] : Submit an array of one or more insurances in priority order [Primary, Secondary, Tertiary] |
Yes |
prescriptions | Array | Can be an array of prescription tokens ["4ddy38", "b5q3t2", "h3r55c"] , or an array of Prescription objects |
Yes |
initiate_prior_auth | Boolean | true or false : Set to true to initiate an electronic PA request at the point of claim rejection |
No |
metadata | String | Customer-side identifier to reference the Copay request in customer system | No |
notes | String | Additional information customer wishes to convey relating to this Copay request | No |
ship_to_state | String | State prescription is being shipped to as 2 letter abbreviation | No |
Copay Prescription
Submitting Patient Consent, Quantity, and Days Supply on Copay Request
{
"patient_token": "571ce37390db1316",
"insurance_token": ["139jdk20s3"],
"prescriptions": [
{
"prescription_token": "015f4cc7b065",
"patient_consent": {
"consent_statement": "Patient Bruce Banner consented that Truepill pharmacy will bill their insurance in order to provide a fill of medication sildenafil 10mg for a quantity of 10.",
"consent_method": "ONLINE",
"consent_date": "2023-02-25 15:17:51.000Z",
"consent_type": "INSURANCE",
"patient_name": "Bruce Banner",
"consent_provided_by": "Bruce Banner",
"item": "sildenafil 10mg"
},
"quantity": 30,
"days_supply": 30
},
{
"prescription_token": "015f4cc7b066",
"patient_consent": {
"consent_statement": "Patient Bruce Banner consented that Truepill pharmacy will bill their insurance in order to provide a fill of medication metoprolol 25mg for a quantity of 30.",
"consent_method": "ONLINE",
"consent_date": "2023-02-25 15:17:51.000Z",
"consent_type": "INSURANCE",
"patient_name": "Bruce Banner",
"consent_provided_by": "Bruce Banner",
"item": "metoprolol 25mg"
},
"quantity": 30,
"days_supply": 30
}
]
}
The prescriptions
field on the copay request accepts an array of prescription_token
strings OR an array of objects.
Submit prescriptions
as an array of objects when providing patient consent to bill insurance, and/or if a copay check is being requested for a different quantity and/or days supply than what was prescribed.
Field Name | Type | Description and Example | Required? |
---|---|---|---|
prescription_token | String | Token to reference exact prescription | Yes |
patient_consent | Object | Patient Consent object. Use consent_type "INSURANCE" to indicate consent to bill insurance | Yes |
quantity | Number | Quantity to submit on claim, if different from prescribed quantity | No |
days_supply | Number | Days supply to submit on claim, if different from prescribed days supply | No |
Copay Request Webhook Events
Successful Copay Request Webhook Event - All Prescriptions
{
"request_id": "cnpsa8ms8vbs7f52c8y2xchd77tza3nv",
"status": "success",
"callback_type": "COPAY",
"timestamp": 1563916377515,
"details": {
"metadata": "cfe146",
"message": "Here is a list of medications that we have successfully checked the copay amounts for",
"patient_token": "4526d90a",
"prescriptions": [
{
"prescription_token": "z3q2jr",
"insurance_token": "skhsyq83rkd3uht9",
"status": "completed",
"next_fill_date": "2019-07-23T00:00:00.000Z",
"copay_amount": "21.02",
"copay_request_prescription_token": "98dagjw",
"fill_number": 1,
"days_supply": "28",
"quantity": 28,
"claims": [
{
"insurance_token": "skhsyq83rkd3uht9",
"billing_order": 1,
"status": "Paid",
"copay_amount": "21.02"
}
]
},
{
"prescription_token": "3cs873",
"insurance_token": "skhsyq83rkd3uht9",
"status": "completed",
"next_fill_date": "2019-08-05T00:00:00.000Z",
"copay_amount": "1.10",
"copay_request_prescription_token": "ad92wek",
"fill_number": 1,
"days_supply": "28",
"quantity": 28,
"claims": [
{
"insurance_token": "skhsyq83rkd3uht9",
"billing_order": 1,
"status": "Paid",
"copay_amount": "1.10"
}
]
}
]
}
}
Successful Copay Request Webhook Event with Completed & Rejected Copays
{
"request_id": "cnpsa8ms8vbs7f52c8y2xchd77tza3nv",
"status": "success",
"callback_type": "COPAY",
"timestamp": 1563916377515,
"details": {
"metadata": "cfe146",
"message": "Here is a list of medications that were checked",
"patient_token": "4526d90a",
"prescriptions": [
{
"prescription_token": "z3q2jr",
"insurance_token": "skhsyq83rkd3uht9",
"status": "rejected",
"claim_reject_codes": [
{
"code": "79",
"message": "Refill too soon"
}
],
"fill_number": 1,
"copay_request_prescription_token": "17ed9e856d5baba1",
"next_fill_date": "2020-05-10T00:00:00.000Z",
"error_code": "Refill too soon",
"claims": [
{
"insurance_token": "skhsyq83rkd3uht9",
"billing_order": 1,
"status": "Rejected",
"claim_reject_codes": [
{
"code": "79",
"message": "Refill too soon"
}
]
}
]
},
{
"prescription_token": "3cs873",
"insurance_token": "skhsyq83rkd3uht9",
"status": "completed",
"copay_request_prescription_token": "a7da36900cedbd80",
"next_fill_date": "2020-04-20T20:23:43.000Z",
"copay_amount": "0",
"fill_number": 1,
"days_supply": "90",
"quantity": 90,
"claims": [
{
"insurance_token": "skhsyq83rkd3uht9",
"billing_order": 1,
"status": "Paid",
"copay_amount": "0"
}
]
}
]
}
}
Successful Copay Request Webhook Event with Primary & Secondary Claims
{
"request_id": "cnpsa8ms8vbs7f52c8y2xchd77tza3nv",
"status": "success",
"callback_type": "COPAY",
"timestamp": 1563916377515,
"details": {
"metadata": "cfe146",
"message": "Here is a list of medications that were checked",
"patient_token": "4526d90a",
"prescriptions": [
{
"prescription_token": "z3q2jr",
"insurance_token": "skhsyq83rkd3uht9",
"status": "completed",
"copay_request_prescription_token": "17ed9e856d5baba1",
"next_fill_date": null,
"copay_amount": "10",
"fill_number": 1,
"days_supply": "30",
"quantity": 30,
"claims": [
{
"insurance_token": null,
"insurance": {
"rx_bin": "123456",
"pcn": "ABC",
"rx_group": "GROUP1",
"cardholder_id": "ABC010101",
"relationship_code": "1"
},
"billing_order": 1,
"status": "Paid",
"copay_amount": "50"
},
{
"insurance_token": "skhsyq83rkd3uht9",
"billing_order": 2,
"status": "Paid",
"copay_amount": "10"
}
]
}
]
}
}
Incoming Copay requests are processed in our Truepill pharmacy system.
On completion of a copay check request, Truepill will provide a webhook event with the text COPAY
in the callback_type
field. Like other webhook events, the status
field within each Prescription object indicates if it was successful.
In a successful copay check, a detailed list of the medications will be provided in the prescriptions
field.
If a copay is blocked by an extraneous circumstance but is believed to be resolved soon, the copay may be moved to a triage
status. A webhook event notification will be sent for Triaged Copays as well.
Successful Copay Request Webhook Event Fields
Field Name | Type | Description |
---|---|---|
patient_token | String | Associated patient's URL token |
prescriptions | Array of Copay Prescription objects | List of prescription copay information |
metadata | String | Provided by customer |
message | String | Plain English status text |
Copay Prescription Object
The prescriptions
field houses an array of objects that contain the following fields:
Field Name | Type | Description |
---|---|---|
prescription_token | String | Associated prescription's URL token |
insurance_token | String | Associated token for insurance that was used for the Copay Claim |
status | String | Status of copay request on associated prescription |
next_fill_date | String or null | Date the associated prescription is fillable |
copay_amount | String | Final copay price for the associated prescription |
copay_request_prescription_token | String | Token for identifying a prescription in a copay request |
days_supply | String | Day supply for the associated prescription |
quantity | Integer | Quantity for the associated prescription |
fill_number | Integer | The fill number of the prescription the copay is associated with |
error_code | String Rejection codes | Description (not code) of copay prescription rejection |
claim_reject_codes | Array of Reject Code objects | Array of NCPDP error codes at the prescription level |
claims | Array of Claim objects | Array of objects providing claim-level details |
Copay Prescription Rejection Codes
Code | Description |
---|---|
BAD_INSURANCE_DETAILS | Missing / Invalid Insurance Information |
COPAY_REQUEST_ABANDONED | Copay Request Abandoned |
HIGH_COPAY | High Copay |
INSURANCE_ISSUE | Insurance Issue |
INSURANCE_LTD_QTY | Quantity Limited by Insurance |
INSURANCE_TERMINATED | Coverage Terminated |
MAIL_ORDER_FILLS | Mail Order Fills Exceeded |
PA_DENIED | Prior Authorization Denied |
PA_REQUIRED | Prior Authorization Required |
PHARMACY_OUT_OF_NETWORK | Out of Network |
PHARMACY_OUT_OF_NETWORK_STATE_MEDICAID | Pharmacy Not Enrolled in State Medicaid Program |
PRIMARY_INSURANCE_REQUIRED | Primary Insurance Required |
RX_ISSUE | Prescription Issue |
RX_NO_REFILLS | Prescription Has No More Refills |
RX_NOT_COVERED | Not covered by insurance |
RX_REFILL_TOO_SOON | Refill too soon |
RX_TRANSFERRED | Prescription Transferred |
Reject Code Object Fields
Field Name | Type | Description |
---|---|---|
code | String | NCPDP claim rejection code |
message | String | String explanation of the NCPDP claim rejection code |
Prescription Claim Object Fields
The claims
field on the copay prescriptions
object provides additional claim-level detail for the prescription. This can be useful in cases where prescriptions are processed with multiple insurances. For example, if a prescription was adjudicated using primary and secondary insurance, the claims
object will display the copay amount or reject codes returned on the claim from each payer.
There may be situations where a copay webhook is returned without claims
; for example, if the prescription has no refills remaining or has invalid data for claim submission. In these cases, Truepill will reject the copay prescription before submitting any claims.
The claims
field houses an array of objects that contain the following fields:
Field Name | Type | Description |
---|---|---|
insurance_token | String | Associated token for insurance that was used for the Copay Claim. Returns null if processed insurance does not match any insurance on file for the patient |
insurance | Object Insurance object | Actual processed insurance details, if different from submitted insurance |
billing_order | Integer | Order in which the claim was billed. 1 = Primary insurance, 2 = Secondary insurance, etc |
status | String | Status of claim, e.g. "Paid", "Rejected" |
copay_amount | String | Copay amount for the associated claim. Amount in USD. |
voucher_savings_amount | Number | The amount of copay covered by eVoucher / Denial Conversion. Only returned if eV/DC was applied |
voucher_type | String | "eVoucher", "Denial Conversion", or "unknown" if Truepill was unable to determine the type. Only returned if eV/DC was applied |
response_message | String | The information provided in the Response Message (F4) field on the claim response |
additional_message_information | String | The information provided in the Additional Message Information (FQ) field on the claim response |
claim_reject_codes | Array of Reject Code objects | Array of NCPDP error codes for the associated claim |
The insurance
object within claims
returns actual processed insurance information. When Truepill's pharmacy team handles eligibility-related rejections for customers, copay checks may be processed using insurance that is different from what was originally submitted. In these cases, insurance_token
will be null and Truepill will instead provide the processed insurance information in the insurance
block.
Customers can reference these insurance fields on a successful/completed copay webhook to create a new insurance that can be used on the subsequent Fill Request. This ensures that the fill request will be processed with the correct insurance.
Claim Insurance Object Fields
Field Name | Type | Description |
---|---|---|
rx_bin | String | BIN number of the insurance used to process the copay check |
pcn | String | PCN of the insurance used to process the copay check |
rx_group | String | Group number of the insurance used to process the copay check |
cardholder_id | String | Cardholder ID of the insurance used to process the copay check |
relationship_code | String | Relationship code of the insurance used to process the copay check |
Handling Copay Request Rejections
Error Copay Request Webhook Event
{
"request_id": "cnpsa8ms8vbs7f52c8y2xchd77tza3nv",
"status": "error",
"callback_type": "COPAY",
"timestamp": 1563916377515,
"details": {
"error_code": "BAD_INSURANCE_DETAILS",
"metadata": "cfe146",
"message": "This request was rejected. Please see details.",
"patient_token": "4526d90a",
"reject_reason": "Bad Insurance Details",
"rejection_reason_other": "Invalid BIN"
}
}
There are a number of reasons why a Copay request may be rejected. The most common reasons include:
- Incorrect insurance details
- Refill too soon
- Product not covered
In an rejected copay check, the webhook event will contain the rejection reason.
Rejected Copay Request Webhook Event Fields
Field Name | Type | Description |
---|---|---|
patient_token | String | Associated patient's URL token |
reject_reason | String | A string containing the rejection reason |
reject_reason_other | String | Additional information about rejection - if provided |
metadata | String | Provided by customer |
message | String | Plain English status text |
error_code | String Copay Reject Codes | Error code for rejection |
Copay Reject Codes
Code | Description | Message (Additional Information) |
---|---|---|
DUPLICATE_REQUEST | Duplicate Request | N/A |
CLOSED_NETWORK | Closed Network | N/A |
PHARMACY_OUT_OF_NETWORK | Out of Network | N/A |
PHARMACY_OUT_OF_NETWORK_STATE_MEDICAID | Out of Network | N/A |
INSURANCE_TERMINATED | Coverage Terminated | N/A |
BAD_INSURANCE_DETAILS | Bad Insurance Details | List of selected insurance issues |
CUSTOMER_CANCELLATION_REQUEST | Copay Cancelled by Customer Request | N/A |
PA_REQUIRED | Prior Authorization Required | N/A |
Triaged Copay Requests
Triaged Copay Webhook Event
// Triage webhook event along with additional information
{
"request_id": "914b810e56445e6ca2ab025c9c96d254",
"timestamp": 1585608018,
"callback_type": "COPAY",
"status": "triage",
"details": {
"metadata": "cfe146",
"message": "This copay has been moved to Triage status",
"code": "CT004",
"description": "Refill too soon",
"additional_information": "2020-08-21",
"copay_token": "6fb823f403dc5aa3",
"patient_token": "bd8d80"
}
}
Certain copays may be blocked from being processed further due to external dependencies but can be resolved in a timely manner. If desired, these copays can be moved into the triage
status and handled by the proper personnel.
A webhook event will be sent to the customer when a Copay request is moved to the triage
status. Similar to the Copay Error Rejection webhook event, the Triage webhook event contains a code denoting the triage reason in the code
field. These codes are accompanied by a text description detailing the reason in the description
field.
If there is additional information that can accompany the triage code and description, it will be provided in the additional_information
field.
Table of Triage Codes & Associated Information
Code | Description | Additional Information |
---|---|---|
CT001 | Clinic Outreach | Description/reason of clinical outreach |
CT002 | Customer Clarification needed | May include description of desired customer clarification |
CT003 | Prior Authorization needed | May include description of Prior Authorization |
CT004 | Refill too soon | Date of when medication can be filled |
CT005 | Pending internal transfer | Pending internal transfer |
CT006 | Other Reason | Specifics of reason |
CT007 | Coverage Terminated | Description/reason of coverage terminated |
CT008 | Coverage Not Effective | Description/reason of coverage not effective |
CT009 | Date of Birth Mismatch | Date of birth mismatch |
CT010 | Bad Insurance Details | May include description such as: 'Missing/Invalid Group Number', 'Non-Matched Cardholder ID', 'Missing/Invalid PCN', 'Missing/Invalid DOB', 'Invalid BIN' |
Cancel a Copay Request
Cancel Fill Request
curl -X POST https://api.truepill.com/v1/copay_request/cancel \
-d api_key="ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-d request_id="bf11da52584eb54188bf8ebed33ef15f"
const body = {
request_id: 'bf11da52584eb54188bf8ebed33ef15f'
}
fetch('https://api.truepill.com/v1/copay_request/cancel', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"request_id": "cancel_copay_request_a122673989c1a4fd2152be59961ba31c",
"timestamp": 1635290822,
"status": "success",
"details": {
"code": "CUSTOMER_CANCELLATION_REQUEST",
"description": "Copay Cancelled by Customer Request",
"message": "Accepted: Copay Request 4d8e96a49420635e has been cancelled."
}
}
Error Response
{
"timestamp": 1511226167,
"status": "error",
"message": "There was an error cancelling this copay, either you are not the owner of the request, the copay doesn't exist, or have already cancelled the copay."
}
POST https://api.truepill.com/v1/copay_request/cancel
This endpoint cancels a copay request whose request_id
or copay_request_token
field matches the respective user-provided text parameter.
Request Fields
Field Name | Type | Description and Example | Required? |
---|---|---|---|
request_id | String | Request ID: 4181a2a48e03508c |
See Note |
copay_request_token | String | Copay Request Token: 4526d90a |
See Note |
Patient Safety API
Your patients’ safety is always our top priority. Our patient safety APIs are the foundation of every step in our pharmacy and telehealth process.
While we leverage our own APIs across our internal workflows, we also explore these safety features through our APIs to ensure patient safety is core to your experience.
Get a Patient Survey
Get Patient Survey Request
curl --request GET \
--url https://api.truepill.com/patient/{patient_token}/patient_survey
--header 'authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
fetch('https://api.truepill.com/patient/{patient_token}/patient_survey',{
method: 'GET',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w'
}
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"asthma_breathing": null,
"heart_disease": null,
"arthritis": null,
"lung_disorder": null,
"bleeding_clotting_disorder": null,
"neurological_chronic_headaches": null,
"blood_transfusion": null,
"psychiatric_disorder": null,
"bowel_stomach": null,
"pulmonary_embolism": null,
"cancer": null,
"stroke": null,
"cholesterol_disorder": null,
"seizure_epilepsy": null,
"diabetes": null,
"thyroid_disorder": null,
"eye_disorder": null,
"urinary_kidney_disorder": null,
"conditions": "COPD",
"smoking_frequency": null,
"drinking_frequency": null,
"url_token": "6fa050",
"other_medications": "null",
"known_allergies": "Regular Combivent Type of Inhaler(PT not allergic to combivent)",
"pregnancy": null
}
Error Response
{
"statusCode": 404,
"error": "Not Found",
"message": "Unable to find Patient."
}
GET https://api.truepill.com/v1/patient/{patient_token}/patient_survey
Once a patient survey has been submitted, you can look up the request payload that was submitted at any time for reference with an API request.
This endpoint requires the following:
patient_token
- A Fill request or Consult request for the patient that has been completed
Search Drugs, Conditions, and Allergies
You can use the Truepill Patient Safety API to search and retrieve a list of Allergens, Conditions, or Medications for your patient safety experience.
Each of these endpoints works similarly in that you pass in a search keyword
and you will retrieve a list of related results.
Search results will be limited to 50 entries.
Search Allergies
Allergen Search Request
curl -X GET https://api.truepill.com/v1/patient_safety/allergies?keyword=pea \
-H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json"
fetch('https://api.truepill.com/v1/patient_safety/allergies?keyword=pea', {
method: 'GET',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
[
"Pear",
"Tea Tree",
"Palmitamide MEA",
"Acetamide MEA",
"Sea Cucumber",
"Sea Whip",
"DEA-Cetyl Phosphate",
"Disodium Ricinoleamido MEA-Sulfosuccinate",
"Green Tea (Camellia Sinensis)",
"Red Beet (Beta Vulgaris)",
"Sea Parsley (Palmaria Palmata)",
"Urea",
"Bee Pollens",
"Pde5 Inhibitor",
"Prostaglandins F2a",
"Glucanase-beta",
"Red Clover",
"Imidazolidinyl Urea",
"Diazolidinyl Urea",
"Beta-Glucan"
]
GET https://api.truepill.com/v1/patient_safety/allergies?keyword={SEARCH_TERM}
Search Conditions
Conditions Search Request
curl -X GET https://api.truepill.com/v1/patient_safety/conditions?keyword=pea \
-H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json"
fetch('https://api.truepill.com/v1/patient_safety/conditions?keyword=pea', {
method: 'GET',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
[
"Open wound of head",
"Open wound of knee and lower leg",
"Pre-eclampsia",
"Polycythemia vera",
"Pre-existing hypertension with pre-eclampsia",
"Fall from bed",
"Open wound of neck",
"Indeterminate sex and pseudohermaphroditism",
"Abnormalities of heart beat",
"Crushing injury of head",
"Open wound of thorax",
"Cholesteatoma of middle ear",
"Pedal cycle rider injured in collision with other pedal cycle",
"Pneumothorax and air leak",
"Superficial injury of head",
"Foreign body in ear",
"Exposure to excessive natural heat",
"Effects of heat and light",
"Other diseases of inner ear",
"Otalgia and effusion of ear"
]
GET https://api.truepill.com/v1/patient_safety/conditions?keyword={SEARCH_TERM}
Search Medications
Medications Search Request
curl -X GET https://api.truepill.com/v1/patient_safety/medications?keyword=pea \
-H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json"
fetch('https://api.truepill.com/v1/patient_safety/medications?keyword=pea', {
method: 'GET',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
[
"PRE-PEN",
"PEN-VEE K",
"PEG-LYTE",
"GRIS-PEG",
"BYDUREON PEN",
"HUMALOG PEN",
"NUTROPIN AQ PEN",
"SER-A-GEN",
"HUMULIN R PEN",
"LUPRON DEPOT-PED",
"PEG 3350 AND ELECTROLYTES",
"EPI E Z PEN JR",
"EPIPEN E Z PEN",
"HUMULIN 70/30 PEN",
"HUMALOG MIX 50/50 PEN",
"PBZ",
"PBZ",
"PCE",
"WERA",
"HUMALOG MIX 75/25 PEN"
]
GET https://api.truepill.com/v1/patient_safety/medications?keyword={SEARCH_TERM}
Prior Authorization
Truepill leverages its own internal workflows and uses industry-standard CoverMyMeds for electronic prior authorization workflows.
Our prior authorization and electronic prior authorization (ePA) workflows are based on the NCPDP SCRIPT standard for ePA.
Prospective vs. Retrospective
There are two ways you can trigger a Prior Authorization request — they are commonly referred to as "prospectively" by a doctor or "retrospectively" after a claim rejection in the pharmacy. A majority of PAs today are still handled retrospectively at the pharmacy. We will cover the retrospective approach in more detail here and cover the prospective approach in more detail in our Telehealth API.
Using Copay Request vs. Prior Authorization API
We provide a streamlined approach to managing your PA process within your Copay request or a more robust process with our Prior Authorization API.
If you know the medication being dispensed has a low or moderate prevalence of PAs, then you may choose to use the copay request since a bulk of your Copay requests will be returned successfully without a PA rejection.
Alternatively, if you know the medication being dispensed requires PAs 100% of the time (most specialty products), then we recommend using our Prior Authorization which will provide finer controls to managing your PA process. Our Prior Authorization API can also provide you a real-time prediction on whether a PA will be required based on the insurance and medication details provided.
Prior Authorization Request
In this section, we will cover the retrospective prior authorization process as a result of a PA-rejected insurance claim at the pharmacy.
Create a Prior Authorization Request
Prior Authorization Request
curl -X POST https://api.truepill.com/v1/prior_authorization \
-H "Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json" \
-d '{
"patient_token": "4526d90a",
"insurance_token": "19sienglo92831n5",
"prescription_token": "z3q2jr",
"metadata": "cfe146",
"prescriber_phone": "1-800-123-4567",
"prescriber_fax": "1-800-234-5678"
}'
const body = {
patient_token: '4526d90a',
insurance_token: '19sienglo92831n5',
prescription_token: 'z3q2jr',
metadata: 'cfe146',
prescriber_phone: '1-800-123-4567',
prescriber_fax: '1-800-234-5678'
}
fetch('https://api.truepill.com/v1/prior_authorization', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"request_id": "prior_auth_bd6825a9d66a49b3d7a7",
"timestamp": 1592183925,
"status": "success",
"details": {
"message": "Your prior authorization request has been processed successfully.",
"patient_token": "4526d90a",
"insurance_token": "19sienglo92831n5",
"prescription_token": "z3q2jr",
"metadata": "cfe146",
"prescriber_phone": "1-800-123-4567",
"prescriber_fax": "1-800-234-5678"
}
}
POST https://api.falsepill.com/v1/prior_authorization
A prior authorization can be created by making a Prior Authorization request. Truepill will provide a receipt confirmation of the request, and multiple subsequent webhook events throughout the lifecycle of your PA.
Prior Authorization Request Fields
Field Name | Type | Description and Example | Required? |
---|---|---|---|
patient_token | String | Associated patient's record token | Yes |
insurance_token | String | Associated patient's insurance record token | Yes |
prescription_token | String | Token to reference the prescription | Yes |
metadata | String | Customer-side identifier to reference the PA request in customer system | No |
prescriber_phone | String | Phone number associated with the prescriber | No |
prescriber_fax | String | Fax number associated with the prescriber | No |
Managing the Prior Authorization Workflow
Prior Authorization Webhook Event
{
"request_id": "8y2xc7tp93nc2csacn2hd7afka3nv",
"status": "new",
"callback_type": "PRIOR_AUTH",
"timestamp": 1563916377515,
"details": {
"prior_auth_type": "traditional",
"message": "The PA has been created, but not yet submitted to plan",
"patient_token": "4526d90a",
"prescription_token": "z3q2jr",
"insurance_token": "19sienglo92831n5",
"metadata": "cfe146",
"prescriber_phone": "1-800-123-4567",
"prescriber_fax": "1-800-234-5678"
}
}
There are two types of PA requests: ePA and traditional PA. Both of them are managed in the Truepill Prior Authorization API. Traditional PA requests are used with payers who have not yet adopted the new digital standard. The major difference between the two approaches is in the workflow as reflected in the different status updates you will receive.
Status updates are sent using a webhook event with the text PRIOR_AUTH
in the callback_type
field and references your Prior Authorization request ID.
Prior Authorization Workflow Statuses
Status | Definition |
---|---|
new | The PA has been created, but not yet submitted to plan. Typically a PA in this status is awaiting action by the provider |
submitted | The PA has been submitted to the payer for approval |
pending | The PA has been submitted to the payer for approval |
approved | The PA has been approved by the payer |
declined | The PA has been rejected by the payer |
cancelled | The PA has been successfully cancelled |
appealed | The PA was appealed and the payer is working to make a determination |
Initiating a Prior Auth from Copay Request
Copay Request with Prior Authorization Initiated
curl -X POST https://api.truepill.com/v1/copay_request \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
-d patient_token='4526d90a' \
-d insurance_token='["skhsyq83rkd3uht9"]' \
-d prescriptions='[
"z3q2jr",
"3cs873",
"wz25v2"
]' \
-d metadata='cfe146' \
-d initiate_prior_auth=true
const body = {
patient_token: '4526d90a',
insurance_token: ['skhsyq83rkd3uht9'],
prescriptions: ['z3q2jr', '3cs873', 'wz25v2'],
metadata: 'cfe146',
initiate_prior_auth: true
}
fetch('https://api.truepill.com/v1/copay_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Prior Authorization Webhook Event - New
{
"request_id": "8y2xc7tp93nc2csacn2hd7afka3nv",
"status": "new",
"callback_type": "PRIOR_AUTH",
"timestamp": 1563916377515,
"details": {
"prior_auth_type": "ePA",
"message": "The PA has been created, but not yet submitted to plan",
"prescriber_form": "https://www.secure:prior-authorization.com/request/view/A83ADBK4?token_id=n042aqoali9o9vcfr8ef",
"patient_token": "4526d90a",
"prescription_token": "z3q2jr",
"insurance_token": "19sienglo92831n5",
"metadata": "cfe146",
"prescriber_phone": "1-800-123-4567",
"prescriber_fax": "1-800-234-5678"
}
}
Prior Authorization Webhook Event - Pending
{
"request_id": "8y2xc7tp93nc2csacn2hd7afka3nv",
"status": "pending",
"callback_type": "PRIOR_AUTH",
"timestamp": 1563916377515,
"details": {
"prior_auth_type": "ePA",
"message": "The PA has been submitted to the payer for approval",
"patient_token": "4526d90a",
"prescription_token": "z3q2jr",
"insurance_token": "19sienglo92831n5",
"metadata": "cfe146",
"prescriber_phone": "1-800-123-4567",
"prescriber_fax": "1-800-234-5678"
}
}
Prior Authorization Webhook Event - Approved
{
"request_id": "8y2xc7tp93nc2csacn2hd7afka3nv",
"status": "approved",
"callback_type": "PRIOR_AUTH",
"timestamp": 1563916377515,
"details": {
"prior_auth_type": "ePA",
"message": "The PA has been approved by the payer",
"patient_token": "4526d90a",
"prescription_token": "z3q2jr",
"insurance_token": "19sienglo92831n5",
"metadata": "cfe146",
"prescriber_phone": "1-800-123-4567",
"prescriber_fax": "1-800-234-5678"
}
}
Successful Copay Request Webhook Event
{
"request_id": "cnpsa8ms8vbs7f52c8y2xchd77tza3nv",
"status": "success",
"callback_type": "COPAY",
"timestamp": 1563916377515,
"details": {
"metadata": "cfe146",
"message": "Here is a list of medications that we have successfully checked the copay amounts for",
"patient_token": "4526d90a",
"prescriptions": [
{
"prescription_token": "z3q2jr",
"status": "completed",
"next_fill_date": "2019-07-23T00:00:00.000Z",
"insurance_token": "19sienglo92831n5",
"copay_amount": "21.02",
"copay_request_prescription_token": "98dagjw",
"days_supply": "28",
"quantity": 28
}
]
}
}
The prior authorization workflow is covered in full detail in the Prior Authorization Guide. If you need a more streamlined way to manage your PA process, you can do so from within your Copay request.
With a Copay request, an electronic PA request can automatically be initiated at the point of claim rejection. If you intend to leverage our PA workflow, you can set the initiate_prior_auth
field to true
on the Copay request object.
Once a prior authorization is initiated by Truepill, we will notify you at various stages of the PA process through webhook events.
Once a Prior Authorization request is approved, your webhook event for the Copay request will look identical to a standard successful copay request. It will be processed seconds after receiving a PA approval.
Coverage Request
There may be scenarios where you do not have valid insurance details for your patient.
In these situations, you can use the Coverage Request endpoint to run a benefits investigation. If we find valid plans and benefit details, we will send them back to you via a webhook event.
Create a Coverage Request
Coverage Request
curl -X POST https://api.truepill.com/v1/coverage_request \
--header 'Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
-d patient_token ='4526d90a' \
-d metadata='cfe146'
const body = {
patient_token: '4526d90a',
metadata: 'cfe146'
}
fetch('https://api.truepill.com/v1/coverage_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"request_id": "skhsyq83rkd3uht9",
"timestamp": 1593452421,
"status": "success",
"details": {
"coverage_request_token": "skhsyq83rkd3uht9",
"message": "Your coverage request has been processed successfully."
}
}
POST https://api.truepill.com/v1/coverage_request
This endpoint generates a Coverage request for Truepill to investigate whether a patient has any valid plans or benefit details. Upon successful API submission, Truepill will provide a receipt confirmation of the request. Results will be sent to your webhook server via Coverage Request webhook event.
Body Fields
Field Name | Type | Description and Example | Required? |
---|---|---|---|
patient_token | String | 4526d90a Token to reference Patient record upon Patient Creation |
Yes |
metadata | String | cfe146 Customer-side identifier to reference the Fill request in customer system |
Yes |
Coverage Request Webhook Events
Successful Coverage Webhook Event - Patient Insurance Retrieved & In-Network
{
"request_id": "skhsyq83rkd3uht9",
"status": "success",
"callback_type": "COVERAGE",
"timestamp": 1567026972,
"details": {
"metadata": "cfe146",
"patient_token": "4526d90a",
"coverage_request_token": "skhsyq83rkd3uht9",
"insurances": [
{
"insurance_token": "0db029",
"cardholder_id": "XBC1009876543",
"bin": "880099",
"group_number": "D96009620",
"pcn": "SP9E6",
"plan_type": "commercial",
"effective_date": "2019-03-01T00:00:00.000Z",
"termination_date": "2020-02-29T00:00:00.000Z",
"payer_name": "Anthem BC",
"person_code": "03",
"patient_relationship": "Child",
"help_desk_phone_number": "800-300-2000"
}
]
}
}
Successful Coverage Webhook Event - Patient Insurance Retrieved & Out-of-Network
{
"request_id": "skhsyq83rkd3uht9",
"status": "success",
"callback_type": "COVERAGE",
"timestamp": 1567026972,
"details": {
"metadata": "cfe146",
"patient_token": "4526d90a",
"coverage_request_token": "skhsyq83rkd3uht9",
"insurances": [
{
"insurance_token": "0db029",
"cardholder_id": "XBC1009876543",
"bin": "880099",
"group_number": "D96009620",
"pcn": "SP9E6",
"plan_type": "commercial",
"effective_date": "2019-03-01T00:00:00.000Z",
"termination_date": "2020-02-29T00:00:00.000Z",
"payer_name": "Anthem BC",
"person_code": "03",
"patient_relationship": "Child",
"help_desk_phone_number": "800-300-2000"
}
]
}
}
Error Coverage Webhook Event - Patient Insurance Not Found
{
"request_id": "skhsyq83rkd3uht9",
"status": "error",
"message": "Patient insurance is not found",
"callback_type": "COVERAGE",
"timestamp": 1567026972,
"details": {
"metadata": "cfe146",
"patient_token": "4526d90a",
"coverage_request_token": "skhsyq83rkd3uht9",
"insurances": null
}
}
Error Coverage Webhook Event - Patient Social Security Number Not Available
{
"request_id": "skhsyq83rkd3uht9",
"status": "error",
"message": "Patient social security number is not available",
"callback_type": "COVERAGE",
"timestamp": 1567026972,
"details": {
"metadata": "cfe146",
"patient_token": "4526d90a",
"coverage_request_token": "skhsyq83rkd3uht9",
"insurances": null
}
}
After submitting a Coverage request, Truepill will send a webhook event upon completion of the coverage check.
The webhook event will contain the text COVERAGE
in the callback_type
field.
Coverage Request Webhook Event Fields
Field Name | Type | Description |
---|---|---|
patient_token | String | Associated patient's token |
coverage_request_token | String | Associated coverage request token |
insurances | Array | Array of Insurance objects |
metadata | String | Provided by customer |
Coverage Insurance Object
The coverage insurance
field houses an object that contains the following fields:
Field Name | Type | Description |
---|---|---|
insurance_token | String | Insurance token |
bin | String | Insurance BIN number |
pcn | String | Insurance PCN |
group_number | String | Insurance group number |
cardholder_id | String | Cardholder ID or Member ID |
plan_type | String | Insurance plan type: commercial or government |
effective_date | String | Effective date |
termination_date | String | Termination date |
payer_name | String | Payer name |
person_code | String | Person code |
patient_relationship | String | Patient relationship (if applicable) |
help_desk_phone_number | String | Payer's help desk phone number |
Telehealth API
The Truepill Telehealth API will allow you to easily leverage our nationwide provider network for a clinical telehealth consult by a licensed provider.
The process starts when you request a consult, and similarly to our Pharmacy API endpoints, you will receive notifications about your requested consult through our webhook events. These webhook events will provide updates on the lifecycle of your clinical consult.
In this guide, we will walk you through the two basic steps of getting medication delivered to your patient.
- Create a Patient.
- Create a Consult request.
Assigning a Provider
Assigning a licensed provider to your consult request is handled seamlessly behind the scenes by our technology. If you are looking to bring your own providers onto our platform, please talk to our team about utilizing our EMR platform and programmable EMR APIs.
Once a provider is assigned to your consult request, you will receive a webhook event notifying you of the assigned provider.
Concepts in POSTing a Consult
Consult Types
Truepill offers two types of consults through the API — asynchronous and synchronous.
An asynchronous consult is a clinical consult where patient-provider interaction is not required. Patients will typically submit clinical data in the form of a patient questionnaire. This questionnaire can be reviewed asynchronously and be used to diagnose and prescribe medications.
A synchronous consult is a clinical consult where patient-provider interaction is required. Visits can be held either by phone or video conference and can be requested on-demand or scheduled.
For on-demand consults, a provider calls a patient based on the SLA. For scheduled consults, in addition to the SLA, a patient specifies the preferred date and time of the consult.
Questionnaires
Consults are customized to your program. We build consults based on agreed clinical protocol, such as your target diagnosis, target treatment, which can be a prescription, whether the consult is asynchronous or synchronous. Once your program’s consult has been set up, we provide you with a questionnaireId to submit when creating a new consult.
Standard Questions
Prior to submitting a consult, you must collect from your patients answers to our standard questions:
- Medications
- Allergies
- Medical Conditions
These answers are submitted in the standardQuestions
field when creating a consult.
Answers Object
Prior to creating a consult, you may ask your patients questions which are required by your program and will be reviewed by the provider. The answers are submitted in the Answers object. The fields will be a camel-cased representation of the question, which are unique to your questionnaireId and therefore your consult setup.
Consult Workflow Status
As a consult goes through the various stages, Truepill sends a status update on the consult via webhooks. Statuses are:
Consult Workflow Statuses
Status | Definition |
---|---|
assigned | Licensed provider has accepted the Consult request |
review | Licensed provider has started the Consult |
issue | Licensed provider has run into an issue (technical, clinical, etc.) |
resolved | Care team has resolved the issue the provider encountered, allowing the provider to resume the consult |
rejected | Licensed provider has rejected the Consult request. Rejection reason provided under reject_reason |
unassigned | Licensed provider has declined the Consult request after accepting it |
completed | Licensed provider has completed the Consult request. See Consult Completion States |
cancelled | Customer/Care team has cancelled the Consult request — rare, possibly due to bad or test consult |
Consult Completion States
Consults in the "completed" status also have a specific state within the details
object.
Status | Definition |
---|---|
advice_911 | When a provider recommends a patient reach out to 911 for assistance |
advice_immediate_attention | When a provider recommends a patient to reach out to ER or ED for further care |
advice_local_provider | When a provider recommends a patient to reach out to PCP for further care |
advice_other | Catch all for when a provider recommends a patient something different |
patient_failed_to_respond | When a patient failed to respond to a provider outreach |
rx_prescribed | When a provider writes a prescription |
sig_otc | When a provider recommends a patient to use an OTC product |
Create a Consult Request
Create Consult Request
curl -X POST https://api.truepill.com/consults/v0/consult \
-H "Authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json" \
-d '{
"metadata": "1234",
"patient": [
{
"first_name": "Jane",
"last_name": "Doe",
"gender": "female",
"dob": "2000-01-01",
"home_zip": "94538",
"preferred_contact": "email"
}
],
"contacts": [
{
"email": "test@truepill.com",
"phone": "415-234-1234",
"sms": "415-234-1234"
}
],
"shipping_address": [
{
"line1": "Jane Doe",
"street1": "123 Steiner St",
"city": "San Francisco",
"state": "CA",
"zip": "94115"
}
],
"primary_care_provider": [
{
"name": "Dr. Primary Provider",
"phone": "555-555-5555",
"fax": "555-555-5555"
}
],
"payment_type": "cash",
"preferred_treatment": {
"rx": [
{
"ndc": "ndc_code",
"days_supply": "90",
"quantity": "1",
"num_refills": "1",
"allow_substitutions": false
}
],
"devices": [
{
"hcpcs": "hcpcs_billing_code",
"quantity": "1"
}
]
},
"questionnaire": "603971f14e57401334aa16e0",
"standard_questions": {
"medications": "Xarelto",
"allergies": "Penicillin",
"conditions": "Diabetes"
},
"media": {
"documents": [
{
"id": "04ac64eb-d914-44ef-b653-80170fcfc0e4"
},
{
"id": "11259f82-a680-4021-a2ca-60e29523a7d3"
}
]
},
"identification": [
{
"form": "PHOTO_IDENTIFICATION",
"mediaId": "04ac64eb-d914-44ef-b653-80170fcfc0e4"
},
{
"form": "SELF_PORTRAIT",
"mediaId": "11259f82-a680-4021-a2ca-60e29523a7d3"
}
],
"answers": {
"which_of_the_following_istrue": {
"values": [
"A hereditary cancer syndrome runs in your family",
"None of the above"
],
"answers": [
"None of the above"
]
}
},
"appointment": {
"duration": 3600,
"appt_date": "2021-06-01T17:00:00.000Z"
}
}'
const body = {
metadata: '1234'
patient: {
first_name: 'Jane',
last_name: 'Doe',
gender: 'female',
dob: '2000-01-01',
home_zip: '94538',
preferred_contact: 'email',
contacts: {
email: 'test@truepill.com',
phone: '415-234-1234',
sms: '415-234-1234'
}
},
shipping_address: {
line1: 'Jane Doe',
street1: '123 Steiner St',
city: 'San Francisco',
state: 'CA',
zip: '94115'
},
primary_care_provider: {
name: 'Dr. Primary Provider',
phone: '555-555-5555',
fax: '555-555-5555'
},
payment_type: 'cash',
preferred_treatment: {
rx: [
{
ndc: 'ndc_code',
days_supply: '90',
quantity: '1',
num_refills: '1',
allow_substitutions: false
}
]
devices: [
{
hcpcs: 'hcpcs_billing_code',
quantity: '1'
}
]
},
questionnaire: '603971f14e57401334aa16e0',
standard_questions: {
medications: 'Xarelto',
allergies: 'Penicillin',
conditions: 'Diabetes'
},
answers: {
which_of_the_following_istrue: {
values: [
'A hereditary cancer syndrome runs in your family',
'None of the above'
],
answers: [
'None of the above'
]
}
},
appointment: {
duration: 3600,
apptDate: '2021-06-01T17:00:00.000Z'
},
}
fetch('https://api.truepill.com/consults/v0/consult', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"consult": "6dcf35ee85c869d281d85d43",
"patient": {
"patient_token": "9c04e6837c6c96f5"
}
}
Error Response - Request Fails Validation
{
"status_code": 400,
"error": "Bad Request",
"message": "\"patient.contacts.phone\" with value \"12314512\" fails to match the required pattern: /^\\s*(?:\\+?(\\d{1,3}))?[-. (]*(\\d{3})[-. )]*(\\d{3})[-. ]*(\\d{4})(?: *x(\\d+))?\\s*$/"
}
Error Response - User Accessing Prohibited Resource
{
"status_code": 401,
"error": "Unauthorized",
"message": "User is not allowed to access this resource"
}
Error Response - Questionnaire Not Found or Unauthorized
{
"status_code": 404,
"error": "Not Found",
"message": "Questionaire not found (You may not be authorized to it)."
}
POST https://api.truepill.com/consults/v0/consult
A consult can be created using our Consult API endpoint. Truepill will provide a receipt confirmation of the request and multiple subsequent webhook events throughout the lifecycle of the consult.
Consult Request Fields
Field Name | Type | Description and Example | Required for Async Consult? | Required for Sync Consult? |
---|---|---|---|---|
patient | Object | Patient’s demographics | Yes | Yes |
shippingAddress | Object | Patient’s address for shipping medications and lab tests | Yes | Yes |
questionaire | String | Unique identifier for the type of consult and questions | Yes | Yes |
standardQuestions | Object | Questions on patient’s medication, allergies, and medical conditions | Yes | Yes |
answers | Object | Program-specific answers provided by patient before the consult | See description | See description |
paymentType | String | Patient’s payment method: cash or insurance |
Yes | Yes |
insurances | Array | Array of Insurance objects. Required if paymentType is set to insurance |
See description | See description |
appointment | Object | Patient’s preferred date and time for the sync consult | No | Yes |
isVideoConsult | Boolean | Whether the sync consult is a video consult | Not applicable | No |
otherConsultInfo | Object | Additional consult details | No | No |
documents | Object | Supporting documents for the consult, please use media key instead | No | No |
primaryCareProvider | Object | Patient’s primary care provider | No | No |
attribute | String | Additional identifier | No | No |
preferredTreatment | Object | Patient’s or customer’s preferred treatments — devices or rx |
No | No |
metadata | String or Stringified JSON | Customer-side identifier | No | No |
media | Object | Use media endpoint to upload necessary documents in place of documents field | No | No |
identification | Array | Patient photo identifications like driver license | No | No |
Consult Webhook Events
Consult Webhook Event - Consult Assigned
{
"consult_id": "6dcf35ee85c869d281d85d43",
"timestamp": 1597777734,
"callback_type": "CONSULT",
"status": "assigned",
"details": {
"message": "Licensed provider has accepted the Consult",
"provider": "Doogie Howser",
"metadata": "1234"
}
}
Consult Webhook Event - Consult Review
{
"consult_id": "6dcf35ee85c869d281d85d43",
"timestamp": 1597777734,
"callback_type": "CONSULT",
"status": "review",
"details": {
"message": "Licensed provider has started the Consult",
"provider": "Doogie Howser",
"metadata": "1234"
}
}
Consult Webhook Event - Consult Rejected
{
"consult_id": "6dcf35ee85c869d281d85d43",
"timestamp": 1597777734,
"callback_type": "CONSULT",
"status": "rejected",
"details": {
"reject_reason": "Patient is not eligible",
"message": "Licensed provider has rejected the Consult request. Rejection reason provided under `reject_reason`",
"provider": "Doogie Howser",
"metadata": "1234"
}
}
Consult Webhook Event - Consult Completed
{
"consult_id": "6dcf35ee85c869d281d85d43",
"timestamp": 1597777734,
"callback_type": "CONSULT",
"status": "completed",
"details": {
"state": ["rx_prescribed"],
"message": "Licensed provider has completed the Consult request",
"provider": "Doogie Howser",
"metadata": "1234"
}
}
Our telehealth platform provides real-time visibility into the status of your consults. You will receive a series of webhook events relating to the status of your consult as it is being processed.
Consult webhook events will be identified with the text CONSULT
in the callback_type
field. The status
field will indicate the current status of the Consult.
File Interaction Webhook Events
File Interaction Webhook Event - File Uploaded
{
"timestamp":1625237490,
"consult_id":"60a81aca1b9368001c503783",
"callback_type":"FILE",
"details":{
"metadata":"METADATA",
"documents":[
{
"status":"UPLOADED",
"document_id":"60df27f1b5f815001c74b84d",
"tags":[
"SELFIE"
]
},
{
"status":"UPLOADED",
"document_id":"60df27f1b5f815001c74b84e",
"tags":[
"PHOTO_ID"
]
}
]
}
}
File Interaction webhook events are sent when a patient’s photo for identification or selfie is uploaded. The webhook event has the FILE
in the callback_type
field.
Get a Consult
Get Consult Request
curl --request GET \
--url https://api.truepill.com/consults/v0/consult/6010ab456436f5291efa8ab0
--header 'authorization: ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w' \
fetch('https://api.truepill.com/consults/v0/consult/6010ab456436f5291efa8ab0', {
method: 'GET',
headers: {
Authorization: 'ApiKey tp_live_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"id": "6010ab456436f5291efa8ab0",
"prescriptions": [{
"id": "6010ab456436f5291efa8ab0",
"ndc": "52817029500",
"name": "Sildenafil",
"strength": "20mg",
"days_supply": 30,
"refills": 2,
"sig": "Take 3 tablets as needed 1 hour before sex (max once daily)",
"quantity": 3,
"created_at": "2000-01-01T23:52:37.982Z"
}],
"provider": {
"npi": 1306394952,
"first_name": "Maria",
"last_name": "ABAD"
}
}
Error Response - User Is Not Allowed to Access This Resource
{
"status_code": 401,
"error": "Unauthorized",
"message": "User is not allowed to access this resource"
}
GET https://api.truepill.com/consults/v0/consult/{consult_id}
Once a consult has been created, you can access the associated prescription, lab order, and provider information using the GET consult
endpoint. The consultId
can be found on the Create Consult response.
Media Upload API
Truepill’s Media Upload API provides a secure upload mechanism of media into Truepill’s ecosystem. It provides malware scanning, content scanning, and more.
API URLs
Staging URL: https://api.falsepill.com
Production URL: https://api.truepill.com
Authentication: API Key to be provided to you through secure email. Header: https://docs.truepill.com/#authentication
There are two endpoints for you to communicate with the Media API : - A public endpoint to make a signed URL and to post a media file to the Media API - A public endpoint to get a media file status
Step 1: Upload media to cloud storage bucket
First, you need to upload your media to a cloud storage bucket for review and scanning.
POST api/v2/media
Create a media record and make a signed URL.
Parameters:
- name (required): string – a name of the media uploaded to the Inbound bucket.
Response:
{
id: [uuid]
status: “AWAITING_UPLOAD”
name: [required]
upload_Url: [url]
}
- If the authentication token (from request) is not valid, the response status is 401.
- Make a request to the POST api/v2/media endpoint:
- This POST endpoint uses Google Cloud Storage SDK by itself, so there is no need to use SDK on the web app side.
- Parameter: name - is a file name created by you.
File Name Example
json “image.jpg”
Response:
Response Example
Uploading URL for the cloud storage bucket
"https://storage.googleapis.com/tp-media-develop-inbound/image.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=upload-scanner%40ironman-dev.iam.gserviceaccount.com%2F20211126%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20211126T130011Z&X-Goog-Expires=900&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=679f9367704d651580e41aedb956ba9dd3e0e6fdf654b5fcefd90197ba2b2fd2e990e58995fdc833b7bed4f471d8a40c83bea2af0d6712dcd6462ec1606334fb151a8e71268cdd360ff8860a66f8f30ffd041e6bbe8e4c00f5e2efb934361e20e2a7157914f90bfb13b50ac950dbc7d2fb0d7955aafafc532866d06f3ddf2edce7a3f8b7f560cb140842eedf7a4abfb23dc4ae4203d83c0266960d12a59a38ef6012d32682fbc82d06fe1a1b984b438380ccb5c78a5c0b8b9f3f662f09a8001d9195065477bcc4e808136f8faccfb68caf52a53bda46d389d4ca4d4bb5032bc521a6e55f9973e335ed5e263023c686d12bce9687ba7bb1ab0006a2bcd7d3bfed"
- Call the PUT method within the web app:
- Parameter: signed-url (returned in Step 1).
Code Example (using the Axios Javascript library)
axios.put(signed-url, data, {
headers: {
"x-goog-content-length-range": `0,4000000000`
}
}
- The file limit is 4 GB in the header: x-goog-content-length-range:0,4000000000.
Step 2: GET media
GET api/v2/media/{id}
Get all details about the media file, including its status.
Parameters: - id (required): string – a unique id (in UUID v4) created by Truepill.
Response:
{
id: [required]
name: [required]
status: [required]
url: [required]
}
- If the request is not correct (incorrect Id format - not UUID), the response status is 400.
- If the request returns nothing (record not found), the response status is 404.
- If the authentication token (from request) is not valid, the response status is 401.
Response Example
{
"id": "8844583a-1940-40e6-ad08-ba0a8f2ab721",
"name:": “image.jpg”,
"status": "AVAILABLE",
"url": "https://storage.googleapis.com/tp-media-develop-inbound/image.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=upload-scanner%40ironman-dev.iam.gserviceaccount.com%2F20211126%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20211126T130011Z&X-Goog-Expires=900&X-Goog-SignedHeaders=content-type%3Bhost&X-Goog-Signature=679f9367704d651580e41aedb956ba9dd3e0e6fdf654b5fcefd90197ba2b2fd2e990e58995fdc833b7bed4f471d8a40c83bea2af0d6712dcd6462ec1606334fb151a8e71268cdd360ff8860a66f8f30ffd041e6bbe8e4c00f5e2efb934361e20e2a7157914f90bfb13b50ac950dbc7d2fb0d7955aafafc532866d06f3ddf2edce7a3f8b7f560cb140842eedf7a4abfb23dc4ae4203d83c0266960d12a59a38ef6012d32682fbc82d06fe1a1b984b438380ccb5c78a5c0b8b9f3f662f09a8001d9195065477bcc4e808136f8faccfb68caf52a53bda46d389d4ca4d4bb5032bc521a6e55f9973e335ed5e263023c686d12bce9687ba7bb1ab0006a2bcd7d3bfed"
}
Media File Statuses
Status | Definition |
---|---|
AWAITING_UPLOAD | File is waiting to be uploaded |
REVIEWING | File is being reviewed by scanner |
QUARANTINE | File has been deemed unsafe and will not be available |
AVAILABLE | File is safe and available to the internal platform |
Sandbox Testing with Simulations
In the sandbox environment, Truepill's live systems for managing eRx's don't exist. To make up for this, the sandbox environment houses frameworks to simulate these webhook events and prescriptions.
This will be important and useful as you test your integration end-to-end with Truepill's platform in the sandbox environment.
Below are the APIs that have simulations in place:
- Patient & Prescription
- Copay request
- Fill request
- Direct Transfer
- Consult
Simulations are available ONLY in the sandbox environment. As such, the code examples in this section hit api.falsepill.com
.
Patient & Prescription
Creating a Patient and Two Prescriptions: One with Default Rx Information and One with Custom Information
curl -X PUT https://api.falsepill.com/v1/patient \
--header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
-d '{
"first_name": "David",
"last_name": "Doe",
"dob": "19820115",
"gender": "male",
"company": "Example Company",
"street1": "123 Some Lane",
"street2": "UNIT 301",
"city": "Los Angeles",
"state": "CA",
"zip": "94402",
"phone": "001000000000",
"email": "example@email.com",
"simulation": {
"newRx": [
true,
{
"medication_sig": "Take one every two hours",
"prescriber": "Dr. Strange",
"days_supply": "1",
"num_refills_filled": "2",
"refills_remaining": 4,
"quantity_remaining": 48,
"number_of_refills_allowed": 4,
"prescribed_drug_strength": "50 mg",
"prescribed_ndc": "55555555555",
"prescribed_quantity": 12,
"prescribed_unit_text": "EA",
"prescribed_label_type": "Generic",
"prescribed_brand_name": "Generic Label",
"prescribed_written_name": "Generic Label 50mg Tablet",
"prescribed_generic_name": "Generic 50mg tablet",
"dispensed_drug_strength": "50 mg",
"dispensed_ndc": "55555555555",
"dispensed_quantity": 12,
"dispensed_days_supply": 1
}
]
}
}'
const body = {
first_name: 'David',
last_name: 'Doe',
dob: '19820115',
gender: 'male',
company: 'Example Company',
street1: '123 Some Lane',
street2: 'UNIT 301',
city: 'Los Angeles',
state: 'CA',
zip: '94402',
phone: '001000000000',
email: 'example@email.com',
simulation: {
newRx: [
true,
{
medication_sig: 'Take one every two hours',
prescriber: 'Dr. Strange',
days_supply: '1',
num_refills_filled: '2',
refills_remaining: 4,
quantity_remaining: 48,
number_of_refills_allowed: 4,
prescribed_drug_strength: '50 mg',
prescribed_ndc: '55555555555',
prescribed_quantity: 12,
prescribed_unit_text: 'EA',
prescribed_label_type: 'Generic',
prescribed_brand_name: 'Generic Label',
prescribed_written_name: 'Generic Label 50mg Tablet',
prescribed_generic_name: 'Generic 50mg tablet',
dispensed_drug_strength: '50 mg',
dispensed_ndc: '55555555555',
dispensed_quantity: 12,
dispensed_days_supply: 1
}
]
}
}
fetch('https://api.falsepill.com/v1/patient', {
method: 'PUT',
headers: {
Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"patient_token": "838a906bcc6e7671"
}
PUT https://api.falsepill.com/v1/patient
Begin the walkthrough by first creating a new Patient and Prescription in the system.
Simulating a Prescription in Sandbox
In the sandbox environment, prescriptions can be generated by passing in a simulation
object on the Create Patient endpoint. Within the simulation
object, there should be an attribute named newRx
, which houses an array.
Multiple prescriptions can be generated at once for a singular patient by populating the newRx
array with multiple values. If true is passed in within the newRx
array, a prescription will be generated with default sample properties.
These properties can be overridden with custom prescription information. The overridable fields are detailed below:
Field Name | Type | Default Value |
---|---|---|
medication_sig | String | "Take one Daily" |
prescriber | String | "Dr. P. Scribe" |
days_supply | String | "28" |
num_refills_filled | String | "0" |
refills_remaining | Integer | 2 |
quantity_remaining | Integer | 84 |
number_of_refills_allowed | Integer | 2 |
prescribed_drug_strength | String | "10 mg" |
prescribed_ndc | String | "51862009706" |
prescribed_dea_schedule | Integer | 0 |
prescribed_quantity | Integer | 42 |
prescribed_unit_text | String | "EA" |
prescribed_label_type | String | "Generic" |
prescribed_brand_name | String | "Brand Label" |
prescribed_written_name | String | "Brand Label 10 mg Tablet" |
prescribed_generic_name | String | "Generic 10 mg tablet" |
dispensed_drug_strength | String | "10 mg" |
dispensed_ndc | String | "51862009706" |
dispensed_quantity | Integer | 42 |
dispensed_dea_schedule | Integer | 0 |
dispensed_days_supply | Integer | 28 |
diagnosis_codes | Object | Diagnosis Codes |
Diagnosis Codes
Each prescription in the Truepill ecosystem is usually associated with at least one ICD code (International Statistical Classification of Diseases and Related Health Problems).
This can also be overridden with your own custom ICD10 or ICD9 codes by passing in an object for the diagnosis_codes
attribute. The object is composed as follows:
Field Name | Type | Default Value |
---|---|---|
icd10 | Array | ["Z30.09"] |
icd9 | Array | ["V85.30"] |
Simulated Notify Rx Webhook Events
Notify Rx Webhook Event of Prescription with Default Attributes
{
"timestamp": 1590784899,
"callback_type": "NOTIFY_RX",
"details": {
"medication_name": "Brand Label 10mg Tablet",
"prescriber": "Dr. P. Scribe",
"prescription_token": "7cb7d8ea418d",
"patient_token": "838a906bcc6e7671",
"location": "Hayward, CA"
}
}
Notify Rx Webhook Event of Prescription with Custom Attributes
{
"timestamp": 1590382349,
"callback_type": "NOTIFY_RX",
"details": {
"medication_name": "Generic Label 50mg Tablet",
"prescriber": "Dr. Strange",
"prescription_token": "e9549cca9639",
"patient_token": "838a906bcc6e7671",
"location": "Hayward, CA"
}
}
When the request object containing the simulation
object is submitted, a NOTIFY_RX
webhook event containing a generated prescription_token
will be created shortly afterward for each prescription. These prescriptions can be used for subsequent API calls via the prescription_token
.
Retrieving Patient's Prescriptions
Patient's Prescription Response Containing the Generated Prescriptions
{
"patient_token": "838a906bcc6e7671",
"prescriptions": [
{
"prescription_token": "7cb7d8ea418d",
"medication_name": "Brand Label 10mg Tablet",
"medication_sig": "Take one daily.",
"prescriber": "Dr. P. Scribe",
"date_written": "2020-05-18T19:59:56.000Z",
"refills_remaining": 2,
"current_rx_status_text": "On Hold",
"fillable": true,
"date_filled_utc": "2020-07-30T20:08:55.000Z"
},
{
"prescription_token": "e9549cca9639",
"medication_name": "Generic Label 50mg Tablet",
"medication_sig": "Take one every two hours",
"prescriber": "Dr. Strange",
"date_written": "2020-05-18T19:59:56.000Z",
"refills_remaining": 4,
"current_rx_status_text": "On Hold",
"fillable": true,
"date_filled_utc": "2020-07-30T20:08:55.000Z"
}
]
}
A patient’s prescriptions can also be collected by hitting the following API endpoint:
api.falsepill.com/v1/patient/{patient_token}/prescriptions
A quick check on this endpoint using the existing_patient
token will retrieve both prescriptions that were created — the default values prescription and the custom-made prescription.
Get a Prescription
Get Prescription Request
curl --request GET \
--url https://api.falsepill.com/v1/prescription/90aae1c9de75 \
--header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w'
fetch('https://api.falsepill.com/v1/prescription/90aae1c9de75', {
method: 'GET',
headers: {
Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w'
}
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"prescription": {
"date_written": "2020-05-18T19:59:56.000Z",
"days_supply": "28",
"is_refill": 0,
"last_filled_date": null,
"medication_sig": "Take one daily.",
"number_of_refills_allowed": 2,
"prescribed_brand_name": "Brand Label",
"prescribed_drug_strength": "10 mg",
"prescribed_generic_name": "Generic 10mg tablet",
"prescribed_ndc": "51862009706",
"prescribed_quantity": 42,
"prescribed_written_name": "Brand Label 10mg Tablet",
"prescriber": "Dr. P. Scribe",
"prescriber_address": {
"name": "Carol Danvers",
"company": null,
"street1": "12345 Avengers Rd",
"street2": null,
"city": "San Francisco",
"state": "CA",
"zip": "94402",
"country": "US",
"phone": "(800) 888-8888",
"email": "carol.danvers@avengers.com"
},
"prescriber_npi": "1497742761",
"prescriber_order_number": "11111111",
"quantity_remaining": 84,
"refills_remaining": 2,
"rx_number": "452702000",
"prescription_token": "7cb7d8ea418d",
"notes": "prescription notes",
"icd_codes": {
"icd10": ["Z30.09"],
"icd9": ["N94.6"]
},
"is_daw": false,
"dea_schedule": 0,
"date_filled_utc": "2020-07-30T20:08:55.000Z"
}
}
GET https://api.falsepill.com/v1/prescription/{prescription_token}
If a simulation is used on the Create Patient request, a prescription_token
will be generated on the Notify Rx Webhook event. The details of the prescription can then be retrieved with the Get Prescription API response.
Coverage Request
Sending Coverage Request with Custom Simulated Insurance Information
curl -X POST https://api.falsepill.com/v1/coverage_request \
--header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
-d '{
"patient_token": "838a906bcc6e7671",
"metadata": "metadata",
"simulation": {
"insurance": [
{
"cardholder_id": "123456789",
"group_number": "DEF9876543",
"bin": "555555",
"pcn": "PCN456",
"payer_name": "Custom Benefits",
"plan_type": "government",
"effective_date": "20200120",
"termination_date": "20201231"
}
]
}
}'
const body = {
patient_token: '838a906bcc6e7671',
metadata: 'metadata',
simulation: {
insurance: [
{
cardholder_id: '123456789',
group_number: 'DEF9876543',
bin: '555555',
pcn: 'PCN456',
payer_name: 'Custom Benefits',
plan_type: 'government',
effective_date: '20200120',
termination_date: '20201231'
}
]
}
}
fetch('https://api.falsepill.com/v1/coverage_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Sending Coverage Request to Simulate Error
curl -X POST https://api.falsepill.com/v1/coverage_request \
--header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
-d '{
"patient_token": "838a906bcc6e7671",
"metadata": "metadata",
"simulation": {
"error": "Patient social security number is not available"
}
}'
const body = {
patient_token: '838a906bcc6e7671',
metadata: 'metadata',
simulation: {
error: 'simulated error'
}
}
fetch('https://api.falsepill.com/v1/coverage_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"request_id": "skhsyq83rkd3uht9",
"timestamp": 1593452421,
"status": "success",
"details": {
"coverage_request_token": "skhsyq83rkd3uht9",
"message": "Your coverage request has been processed successfully."
}
}
POST https://api.falsepill.com/v1/coverage_request
For making a coverage request, the patient_token
will be used here.
An empty simulation
object can be passed in to simulate a successful Coverage request retrieval with default sample insurance values.
These insurance properties can be overridden with custom insurance information and should be specified in objects in an insurance
array within the simulation
object.
The overridable fields are detailed below:
Field Name | Type | Default Value |
---|---|---|
cardholder_id | String | "9151014609" |
group_number | String | "ABC123456789" |
bin | String | "999999" |
pcn | String | "ABC1234567" |
payer_name | String | "Omni Benefits" |
plan_type | String | "commercial" |
effective_date | String | "20200120" |
termination_date | String | "20201231" |
To simulate a rejected copay request (retrieving no insurance information for the patient), pass an error
string field within the simulation
object.
Simulated Coverage Request Webhook Events
When a Coverage request with simulations is successfully submitted in the sandbox environment, you will see any custom insurance information provided appear in the Coverage Request webhook event.
For the error scenario, you will retrieve null
for the insurances
field.
Successful Coverage Request Webhook Event with Custom Insurance
{
"request_id": "skhsyq83rkd3uht9",
"timestamp": 1596137150,
"callback_type": "COVERAGE",
"status": "success",
"details": {
"metadata": "metadata",
"patient_token": "838a906bcc6e7671",
"coverage_request_token": "skhsyq83rkd3uht9",
"insurances": [
{
"insurance_token": "9502a8162af55927",
"cardholder_id": "123456789",
"group_number": "DEF9876543",
"bin": "555555",
"pcn": "PCN456",
"payer_name": "Custom Benefits",
"plan_type": "government",
"effective_date": "2020-01-20T00:00:00.000Z",
"termination_date": "2020-12-31T00:00:00.000Z"
}
]
}
}
Error Coverage Request Webhook Event
{
"request_id": "skhsyq83rkd3uht9",
"status": "error",
"message": "Patient insurance is not found",
"callback_type": "COVERAGE",
"timestamp": 1567026972,
"details": {
"metadata": "cfe146",
"patient_token": "838a906bcc6e7671",
"coverage_request_token": "skhsyq83rkd3uht9",
"insurances": null
}
}
Insurance
Create Insurance Request
curl -X POST https://api.falsepill.com/v1/insurance \
--header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
-d patient_token ='838a906bcc6e7671' \
-d insurance='{
"cardholder_id": "ABC12345",
"rx_group": "006543",
"rx_bin": "997955",
"pcn": "TEST",
"phone_number": "(555) 555-1234"
}'
const body = {
patient_token: '838a906bcc6e7671',
insurance: {
cardholder_id: 'ABC12345',
rx_group: '006543',
rx_bin: '997955',
pcn: 'TEST',
phone_number: '(555) 555-1234'
}
}
fetch('https://api.falsepill.com/v1/insurance', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"request_id": "34e36c77fae25da9f8228e3b68b03bd2",
"status": "success",
"timestamp": 1590785394,
"details": {
"insurance_token": "1a9e3cdba512d862"
}
}
POST https://api.falsepill.com/v1/insurance
Create an insurance that this patient will have — using the same patient_token
.
This will be used for making a Copay request and Fill request.
Copay Request
Sending Copay Request to Simulate Successful Copay
curl -X POST https://api.falsepill.com/v1/copay_request \
--header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
-d patient_token='838a906bcc6e7671' \
-d insurance_token='["1a9e3cdba512d862"]' \
-d prescriptions='["7cb7d8ea418d"]' \
-d metadata='cfe146' \
-d simulation=`{}`
const body = {
patient_token: '838a906bcc6e7671',
insurance_token: ['1a9e3cdba512d862'],
prescriptions: ['7cb7d8ea418d'],
metadata: 'cfe146',
simulation: {}
}
fetch('https://api.falsepill.com/v1/copay_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Sending Copay Request to Simulate Rejected Copays
curl -X POST https://api.falsepill.com/v1/copay_request \
--header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
-d patient_token='4526d90a' \
-d insurance_token='["1a9e3cdba512d862"]' \
-d prescriptions='["7cb7d8ea418d"]' \
-d metadata='cfe146' \
-d simulation=`{
"error": {
"reject_codes": ["79", "75"]
}
}`
const body = {
patient_token: '4526d90a',
insurance_token: ['1a9e3cdba512d862'],
prescriptions: ['7cb7d8ea418d'],
metadata: 'cfe146',
simulation: {
error: {
reject_codes: ['79', '75']
}
}
}
fetch('https://api.falsepill.com/v1/copay_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"request_id": "c5e0baede8e5efe91c5811e2e67c17b7",
"status": "success",
"timestamp": 1590797192,
"details": {
"copay_request_token": "6eab1626c278dbeb",
"copay_request_prescriptions_tokens": [
{
"prescription_token": "7cb7d8ea418d",
"copay_request_prescription_token": "4a38fb2cdc79222d",
"status": "pending"
}
]
}
}
POST https://api.falsepill.com/v1/copay_request
The patient_token
, insurance_token
, and prescription_token
all will be used here to create this request.
When a simulation
object is passed in, the status of the Copay request will be updated and an appropriate webhook event will be generated and sent.
An empty simulation
object can be passed in to update the status of the Copay request to “completed” and generate a successful webhook event.
To simulate copay request rejections, pass in a simulation
object containing an error
object.
You can pass in specific claim rejection codes as they align to NCPDP Claim Codes to simulate receiving different claim codes on a prescription claim rejection. To do this, pass the reject_codes
field within the error
object containing an array of your NCPDP codes.
All of these claim codes will be applied to each prescription on the webhook event.
Simulated Copay Request Webhook Events
Successful Copay Request Webhook Event
{
"request_id": "c5e0baede8e5efe91c5811e2e67c17b7",
"timestamp": 1590797193,
"callback_type": "COPAY",
"status": "success",
"details": {
"metadata": "cfe146",
"message": "Here is a list of medications that were checked",
"patient_token": "838a906bcc6e7671",
"prescriptions": [
{
"prescription_token": "7cb7d8ea418d",
"status": "completed",
"copay_request_prescription_token": "4a38fb2cdc79222d",
"insurance_token": "36a0238257986729",
"next_fill_date": "2020-05-30T00:06:32.000Z",
"fill_number": 1,
"copay_amount": "13.37",
"days_supply": "28"
}
]
}
}
Error Copay Request Webhook Event
{
"request_id": "c5e0baede8e5efe91c5811e2e67c17b7",
"timestamp": 1590797193,
"callback_type": "COPAY",
"status": "success",
"details": {
"metadata": "cfe146",
"message": "Here is a list of medications that were checked",
"patient_token": "838a906bcc6e7671",
"prescriptions": [
{
"prescription_token": "7cb7d8ea418d",
"status": "rejected",
"copay_request_prescription_token": "4a38fb2cdc79222d",
"fill_number": 1,
"insurance_token": "36a0238257986729",
"claim_reject_codes": ["79", "75"]
}
]
}
}
Note that on the error Copay Request webhook event, the status will be success
— check the prescriptions
array to view the status of each prescription's claim that was run.
Fill Request
Sending Fill Request to Simulate a Completely Successful Order
curl -X POST https://api.falsepill.com/v1/fill_request \
-H "Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json" \
-d '{"patient_token": "838a906bcc6e7671",
"patient_payment_type": "insurance",
"insurances": [
{
"insurance_token": "1a9e3cdba512d862"
}
],
"medications": [
{
"prescription_token": "7cb7d8ea418d"
},
{
"prescription_token": "e9549cca9639",
}
],
"shipping_method": "fedex_ground",
"signature_confirmation": true,
"address_to_name": "David Doe",
"address_to_street1": "123 Some Lane",
"address_to_street1": "UNIT 301",
"address_to_city": "Los Angeles",
"address_to_state": "CA",
"address_to_zip": "94402",
"address_to_country": "US",
"address_to_phone": "(555) 555-5555",
"address_to_email": "example@gmail.com",
"metadata": "cfe146",
"patient_survey": {
"allergies": null,
"conditions": "Anxiety",
"medications": "Ibuprofen, Vitamin B 12"
},
"simulation": {}
}'
const body = {
patient_token: '838a906bcc6e7671',
patient_payment_type: 'insurance',
insurances: [
{
insurance_token: '1a9e3cdba512d862'
}
],
medications: [
{
prescription_token: '7cb7d8ea418d'
},
{
prescription_token: 'e9549cca9639'
}
],
shipping_method: 'fedex_ground',
signature_confirmation: true,
address_to_name: 'David Doe',
address_to_street1: '123 Some Lane',
address_to_street1: 'UNIT 301',
address_to_city: 'Los Angeles',
address_to_state: 'CA',
address_to_zip: '94402',
address_to_country: 'US',
address_to_phone: '(555) 555-5555',
address_to_email: 'example@gmail.com',
metadata: 'cfe146',
patient_survey: {
allergies: null,
conditions: 'Anxiety',
medications: 'Ibuprofen, Vitamin B 12'
},
simulation: {}
}
fetch('https://api.falsepill.com/v1/fill_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Sending Fill Request that Will Reject the Entire Order
curl -X POST https://api.falsepill.com/v1/fill_request \
-H "Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w" \
-H "Content-Type: application/json" \
-d '{"patient_token": "838a906bcc6e7671",
"patient_payment_type": "insurance",
"insurances": [
{
"insurance_token": "1a9e3cdba512d862"
}
],
"medications": [
{
"prescription_token": "7cb7d8ea418d"
},
{
"prescription_token": "e9549cca9639",
}
],
"shipping_method": "fedex_ground",
"signature_confirmation": true,
"address_to_name": "David Doe",
"address_to_street1": "123 Some Lane",
"address_to_street1": "UNIT 301",
"address_to_city": "Los Angeles",
"address_to_state": "CA",
"address_to_zip": "94402",
"address_to_country": "US",
"address_to_phone": "(555) 555-5555",
"address_to_email": "example@gmail.com",
"metadata": "cfe146",
"patient_survey": {
"allergies": null,
"conditions": "Anxiety",
"medications": "Ibuprofen, Vitamin B 12"
},
"simulation": {
"order": {
"error": "passing in error message"
}
}
}'
const body = {
patient_token: '838a906bcc6e7671',
patient_payment_type: 'insurance',
insurances: [
{
insurance_token: '1a9e3cdba512d862'
}
],
medications: [
{
prescription_token: '7cb7d8ea418d'
},
{
prescription_token: 'e9549cca9639'
}
],
shipping_method: 'fedex_ground',
signature_confirmation: true,
address_to_name: 'David Doe',
address_to_street1: '123 Some Lane',
address_to_street1: 'UNIT 301',
address_to_city: 'Los Angeles',
address_to_state: 'CA',
address_to_zip: '94402',
address_to_country: 'US',
address_to_phone: '(555) 555-5555',
address_to_email: 'example@gmail.com',
metadata: 'cfe146',
patient_survey: {
allergies: null,
conditions: 'Anxiety',
medications: 'Ibuprofen, Vitamin B 12'
},
simulation: {
order: {
error: 'passing in error message'
}
}
}
fetch('https://api.falsepill.com/v1/fill_request', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Successful Response
{
"request_id": "fill_request_991e90fa6b367cf72032",
"timestamp": 1590800011,
"status": "success",
"details": {
"message": "Your fill request has been processed successfully.",
"metadata": "cfe146"
}
}
This is the main endpoint used to create orders in the Truepill system. In this API call, patient_token
, insurance_token
, and prescription_token
can be passed in.
When a simulation
object is passed in, the status of the Fill request will be updated and the appropriate webhook event will be generated and sent.
An empty simulation
object can be passed in to update the status of the Fill request to complete, generating an order success webhook event along with three shipping webhook events containing information on the status of the delivery.
A simulation
object with an error
field containing a string can be passed in to update the status of the Fill request to rejected
and will only generate an error webhook event.
Simulated Fill Request Webhook Events
Successful Fill Request Webhook Event
{
"request_id": "fill_request_991e90fa6b367cf72032",
"timestamp": 1590800072,
"callback_type": "ORDER",
"status": "success",
"details": {
"metadata": "cfe146",
"message": "Your fill request was processed and is pending shipment.",
"date_filled": "N/A",
"medications": [
{
"medication_name": "Brand Label 10mg Tablet",
"dispensed_medication_name": "Brand Label 10mg Tablet",
"requested_medication_name": "prescription_token:7cb7d8ea418d",
"original_requested_prescription_token": "c8226924vf1a",
"days_supply": 28,
"quantity": 42,
"fill_number": "0",
"rx_number": "452793000",
"total_refills_allowed": 2,
"prescription_token": "7cb7d8ea418d",
"medication_token": "e2b176d61505",
"dispensed_ndc": "1234567890",
"remaining_refills": {
"total_remaining_refills": 2,
"total_quantity_remaining": 84
}
},
{
"medication_name": "Generic Label 50mg Tablet",
"dispensed_medication_name": "Generic Label 50mg Tablet",
"requested_medication_name": "prescription_token:e9549cca9639",
"original_requested_prescription_token": "c9876924vf2c",
"days_supply": 1,
"quantity": 12,
"fill_number": "2",
"rx_number": "452793000",
"total_refills_allowed": 2,
"prescription_token": "e9549cca9639",
"medication_token": "3fbsz9m613o9",
"dispensed_ndc": "0987654321",
"remaining_refills": {
"total_remaining_refills": 2,
"total_quantity_remaining": 48
}
}
],
"order_token": "3d2c77",
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000",
"tracking_number": "43904456187100000000000000",
"carrier": "usps",
"patient_token": "838a906bcc6e7671"
}
}
Error Fill Request Webhook Event
{
"request_id": "fill_request_991e90fa6b367cf72032",
"timestamp": 1591763649,
"callback_type": "ORDER",
"status": "error",
"details": {
"metadata": "cfe146",
"error_code": "passing in error message",
"description": "Simulated Error",
"message": "You requested a simulated error code of passing in error message",
"order_token": "3d2c77"
}
}
Shipment Webhook Event - Arrival to Facility
{
"request_id": "fill_request_991e90fa6b367cf72032",
"timestamp": 1590800102,
"callback_type": "SHIPMENT",
"status": "success",
"details": {
"metadata": "cfe146",
"status": "TRANSIT",
"message": "Your shipment has arrived at the USPS regional origin facility.",
"eta": "2020-06-02T00:54:31.838Z",
"tracking_number": "43904456187100000000000000",
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000",
"carrier": "usps"
}
}
Shipment Webhook Event - In Transit
{
"request_id": "fill_request_991e90fa6b367cf72032",
"timestamp": 1590800162,
"callback_type": "SHIPMENT",
"status": "success",
"details": {
"metadata": "cfe146",
"status": "TRANSIT",
"message": "In Transit, Arriving On Time",
"eta": "2020-06-02T00:54:31.838Z",
"tracking_number": "43904456187100000000000000",
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000",
"carrier": "usps"
}
}
Shipment Webhook Event - Delivered to Patient
{
"request_id": "fill_request_991e90fa6b367cf72032",
"timestamp": 1590800222,
"callback_type": "SHIPMENT",
"status": "success",
"details": {
"metadata": "cfe146",
"status": "DELIVERED",
"message": "Your shipment has been delivered at the destination mailbox.",
"eta": "2020-06-02T00:54:31.838Z",
"tracking_number": "43904456187100000000000000",
"tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=43904456187100000000000000",
"carrier": "usps"
}
}
It is important to note here that while the three simulated Shipment webhook events are provided — Arrival to Facility, In Transit, Delivered to Patient — there can be many more Shipment webhook events as the specified carrier sends notifications.
Insurance Fulfillment
Order Claim Webhook Event
{
"patient_token":"838a906bcc6e7671",
"patient_payment_type":"insurance",
"insurances":[
{
"insurance_token":"1a9e3cdba512d862"
}
],
"medications":[
{
"prescription_token":"7cb7d8ea418d"
},
{
"prescription_token":"e9549cca9639"
}
],
"shipping_method":"fedex_ground",
"signature_confirmation":true,
"address_to_name":"David Doe",
"address_to_street1":"123 Some Lane",
"address_to_street1":"UNIT 301",
"address_to_city":"Los Angeles",
"address_to_state":"CA",
"address_to_zip":"94402",
"address_to_country":"US",
"address_to_phone":"(555) 555-5555",
"address_to_email":"example@gmail.com",
"metadata":"cfe146",
"patient_survey":{
"allergies":null,
"conditions":"Anxiety",
"medications":"Ibuprofen, Vitamin B 12"
},
"simulation":{
"order":{
"claims":[
{
"copay_amount":10
},
{
"error_code":"someErrorCode",
"error_message":"This is an error message"
}
]
}
}
}
Order Claim webhook events can be simulated by providing a claims array in the simulation object’s order object.
Providing a copay_amount
in a claim
object will return that copay_amount
value in the Order Claim webhook event.
Providing an error_code
and error_message
in a claim
object will return the same error_code
and error_message
in the Order Claim webhook event.
The order in which you provide the claim simulation objects should correspond with the order in which you provide the medications objects.
In the example, the Order Claim webhook event will show that prescription_token
7cb7d8ea418d
has a copay_amount
value of 10
and prescription_token
e9549cca963
9 will contain the error_code
and error_message
.
Direct Transfer
Direct Transfer Request
curl -X POST https://api.falsepill.com/v1/direct_transfer \
--header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
--data '{
"patient_token": "838a906bcc6e7671",
"prescriber":{
"first_name":"Philip",
"last_name":"Scribe",
"npi":"1559977654",
"address":{
"name":"Philip Scribe",
"street1":"1234 Scribe St",
"city":"San Francisco",
"state":"CA",
"zip":"94109",
"country":"US",
"phone":"5035558923"
}
},
"transfer_from":{
"name":"Other Pharmacy, LLC",
"address":{
"name":"Other Pharmacy, LLC",
"street1":"123 Pharmacy Lane",
"city":"Los Angeles",
"state":"CA",
"zip":"97229",
"country":"US",
"phone":"5035558923",
"email":"pharmacy@example.com"
},
"id_number":"134123941",
"pharmacist":"Philip Scribe",
"dea":"DEA1234"
},
"transfer_to":{
"name":"Truepill",
"id_number":"1295182590",
"pharmacist":"Quynh Do"
},
"prescription":{
"medication_name":"COLD HEAD CONGESTION",
"quantity_written":"50",
"quantity_dispensed":"50",
"medication_sig":"50",
"written_date":"20200527",
"original_refills":12,
"quantity_transferred":11,
"refills_left":11,
"refills_transferred":11,
"number":"12345",
"can_substitute":true,
"prescribed_ndc":"12345678912",
"direct_transfer_url":"https://user:securelogin@www.assets.com/rx/saijhofiasjfoasoi2f.png"
},
"metadata": "5fc6c6",
"simulation": {}
}'
const body = {
patient_token: '838a906bcc6e7671',
prescriber: {
first_name: 'Philip',
last_name: 'Scribe',
npi: '1559977654',
address: {
name: 'Philip Scribe',
street1: '1234 Scribe St',
city: 'San Francisco',
state: 'CA',
zip: '94109',
country: 'US',
phone: '5035558923'
}
},
transfer_from: {
name: 'Other Pharmacy, LLC',
address: {
name: 'Other Pharmacy, LLC',
street1: '123 Pharmacy Lane',
city: 'Los Angeles',
state: 'CA',
zip: '97229',
country: 'US',
phone: '5035558923',
email: 'pharmacy@example.com'
},
id_number: '134123941',
pharmacist: 'Philip Scribe',
dea: 'DEA1234'
},
transfer_to: {
name: 'Truepill',
id_number: '1295182590',
pharmacist: 'Quynh Do'
},
prescription: {
medication_name: 'COLD HEAD CONGESTION',
quantity_written: '50',
quantity_dispensed: '50',
medication_sig: '50',
written_date: '20200527',
original_refills: 12,
quantity_transferred: 11,
refills_left: 11,
refills_transferred: 11,
number: '12345',
can_substitute: true,
prescribed_ndc: '12345678912',
direct_transfer_url: 'https://user:securelogin@www.assets.com/rx/saijhofiasjfoasoi2f.png'
},
metadata: '5fc6c6',
simulation: {}
}
fetch('https://api.falsepill.com/v1/direct_transfer', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
When a simulation
object is passed in, the status of the Direct Transfer is updated to have “successfully completed”, and a successful Direct Transfer webhook event will be generated.
The simulation
object can be passed in as an empty object on the request.
Direct Transfer Webhook Events
Successful Direct Transfer Webhook Event
{
"request_id": "c973dab3c2d8b8ea3ca2e30f14c72149",
"timestamp": 1591035261,
"callback_type": "DIRECT_TRANSFER",
"status": "success",
"details": {
"message": "Direct Transfer Accepted.",
"patient_token": "838a906bcc6e7671",
"direct_transfer_token": "8134a6ef49",
"prescription_token": "dfb23987c12e"
}
}
Error Direct Transfer Webhook Event
{
"request_id": "c973dab3c2d8b8ea3ca2e30f14c72149",
"timestamp": 1591035261,
"callback_type": "DIRECT_TRANSFER",
"status": "error",
"details": {
"message": "Direct Transfer Rejected. duplicate",
"patient_token": "838a906bcc6e7671",
"direct_transfer_token": "8134a6ef49",
"prescription_token": "dfb23987c12e"
}
}
A simulated Direct Transfer webhook event will be identical to a Direct Transfer webhook event in production. Note that the patient_token
returned will be identical to the one passed in on the request.
Transfer
Sending Transfer Request with Custom Rx Information to Simulate a Successful Transfer
curl -X POST https://api.falsepill.com/v1/direct_transfer \
--header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
--data '{
"patient_token": "838a906bcc6e7671",
"pharmacy_name": "Example Pharmacy",
"pharmacy_phone": "5555551234",
"prescriber_name": "Dr. Prescriber",
"prescriber_phone": "5555554567",
"metadata": "metadata",
"notes": "test notes",
"medications": [
"Sprintec Tablet",
"Spironolactone 10mg tablet"
],
"simulation": {}
}'
const body = {
patient_token: '838a906bcc6e7671',
pharmacy_name: 'Example Pharmacy',
pharmacy_phone: '5555551234',
prescriber_name: 'Dr. Prescriber',
prescriber_phone: '5555554567',
metadata: 'metadata',
notes: 'test notes',
medications: [
'Sprintec Tablet',
'Spironolactone 10mg tablet'
],
simulation: {}
}
fetch('https://api.falsepill.com/v1/transfer', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Sending Transfer Request to Simulate a Rejected Transfer
curl -X POST https://api.falsepill.com/v1/direct_transfer \
--header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
--data '{
"patient_token": "838a906bcc6e7671",
"pharmacy_name": "Example Pharmacy",
"pharmacy_phone": "5555551234",
"prescriber_name": "Dr. Prescriber",
"prescriber_phone": "5555554567",
"metadata": "metadata",
"notes": "test notes",
"medications": [
"Sprintec Tablet",
"Spironolactone 10mg tablet"
],
"simulation": {
"error": {
"reject_reason": "Test Rejecting Transfer",
"reject_reason_other": null
}
}
}'
const body = {
patient_token: '838a906bcc6e7671',
pharmacy_name: 'Example Pharmacy',
pharmacy_phone: '5555551234',
prescriber_name: 'Dr. Prescriber',
prescriber_phone: '5555554567',
metadata: 'metadata',
notes: 'test notes',
medications: [
'Sprintec Tablet',
'Spironolactone 10mg tablet'
],
simulation: {
error: {
reject_reason: 'Test Rejecting Transfer',
reject_reason_other: null
}
}
}
fetch('https://api.falsepill.com/v1/transfer', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
When a simulation
object is passed in, the status of the Transfer is updated to have been "successfully completed", and a successful Transfer webhook event will be generated and sent.
The simulation
object can be passed in as an empty object on the request. Prescriptions with default generic information will be created for each medication that is passed in on the request.
To simulate a Transfer rejection, pass an error
object within the simulation
object containing reject_reason
and error_code
, and optionally reject_reason_other
. The information provided in these two fields will be propagated back on the error Transfer webhook event.
Transfer Request with Medication-Specific Scenarios
curl -X POST https://api.falsepill.com/v1/direct_transfer \
--header 'Authorization: ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w' \
--data '{
"patient_token": "838a906bcc6e7671",
"pharmacy_name": "Example Pharmacy",
"pharmacy_phone": "5555551234",
"prescriber_name": "Dr. Prescriber",
"prescriber_phone": "5555554567",
"metadata": "metadata",
"notes": "test notes",
"medications": [
"Sprintec Tablet",
"Spironolactone 10mg tablet",
"Ibuprofen"
],
"simulation": {
"medications": ]
{
"medication_sig": "Take one every two hours",
"prescriber": "Dr. Strange",
"days_supply": "1",
"num_refills_filled": "2",
"refills_remaining": 4,
"quantity_remaining": 48,
"number_of_refills_allowed": 4,
"prescribed_drug_strength": "50 mg",
"prescribed_ndc": "55555555555",
"prescribed_quantity": 12,
"prescribed_unit_text": "EA",
"prescribed_label_type": "Generic",
"prescribed_brand_name": "Generic Label",
"prescribed_written_name": "Generic Label 50mg Tablet",
"prescribed_generic_name": "Generic 50mg tablet",
"dispensed_drug_strength": "50 mg",
"dispensed_ndc": "55555555555",
"dispensed_quantity": 12,
"dispensed_days_supply": 1
},
true,
{
error: {
"error_code": "RX_NONEXISTANT",
"rejection_reason": "No Prescription exists at pharmacy",
"rejection_reason_other": "Patient only has expired prescription"
}
}
}
}'
const body = {
patient_token: '838a906bcc6e7671',
pharmacy_name: 'Example Pharmacy',
pharmacy_phone: '5555551234',
prescriber_name: 'Dr. Prescriber',
prescriber_phone: '5555554567',
metadata: 'metadata',
notes: 'test notes',
medications: [
'Sprintec Tablet',
'Spironolactone 10mg tablet',
'Ibuprofen'
],
simulation: {
medications: [
{
medication_sig: 'Take one every two hours',
prescriber: 'Dr. Strange',
days_supply: '1',
num_refills_filled: '2',
refills_remaining: 4,
quantity_remaining: 48,
number_of_refills_allowed: 4,
prescribed_drug_strength: '50 mg',
prescribed_ndc: '55555555555',
prescribed_quantity: 12,
prescribed_unit_text: 'EA',
prescribed_label_type: 'Generic',
prescribed_brand_name: 'Generic Label',
prescribed_written_name: 'Generic Label 50mg Tablet',
prescribed_generic_name: 'Generic 50mg tablet',
dispensed_drug_strength: '50 mg',
dispensed_ndc: '55555555555',
dispensed_quantity: 12,
dispensed_days_supply: 1
},
true,
{
error: {
error_code: "RX_NONEXISTANT",
rejection_reason: 'No Prescription exists at pharmacy',
rejection_reason_other: 'Patient only has expired prescription'
}
}
]
}
}
fetch('https://api.falsepill.com/v1/transfer', {
method: 'POST',
headers: {
Authorization: 'ApiKey tp_test_key_dwXajyzag6mhXQi1z0Gq9w',
'Content-Type': 'application/json'
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(response => console.log(response))
Medication-Specific Simulations
The Transfer simulation also allows for simulating events at the medication level. This is done by passing in a medications
array within the simulation
object.
When a simulation
object is passed in as an empty object, generic prescriptions are created for each medication that is passed in the request. This can be overridden with custom prescription information.
You can also choose to use override only some prescriptions in a transfer, and use the default prescription information on others. To use the default prescription information, simply pass true
in the medications
array.
The following properties can be overridden with custom prescription information:
Field Name | Type | Default Value |
---|---|---|
medication_sig | String | "Take one Daily" |
prescriber | String | "Dr. P. Scribe" |
prescriber_npi | String | "1497742761" |
days_supply | String | "28" |
num_refills_filled | String | "0" |
refills_remaining | Integer | 2 |
quantity_remaining | Integer | 84 |
number_of_refills_allowed | Integer | 2 |
prescribed_drug_strength | String | "10 mg" |
prescribed_ndc | String | "51862009706" |
prescribed_dea_schedule | Integer | 0 |
prescribed_quantity | Integer | 42 |
prescribed_unit_text | String | "EA" |
prescribed_label_type | String | "Generic" |
prescribed_brand_name | String | "Brand Label" |
prescribed_written_name | String | "Brand Label 10 mg Tablet" |
prescribed_generic_name | String | "Generic 10 mg tablet" |
dispensed_drug_strength | String | "10 mg" |
dispensed_ndc | String | "51862009706" |
dispensed_quantity | Integer | 42 |
dispensed_dea_schedule | Integer | 0 |
dispensed_days_supply | Integer | 28 |
date_written | Date | Generated real-time |
diagnosis_codes | Object | Diagnosis Codes |
You can also simulate a medication-level rejection within a Transfer. The overall Transfer will still be approved but, for example, one out of three medications can be rejected during the transfer process.
To do this, pass an object containing an error
object much like the error
object at the root level of the simulation to simulate rejecting an entire Transfer.
This error
object also accepts the reject_reason
and reject_reason_other
fields. This information is propagated back in the Transfer webhook event within the medications
array.
Transfer Diagnosis Codes
Each prescription in the Truepill ecosystem is usually associated with at least one ICD code (International Statistical Classification of Diseases and Related Health Problems).
This can also be overridden with your own custom ICD10 or ICD9 codes by passing in an object for the diagnosis_codes
attribute. The object is composed as follows:
Field Name | Type | Default Value |
---|---|---|
icd10 | Array | ["Z30.09"] |
icd9 | Array | ["V85.30"] |
Transfer Webhook Events
Successful Transfer Webhook Event
{
"request_id": "ae030bc915541154932aad14e622c292",
"timestamp": 1598311289,
"callback_type": "TRANSFER",
"status": "success",
"details": {
"metadata": "metadata",
"message": "Here is a list of medications that were successfully transferred",
"patient_token": "838a906bcc6e7671",
"medications": [
{
"transfer_medication_id": "39e6856f55e1e9df",
"transfer_medication_token": "39e6856f55e1e9df",
"requested_medication_name": "Sprintec Tablet",
"last_filled_date": "No Data",
"prescriber": "Dr. Prescriber",
"medication_sig": "Take one daily.",
"prescription_token": "de6f66b44b67",
"medication_name": "Sprintec Tablet",
"num_refills_remaining": 2,
"quantity": 42,
"days_supply": 28
},
{
"transfer_medication_id": "debcadfe3b2dd482",
"transfer_medication_token": "debcadfe3b2dd482",
"requested_medication_name": "Spironolactone 10mg tablet",
"last_filled_date": "No Data",
"prescriber": "Dr. Prescriber",
"medication_sig": "Take one daily.",
"prescription_token": "a1607c465f83",
"medication_name": "Spironolactone 10mg tablet",
"num_refills_remaining": 2,
"quantity": 42,
"days_supply": 28
}
]
}
}
Error Transfer Webhook Event
{
"request_id": "ae030bc915541154932aad14e622c292",
"timestamp": 1598311289,
"callback_type": "TRANSFER",
"status": "error",
"details": {
"metadata": "metadata",
"message": "Test Rejecting Transfer",
"patient_token": "838a906bcc6e7671"
}
}
Successful Transfer Webhook Event with Medication-Level Information
{
"request_id": "ae030bc915541154932aad14e622c292",
"timestamp": 1598311289,
"callback_type": "TRANSFER",
"status": "success",
"details": {
"metadata": "metadata",
"message": "Here is a list of medications that were successfully transferred",
"patient_token": "838a906bcc6e7671",
"medications": [
{
"transfer_medication_id": "39e6856f55e1e9df",
"transfer_medication_token": "39e6856f55e1e9df",
"requested_medication_name": "Sprintec Tablet",
"last_filled_date": "No Data",
"prescriber": "Dr. Strange",
"medication_sig": "Take one every two hours",
"prescription_token": "de6f66b44b67",
"medication_name": "Generic Label 50mg Tablet",
"num_refills_remaining": 4,
"quantity": 48,
"days_supply": 1
},
{
"transfer_medication_id": "debcadfe3b2dd482",
"transfer_medication_token": "debcadfe3b2dd482",
"requested_medication_name": "Spironolactone 10mg tablet",
"last_filled_date": "No Data",
"prescriber": "Dr. Prescriber",
"medication_sig": "Take one daily.",
"prescription_token": "a1607c465f83",
"medication_name": "Spironolactone 10mg tablet",
"num_refills_remaining": 2,
"quantity": 42,
"days_supply": 28
},
{
"transfer_medication_id": "debcadfe3b2dd482",
"transfer_medication_token": "debcadfe3b2dd482",
"requested_medication_name": "Spironolactone 10mg tablet",
"rejection_message": "Patient only has expired prescription"
}
]
}
}
Note that in the last Transfer webhook event example containing medication-level information, the medications
array returns:
1. A medication with custom Rx information, supplied in the simulation
object on the request.
2. A medication with the default Rx information generated.
3. A medication simulated to be rejected.
Simulated Consults
In order to simulate consults, an unassigned consult must first be created.
Simulate Complete Status Status flow from unassigned" -> "assigned" -> "review" -> "completed
curl --location --request PATCH 'https://api.falsepill.com/consults/v0/consult/64d65f1382359c85170c2f6f/simulate' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey {INSERT_AUTH_KEY}' \
--data '{
"status": "completed",
"completionState": ["rx_prescribed"],
"rx_ndc": "00069-1085-30",
"icd10": "U07.1",
"notes": "Patient is not very healthy",
"providerAnswers": {
"TEST_RESULT": 0,
"MEDICATION": 3,
"REFERRAL": 2,
"RATIONALE": 2
}
}'
{
"newStatus": "completed",
"statusflowFromTo": ["unassigned", "assigned", "review", "completed"]
}
Simulate Issue Flow It is important to note that consult statuses flow from "unassigned" -> "assigned" -> "issue" -> "resolve" -> "review" -> "completed"
curl --location --request PATCH 'https://api.falsepill.com/consults/v0/consult/64d65f1382359c85170c2f6f/simulate' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey {INSERT_AUTH_KEY}' \
--data '{
"status": "issue",
"issueReason": "some reason"
}'
{
"newStatus": "issue"
}
Simulate Issue Rejected Status
curl --location --request PATCH 'https://api.falsepill.com/consults/v0/consult/64d65f1382359c85170c2f6f/simulate' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey {INSERT_AUTH_KEY}' \
--data '{
"status": "rejected",
"rejectReason":"some rejection reason"
}'
{
"newStatus": "rejected"
}
Simulate Issue Completed Status
curl --location --request PATCH 'https://api.falsepill.com/consults/v0/consult/64d65f1382359c85170c2f6f/simulate' \
--header 'Content-Type: application/json' \
--header 'Authorization: ApiKey {INSERT_AUTH_KEY}' \
--data '{
"status": "issueCompleted",
"completionState": ["rx_prescribed"],
"icd10":"U07.1",
"issueReason": "some reason"
}'
{
"newStatus": "completed",
"statusFlowFromTo": [
"unassigned",
"assigned",
"issue",
"resolve",
"review",
"completed"
]
}