NAV
json

PioneerRx Incoming MTM Actions API

This document outlines the API to send PioneerRx MTM actions to associate with patients in PioneerRx.

Technology partners can implement a web method and or FTP data file as described below for PioneerRx to consume.

MTM (Medication Therapy Management) Actions are the preferred method within PioneerRx to manage and document patient care related activities. MTM actions have a status, due date and a completed date.

It is envisioned that this interface will be used to notify PioneerRx users of work to be performed e.g. “call patient by X date” by submitting open MTM actions with a due date, and to notify of work already performed e.g. “performed therapy review with patient” by submitting completed MTM actions.

The API also provides ability to include a URL to deep link into vendor system if needed.

Change Log

Version Date Change Comments
3 10/24/2016 Added ActionTypeID ActionTypeID will allow partners to categorize actions in greater detail
3 02/20/2017 Added Comment to CompletedDate Field Added details about how MTM Action Status Type is set
3 09/11/2020 PatientState Typo Fixed typo for PatientState field

Connectivity

Web Service

At predetermined intervals PioneerRx will poll a HTTPS web method expecting a JSON response. It is assumed that the feed will be centrally managed, with ability to receive updates for a given Patient, Location, or all locations.

The api will use HTTPS Web Services to communicate between the 2 systems. Insecure http traffic will not be allowed.

We will use “application/json; charset=utf-8” for the ContentType Header.

When we receive a Http Status Code of 200, we will treat the response as successful and everything else will be treated as an error or failure.

FTP Data File

A nightly data file can be loaded to an FTP server hosted by the Technology Partner. PioneerRx will download this file and process.

Communication is via SFTP or FTPS will be used. Basic FTP will not be allowed for security reasons.

A single file will be provided for all pharmacies. A column in the format will be used to determine the pharmacy id, PioneerRx will be responsible for splitting the file up and updating the appropriate locations.

The nightly file must be ready by 4 am Central Standard Time each day.

The file will have the following naming convention:
PioneerRx_MTMActions_3_YYYYMMDD.zip or PioneerRx_MTMActions_3_YYYYMMDD.txt

The “_3_” above is the version number for the file format. It will be used to indicate the version of the spec used.

The file will be located in the following directory for the user account provided to PioneerRx:
\mtm\

Zipped files are preferred (standard ZIP compression), especially for large data sets. PioneerRx may require compression if the data is too large and negatively impacts performance of the download.

PioneerRx will automatically delete the file from the FTP server when it has been processed. The Technology Partner is responsible for keeping a separate backup of the file if they desire to keep one.

Authentication

Web Service

PioneerRx supports the following methods for authentication for this service:

username (basic auth)
password (basic auth)
ApplicationKey(header)
LocationKey(header)

Please notify us if test credentials will need to be different from production credentials

FTP Data File

A username and password for the account will be provided to PioneerRx. This should be provided in separate medians for security. We will typically call your designated contact for the password and have you email the username.

Data Format and API

Action Object

Field Name Data Type Required Notes
PioneerRxPatientID CHAR(36) C

Required if PioneerRxPatientIDAlternative not provided

Guid/Uniqueidentifier
PioneerRxPatientIDAlternative INT C Rquired if PioneerRxPatientID not provided
ExternalPatientID VARCHAR(36) Y Patient ID in vendor system or mutual identifier assigned by vendor
PatientDob DATE Format: yyyyMMdd
PatientAddress1 VARCHAR(200)
PatientAddress2 VARCHAR(200)
PatientCity VARCHAR(40)
PatientState VARCHAR(2)
PatientZip VARCHAR(15)
StartDate DATE C

Format: yyyyMMdd

Will assume today if not provided
DueDate DATE Format: yyyyMMdd
CompletedDate DATE

Format: yyyyMMdd

Will set MTM Action Status Type to Completed when a value is provided and Active when no value is provided.
VendorActionID VARCHAR(36) Y

Uniqueidentifier per MTM Action

Used to update previously submitted actions
ActionUrl VARCHAR(500)
ActionText VARCHAR(MAX) Y

Description of the action

Examples:
Called patient
Need to verify patient address
PharmacyID VARCHAR(20) Y Primary NPI or NCPDP needed
PharmacyIDType INT Y 1: NPI, 2: NCPDP
RxNumber INT Used to link action to specific rx/Medication
RefillNumber INT
ActionTypeID INT

