EMR Recommendations

Lastest update 2023/08/29

Our EMR recommendation services are designed to allow practitioners to send their patients recommendations from inside the EMR software. Our EMR API provides 2 methods to obtain authorization tokens, showcasing our commitment to data security. Our platform also offers comprehensive product information and endpoints for sending and listing recommendations and their statuses.

Authorization Code

Description

Redirect the user to an authorization URL that prompts them to login and grant access to your EMR software. This URL will return an authorization code that you can use to fetch a token for that user. The code is valid for five minutes after generation and can only be used to generate a token once.

Authorization

Basic authorization header, username and password provided by XYMOGEN

Request Values

client_id XYMOGEN provided username for your EMR account
redirect_uri A URI on your end that the authorization code and practitioner email will be returned to
State Optional parameter to help protect against CSRF requests

Authorization URL

Copy to clipboard
https://testservices.wholescripts.com/api/EMR/authorize?client_id={username}&redirect_uri={URI}&state=12345

Response Example

Success:

Copy to clipboard
{URI}?code=y8b35g12763b45e7a91caebe54bf02df&email=testemail@xymogen.com&state=12345

Failure:

Copy to clipboard
{URI}?error=access_denied

Token

Description

Pass a practitioner's email and password for wholescripts.com to verify they are valid. If validated, a bearer token will be returned. This token is specific to the practitioner's account and is required for authentication in applicable services. This service is also used to refresh an expired token using the provided refresh_token value.

Authorization

Basic authorization header, username and password provided by XYMOGEN

Request Values

grant_type This value should be "password" if requesting a new token via the password method, "authorization_code" if using the authorization code method, or "refresh_token" if refreshing an existing token
username The practitioner account's email address, only needed for a "password" grant_type
password The account's wholescripts.com password, only needed for a "password" grant_type
code Authoriazation code received from the Authorization Code authentication method, only needed for an "authorization_code" grant_type
refresh_token The refresh token required for the "refresh_token" grant_type

Request URL

Copy to clipboard
GET https://testservices.wholescripts.com/api/EMR/Token?grant_type=password&username={username}&password={password}

or

Copy to clipboard
curl https://testservices.wholescripts.com/api/EMR/Token -X POST -u "username:password" -d "grant_type=password" -d "username={username}" -d "password={password}"

Response Examples

Success:

Copy to clipboard
{
    "access_token":"{{access token}}",
    "token_type":"bearer",
    "expires_in":900,
    "refresh_token":"{{refresh token}}"
}

Fail (HTTP 400 Bad Request):

Copy to clipboard
{
    "error":"invalid_request",
    "error_description":"Request was missing the 'username' parameter.",
}

Logout

Description

Disable a practitioner's authorization token and refresh token received either from the Token endpoint or the Authorization Code method.

Authorization

Bearer token authorization header, received from the Token service

Request URL

Copy to clipboard
GET https://testservices.wholescripts.com/api/EMR/Logout

Response Examples

Success:

Copy to clipboard
{
    "success": true,
    "msg": ""
}

Fail (HTTP 401 Unathorized):

Copy to clipboard
{
    "error": "invalid_grant",
    "error_description": "The access token is invalid"
}

Brand List

Description

Get a complete list of available product brand names.

Authorization

Basic authorization header, username and password provided by XYMOGEN

Request URL

Copy to clipboard
GET https://testservices.wholescripts.com/api/EMR/BrandList

Response Example

Copy to clipboard

[
    "XYMOGEN®",
    "WholeScripts"
]

Category List

Description

Get a complete list of available product category names.

Authorization

Basic authorization header, username and password provided by XYMOGEN

Request URL

Copy to clipboard
GET https://testservices.wholescripts.com/api/EMR/CategoryList

Response Example

Copy to clipboard

[
    "Adrenal Support",
    "Antioxidant Activity",
    "Blood Sugar Support",
    "Body Composition",
    "Bone Health Support",
    "Cardiovascular Support",
    "Cell-Life Regulation",
    "Cytokine Balance Support",
    "Detoxification",
    "Essential Fatty Acids",
    "Female Health",
    "Gastrointestinal Support",
    "Immune System Support",
    "Joint & Muscle Support",
    "Liver Support",
    "Male Health",
    "Multivitamins & Minerals",
    "Neurologic & Cognitive",
    "Probiotics",
    "Relaxation & Sleep",
    "Sports Nutrition",
    "Thyroid Support"
]

Product List

Description

Get a complete list of available products used in sending recommendations.

Authorization

Basic authorization header, username and password provided by XYMOGEN

Request Values

search Pass a string to filter products returned by name, description, brand, category, or SKU (optional)
instockonly Pass "true" or "false"; If true, products with 0 or less quantity will not be returned
brandname Pass a string to filter products by brand name.

Request URL