Mutually agreed upon enumeration of action type to differentiate actions or services performed

Example:
1 = phone call
2 = letter sent
3 = patient follow-up required
etc.

Web Service

Parameters will be provided via JSON object posted to endpoint.

If no patient or location parameters are provided, it is assumed that all patients/locations are requested.

It is the partner system’s responsibility to determine which records are returned with each invocation of the service.

An optional StartDateTime and EndDateTime will be used to filter the results to pull. If neither are provided, the pull should including everything. If StartDateTime only is provided the pull should include everything since that time. If EndDateTime only is provided the pull should include everything up until that time.

In the response JSON, a generatedDateTime property will be included. This should be the datetime that information was generated by the Technology Partner System. This will be used by default as the StartDateTime on the next run. This allows PioneerRx to control which records to pull in the event of a failure.

A “version” property will be included. This will be used to allow for future modifications to be versioned.

Request Object

Request Example 1

{
    "GetActionsRequest": {
        "StartDateTime": "2017-02-15T01:00:36.687Z",
        "EndDateTime": "2017-02-15T06:00:00.000Z"
    }
}

Request Example 2

{
    "GetActionsRequest": {
        "PioneerRxPatientID": "D9BFCCC9-C1A3-4390-B5A3-FFE8B523B363",
        "ExternalPatientID": "ABC12345",
        "PharmacyID": "1234567",
        "PharmacyIDType": 2,
        "StartDateTime": "2017-02-15T01:00:36.687Z",
        "EndDateTime": "2017-02-15T06:00:00.000Z"
    }
}
Field Name Data Type Notes
PioneerRxPatientID CHAR(36) Guid/Uniqueidentifier
ExternalPatientID VARCHAR(36)
PharmacyID VARCHAR(30)
PharmacyIDType INT 1: NPI, 2: NCPDP
StartDateTime DATETIME

ISO8601 with time zone Z

Format:yyyy-mm-ddThh:mi:ss.mmmZ
EndDateTime DATETIME

ISO8601 with time zone Z

Format:yyyy-mm-ddThh:mi:ss.mmmZ

Note that we will poll using only StartDateTime and/or EndDateTime to download mtm actions centrally and each stores will download their data from our central server

Response Object

Reponse Example 1

{
    "generatedDateTime": "2017-02-15T06:00:36.685Z",
    "version": 3,
    "actions": []
}

Response Example 2

{
    "generatedDateTime": "2017-02-15T06:00:36.685Z",
    "version": 3, 
    "actions": [{
        "ActionText": "Call Patient",
        "ActionTypeID": 1,
        "ActionUrl": "https:\/\/www.mydomain.com\/patients\/840934809?ref=notifications",
        "CompletedDate": null,
        "DueDate": "20170220",
        "ExternalPatientID": "840934809",
        "PatientAddress1": "111 Main St",
        "PatientCity": "Shreveport",
        "PatientDob": "20010203",
        "PatientState": "LA",
        "PatientZip": "71111",
        "PharmacyID": "123456",
        "PharmacyIDType": 1,
        "PioneerRxPatientID": "7A6636C2-B5D1-4FAC-B887-C8BEE1676E37",
        "PioneerRxPatientIDAlternative": "10201",
        "RefillNumber": 0,
        "RxNumber": 987654,
        "StartDate": "20170214",
        "VendorActionID": "AB66B454-5B94-4679-9F83-BCBD1825959D"
    },
    {
        "ActionText": "Call Patient",
        "ActionTypeID": 1,
        "ActionUrl": "https:\/\/www.mydomain.com\/patients\/840934810?ref=notifications",
        "CompletedDate": null,
        "DueDate": "20170220",
        "ExternalPatientID": "840934810",
        "PatientAddress1": "123 Main St",
        "PatientAddress2": "Apt 100",
        "PatientCity": "Shreveport",
        "PatientDob": "19910102",
        "PatientState": "LA",
        "PatientZip": "71111",
        "PharmacyID": "123456",
        "PharmacyIDType": 1,
        "PioneerRxPatientID": "343027D2-B375-49AD-AF0E-6F9D17DBC807",
        "RefillNumber": 0,
        "RxNumber": 987655,
        "StartDate": "20170214",
        "VendorActionID": "CAE9DDBA-95DE-4190-A6AA-A7E755EAA6CC"
    }]
}
Field Name Data Type Required Notes
generatedDateTime DATETIME Y

ISO8601 with time zone Z (UTC Time)

Format:yyyy-mm-ddThh:mi:ss.mmmZ
version INT Y
actions Action Array Y List of Action objects (Refer to Action Object section)

FTP Data File

The FTP Data file will be a delimited file. A unit separator character (US - ASCII code 31) or pipe character(| - ASCII code 124) will be used for the delimiter. This character is not allowed in actual data and should be properly stripped out if needed by the Technology Partner.

A newline character (CR - ASCII code 13) should be used to separate each row of data.

No header row will be included.

Data fields will appear in the order as listed in the Action Object section

Example Data File Row

7A6636C2-B5D1-4FAC-B887-C8BEE1676E37|10201|840934809|20010203|123 Main St||Shreveport|LA|71111|20160601|20160605||AB66B454-5B94-4679-9F83-BCBD1825959D|http://www.test.org/somevalue|Called Patient|123456|1|987654|0|1

Action Url

We recommend providing an ActionUrl to deep link into the vendor system (See Action Object data field ActionUrl).

Example:
https://www.mydomain.com/api/ViewAction?VendorActionID=12343465

We have an extension to this api for token based single sign on for viewing the ActionUrl. Please visit http://www.pioneerrx.com/apidoc/mtmsso for this api document.

Browser Support

If an ActionUrl is provided, the user has the ability to view the url in the PioneerRx application. PioneerRx will either open the ActionUrl inside a popup window of the PioneerRx application, or open using the default browser of the workstation. PioneerRx may change between these based on the interactions made by the user and both should be assumed can occur at a pharmacy.

Due to technical requirements of the .net framework, Internet Explorer is used when PioneerRx opens the URL as a popup within the application. In addition, most pharmacies do not alter their workstation’s default browser, and being Windows based, the default is most commonly Internet Explorer. PioneerRx currently requires Internet Explorer 8 or higher. We do not support lower versions of IE.

If your product cannot support current versions of alternative browsers (such as Edge, Chrome, Firefox, Opera, etc), please notify PioneerRx Development during your onboarding so that we can discuss options for forcing Internet Explorer.

Example Scenarios

  1. Vendor initiates contact with customer and wishes to inform pharmacy to add to patient record. No additional action required by pharmacy.

    • MTM Action would be provided for patient with a completed date and description of activity performed

  2. Vendor submits case requiring pharmacy to take action/follow up.

    • MTM Action sent to pharmacy with optional start date and no completed date. Optional URL provided for linking back to vendor system with additional steps to be performed.

  3. Vendor completes an in-process case.

    • MTM Action sent to pharmacy with completed date for case previously created with same VendorActionID

PioneerRx Contact Information

For all technical and business questions, concerns, or issues, please email PioneerRxDataPrograms@PioneerRx.com.

This email is monitored by our data integration team and someone will be in contact once reviewed. If a call is needed, please email us your topics and questions and we will setup a call with the appropriate individuals.

This is not meant to be given to users (ie, pharmacies). The most appropriate solution for them, if to use the PioneerRx Support Request features we have to ask for assistance.

If not contacted in the appropriate ways, persons may have to wait longer than necessary as requests then have to be internally re-routed at PioneerRx.

Questions To Answer for Integration

The following is a recap of the questions PioneerRx will need to have each Vendor answer for the integration to make sure they are configured correctly:

  1. What method will PioneerRx obtain MTM Action data from vendor system e.g. FTP Site, Web Service

  2. If using web service, what is the POST URL that PioneerRx will call for polling the MTM Actions? e.g.https://www.mydomain.com/api

  3. If using web service, what authentication method(s) will we be utilizing? e.g. Basic Auth Only, ApplicationKey Only, LocationKey Only, or a combination of these 3 options

  4. If using FTP site, PioneerRx will need credentials and other necessary information to be provided.

  5. Will vendor be using the MTM SSO api mentioned in the Action Url section for allowing single sign on to action in vendor’s system?

  6. If issues occur in vendor system, who should users contact for assistance (name, email, phone, etc)? e.g. Vendor Support, support@vendor.com, 1-555-555-1234

  7. Who is the technical contact for the integration with PioneerRx at the Vendor (name, email, phone, etc)? i.e. this is the person(s) that PioneerRx technical team can reach for future issues, this will not be shared with users.

json