Copy to clipboard
GET https://testservices.wholescripts.com/api/EMR/ProductList

Response Values

ProductName Product name
Sku Product sku
MedPaxSku Associated MedPax product sku
MedPaxDetails Details about the associated MedPax product (null if no related MedPax product):
  • Quantity – available inventory
  • WholesalePrice
  • RetailPrice
  • Name
  • GenericName – name to be used for Private Label MedPax boxes
Categories Comma delimited string of product categories
Quantity Current available quantity
ReleaseDate The last date and time (UTC) that the product was updated
WholesalePrice Wholesale price (decimal)
RetailPrice Retail price (decimal)
OnlineMAP Minimum Advertised Price (MAP). Only applies to XYMOGEN brand products.
UPC Product's UPC code
Count Product count per unit
Flavor Product flavor (if available)
DescriptionShort Short product description
DescriptionFull Full product description, including HTML markup
Brand Product brand
Weight Product weight
ProductImage URL to product image
SupplementFactsHTML HTML for product supplement facts
DefaultDosing Array of objects that represent the recommended daily dosing for the product (Time and Qty)
DRS URL to product DRS document
CountUnit Unit of measure for the Count value
WeightUnit Unit of measure for the Weight value
Warnings Array of string warnings for the product:
  • Prop65Excluded – cannot be sold in CA
  • Prop65BirthDefect – birth defect warning for CA
  • Prop65Cancer – cancer warning for CA
  • Prop65BirthDefectCancer – birth defect and cancer warning for CA

Response Example

Copy to clipboard
[
    {
        "productName": "NeurophX DPN® 60 Capsules",
        "sku": "000000000300001012",
        "medPaxSku": "000000000200000200",
        "medPaxDetails": {
            "quantity": 8394,
            "wholesalePrice": 0.8000,
            "retailPrice": 1.3400,
            "name": "NeurophX DPN® Capsules",
            "genericName": "B FOLATE WITH ALA"
        },
        "categories": "All",
        "quantity": 1064,
        "releaseDate": "2021-04-01T06:08:00.32",
        "wholesalePrice": 45.0300,
        "retailPrice": 75.2000,
        "upc": "871149004941",
        "count": "60",
        "flavor": "",
        "descriptionShort": "",
        "descriptionFull": "
NeurophX DPN® is an orally administered medical food* for use only under the supervision of a physician for patients with metabolic nutritional impairments associated with peripheral neuropathy and microvascular complications.
",
        "brand": "XYMOGEN®",
        "weight": 2.4000,
        "productImage": "https://www.wholescripts.com/images/thumbs/0006863_neurophx-dpn-60-capsules.png",
        "supplementFactsHTML": "",
        "defaultDosing": [
            {
                "time": "AM",
                "qty": 1
            },
            {
                "time": "PM",
                "qty": 1
            }
        ],
        "drs": "https://www.wholescripts.com/ProductAttachments/DownloadFile/CB53FA66-6A65-4162-A7CC-46556A2C593E",
        "countUnit": "Capsules",
        "weightUnit": "OZ",
        "warnings": [
            "Prop65BirthDefectCancer"
        ]
    }
]

Product

Description

Get a single product's information with the same result format as the ProductList service.

Authorization

Basic authorization header, username and password provided by XYMOGEN

Request Values

Sku Product sku

Request URL

Copy to clipboard
GET https://testservices.wholescripts.com/api/EMR/Product/{sku}

Response Format

See ProductList

ProductImage

Description

Get a product's image as represented by a byte array.

Authorization

Basic authorization header, username and password provided by XYMOGEN

Request Values

Sku Product sku

Request URL

Copy to clipboard
GET https://testservices.wholescripts.com/api/EMR/ProductImage/{sku}

Response Examples

Success:

Copy to clipboard
{
    "mimeType":"image/png",
    "fileBytes":"{{byte array data}}"
}

Fail:

Copy to clipboard
{
    "mimeType": null,
    "fileBytes": null
}

ProductDRS

Description

Get a product's DRS document as represented by a byte array.

Authorization

Basic authorization header, username and password provided by XYMOGEN

Request Values

Sku Product sku

Request URL

Copy to clipboard
GET https://testservices.wholescripts.com/api/EMR/ProductDRS/{sku}

Response Examples

Success:

Copy to clipboard
{
    "mimeType":"application/pdf",
    "fileBytes":"{{byte array data}}"
}

Fail:

Copy to clipboard
{
    "mimeType": null,
    "fileBytes": null
}

PractitionerReferralCodes

Description

Get a list of available referral codes for a given practitioner, including discount percentage and access level for accounts created using each.

Authorization

Bearer token authorization header, value received from the Token service

Request URL

Copy to clipboard
GET https://testservices.wholescripts.com/api/EMR/PractitionerReferralCodes

Response Values

ref_code Referral code
ref_name Referral last name
discount Discount percentage applied to accounts created with this referral code
access_level Website access level applied to accounts created with this referral code

Response Example

Copy to clipboard
[
    {
        "ref_code":"TESTCODE",
        "ref_name":"TESTNAME",
        "discount":15.0,
        "access_level":"Full"
    }
]

PractitionerPatients

Description

Get a list of patients for the authenticated practitioner.

Authorization

Bearer token authorization header, value received from the Token service

Request Values

email Pass as a URL parameter to search for a specific patient record by email (optional)

Request URL

Copy to clipboard
GET https://testservices.wholescripts.com/api/EMR/PractitionerPatients

Response Values

Patients List of patient objects including the following values:
  • Email
  • FirstName
  • LastName
Count Number of patient records returned (int)
Success Boolean indicating success or failure of the result (bool)
Msg Message returned describing the error if the Success value is false

Response Examples

Patients found:

Copy to clipboard
{
    "patients": [
        {
            "email": "05030909@xymogen.com",
            "firstName": "test05030909",
            "lastName": "test"
        }
    ],
    "count": 1,
    "success": true,
    "msg": ""
}

No patients found:

Copy to clipboard
{
    "patients": [],
    "count": 0,
    "success": true,
    "msg": "No patients found"
}

When passing a specific patient email:

Copy to clipboard
{
    "patients": [],
    "count": 0,
    "success": false,
    "msg": "Patient is registered under a different practitioner"
}

Private Label Product List

Description

Get a list of available private label products for a given practitioner, a list of all available MedPax pills, and a list of all available private label cartons.

Authorization

Bearer token authorization header, value received from the Token service

Request URL

Copy to clipboard
GET https://testservices.wholescripts.com/api/EMR/PrivateLabelProductList

Response Values

privateLabelProducts A list of available private label products including the following values
  • privateLabelName
  • sku
  • quantity
  • wholesalePrice
  • retailPrice
  • upc
  • count
  • flavor
  • weight
  • countUnit
  • weightUnit
  • isOnBackorder
medPaxPills A list of available MedPax pills including the following values
  • sku
  • genericName
  • privateLabelName
privateLabelCartons A list of available private label cartons including the following values
  • sku
  • name
  • cartonImage
  • quantity

Response Example

Copy to clipboard

{
    "privateLabelProducts": [
        {
        "privateLabelName": "3PL Probiotics 30 C",
        "sku": "000000000300095860",
        "quantity": 0,
        "wholesalePrice": 21.57,
        "retailPrice": 41.1,
        "upc": "",
        "count": "30",
        "flavor": "",
        "weight": 1.6,
        "countUnit": "Capsules",
        "weightUnit": "OZ",
        "isOnBackorder": false
        },
        {
        "privateLabelName": "3PL Mood formula 60 C",
        "sku": "000000000300095859",
        "quantity": 0,
        "wholesalePrice": 20.35,
        "retailPrice": 39.53,
        "upc": "",
        "count": "60",
        "flavor": "",
        "weight": 2.4,
        "countUnit": "Capsules",
        "weightUnit": "OZ",
        "isOnBackorder": false
        }
    ],
    "medPaxPills": [
        {
        "sku": "000000000100000873",
        "genericName": "BIOTIN PLUS",
        "privateLabelName": "Beauty"
        },
        {
        "sku": "000000000200000131",
        "genericName": "FLORA SUPPORT",
        "privateLabelName": ""
        }
    ],
    "privateLabelCartons": [
        {
        "sku": "000000000200087661",
        "name": "Wellness Clinic",
        "cartonImage": "https://www.wholescripts.com/images/default-image.png",
        "quantity": 0
        }
    ]
}

Recommendations (POST)

Description

Create a new recommendation.

Authorization

Bearer token authorization header, value received from the Token service

Request Values

PractitionerEmail Practitioner's account email that is sending the recommendation (string(1000))
EmailTo Patient email the recommendation will be sent to (string(1000))
PatientFirstName Patient's first name (string(500))
PatientLastName Patient's last name (string(500))
Notes Any notes that should be attached to the recommendation (string(500))
ref_code Referral code if sending the recommendation to a new patient (string(48))
ref_name Referral name, again if sending to a new patient (string(48))
Items Array of items included in the recommendation:
  • Sku – Product sku, or MedPax box sku if the line is a MedPax box
  • Quantity – Product quantity
  • Dosing – Pipe delimited string for product dosing ([Quantity]-[Time]). Available times include AM, PM, Bedtime, and Daily. If omitted, the product's default dosage will be used
  • Notes – Product specific notes (string(1000))
  • MedPaxName – If sending a MedPax box, this represents the MedPax box's name that will print on each packet (if not passed, the patient's name will be used) (string(500))
  • MedPaxPills – Array of products to include in the MedPax box:
    • Sku – Pill's sku
    • Quantity – Pill quantity
    • ItemTime – AM, PM, Bedtime, Daily, AM with food, PM with food, Daily with food, Bedtime with food, AM without food, PM without food, Daily without food, or Bedtime without food
  • ItemDuration – Ongoing, As Needed, 1 Week, 2 Weeks, 3 Weeks, or 4 Weeks
SendEmail Send false to prevent WholeScripts from sending out a notification email to the receiving patient account (Boolean, defaults to true).

Request URL

Copy to clipboard
POST https://testservices.wholescripts.com/api/EMR/Recommendations

Request Payload Example

Copy to clipboard
{
    "PractitionerEmail": "webtest@xymogen.com",
    "EmailTo": "Miguel.Test@mctest.com",
    "PatientFirstName": "McTest",
    "PatientLastName": "TestLast",
    "Notes": "test notes",
    "ref_code": "test",
    "ref_name": "test",
    "Items": [
        {
            "Sku": "000000000300005343",
            "Quantity": 1,
            "Dosing": "1-AM|2-PM",
            "Notes": "",
            "MedPaxName": "",
            "MedPaxPills": [],
            "ItemDuration": "Ongoing"
        },
        {
            "Sku": "000000000200000633",
            "Quantity": 1,
            "Dosing": "",
            "Notes": "",
            "MedPaxName": "Test MPX Order",
            "MedPaxPills": [
                {
                    "Sku": "000000000200000148",
                    "Quantity": 2,
                    "ItemTime": "AM"
                },
                {
                    "Sku": "000000000200000230",
                    "Quantity": 2,
                    "ItemTime": "PM"
                },
                {
                    "Sku": "000000000100000879",
                    "Quantity": 1,
                    "ItemTime": "Bedtime without food"
                }
            ],
            "ItemDuration": "As Needed"
        }
    ],
    "SendEmail": false
}

Response Example

Copy to clipboard
{
    "recommendationId": 12345,
    "patientLink": "https://www.wholescripts.com/Recommendation/MyRecommendations/12345",
    "success": true,
    "msg": ""
}

Recommendations (GET)

Description

Get a list of recommendations by patient email. Response values mirror what is submitted in the POST Recommendations service when creating a recommendation, with unique identifiers and names added.

Authorization

Bearer token authorization header, value received from the Token service

Request Values

email Patient's account email

Request URL

Copy to clipboard
GET https://testservices.wholescripts.com/api/EMR/Recommendations/{email}

Response Values

Status Possible values:
  • Sent*
  • Draft
  • Patient Deleted
  • Patient Viewed*
  • Practitioner Canceled
  • Patient Ordered*
  • Disabled
*patient viewable

Response Example

Copy to clipboard
{
    "recommendations": [
        {
            "id": 12345,
            "practitionerEmail": "webtest@xymogen.com",
            "emailTo": "test@test.com",
            "patientFirstName": "Joe",
            "patientLastName": "Tester",
            "dateSentUtc": "2020-04-17T16:56:35.817",
            "notes": "test notes",
            "status": "Sent",
            "ref_code": "",
            "ref_name": "",
            "items": [
                {
                    "sku": "000000000300005343",
                    "name": "XymoZyme 60 C",
                    "quantity": 1,
                    "dosing": "1-AM|1-PM",
                    "notes": "",
                    "medPaxName": "",
                    "medPaxPills": [],
                    "itemDuration": "Ongoing"
                },
                {
                    "sku": "000000000200000633",
                    "name": "",
                    "quantity": 1,
                    "dosing": null,
                    "notes": "",
                    "medPaxName": "MedPax Order",
                    "itemDuration": "4 Weeks",
                    "medPaxPills": [
                        {
                            "sku": "000000000100000873",
                            "name": "RegeneMax® Plus Capsules",
                            "quantity": 1,
                            "itemTime": "AM"
                        },
                        {
                            "sku": "000000000200000158",
                            "name": "OncoPLEX™ Capsules",
                            "quantity": 1,
                            "itemTime": "AM"
                        }
                    ]
                }
            ]
        }
    ],
    "success": true,
    "msg": ""
}

Recommendation (GET)

Description

Get a single recommendation by Id.

Authorization

Bearer token authorization header, value received from the Token service

Request Values

id Recommendation Id returned from the Recommendations (POST) service.

Request Format

Copy to clipboard
GET https://testservices.wholescripts.com/api/EMR/Recommendation/{id}

Response Values and Format

Same response as Recommendations (GET), but will only return one recommendation that matches the passed Id.

Endpoints:

Authorization Code Token Logout BrandList CategoryList ProductList Product ProductImage ProductDRS PractitionerReferralCodes PractitionerPatients PrivateLabelProductList Recommendations (POST) Recommendations (GET) Recommendation (GET)