Introduction

Welcome to the PMP Gateway API documentation. This API reference provides information on available endpoints and how to interact with them.

Using the PMP Gateway API, you can integrate patient prescription history data into your applications.

This API is RESTful and uses XML formatted requests and responses.

Example code is provided for each API request. To get started, you can make requests against the testing environment using the code examples and the XML request data they reference.

Architecture (of the PMP network)

PMP Gateway gets prescription data from a distributed network of state PMP systems. This section explains the architecture of the PMP network and how PMP Gateway fits into it.

State PMP Systems store prescription data for patients and allow authorized users to request or commit prescription data.

PMP Interconnect facilitates communications between state PMP systems. One role of PMP Interconnect is to manage permissions for how state PMP systems communicate with each other.

PMP Gateway connects to PMP Interconnect, providing an interface for healthcare providers to query patient prescription data.

Consequences of Distributed Architecture

The distributed architecture of the PMP system impacts how PMP Gateway functions. Some of the consequences:

  • Prescription data requests can only be as fast as the slowest PMP being queried. Consequently, the average response time is 7 seconds.
  • Errors may occur at any point in the network. XML Responses will describe where in the network an error occured.
PMP Diagram

Authentication

You must authenticate with a username and password for all API requests.

All requests must be made over HTTPS. Calls made over plain HTTP will fail.

API Endpoints

A testing environment is available for testing and development purposes. The testing environment is populated with test data and contains no real-world patient data.

The production environment contains real HIPAA protected patient data that must be properly handled.

Testing API Endpoint

https://gateway-prep.pmp.appriss.com

Production API Endpoint

https://pmpgateway.net

Errors

PMP Gateway uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing) and codes in the 5xx range indicate an error with PMP Gateway.

HTTP Status Codes

200 OK Everything worked as expected or the request was missing required XML nodes and the response XML will describe the error.
401 Unauthorized Invalid login credentials.
500 Internal Server Error Something went wrong. The response body will be a Gateway Response with an Error section.

Gateway Request

When a Gateway request is recieved, PMP Gateway requests patient prescription data from the required PMP systems.

If the PMP systems are successfully queried, the Gateway response will include the patient prescription data.

The Gateway request has many optional data elements. Additionally, some elements are conditional, meaning that your request must include at least one element out of a set of possible elements.

This example includes all required elements and most of the optional elements. For conditional elements, this example includes all possible options. There are notes where conditional elements are present.

Note: Some optional elements have been ommitted because they are not useful for the vast majority of users. For more information on these rarely used elements, consult the gateway request types XML schema.

Definition

POST https://gateway-prep.pmp.appriss.com/search_request/create

Example Request

curl https://gateway-prep.pmp.appriss.com/search_request/create \
  -u username:password \
  -H "Content-Type: application/xml" \
  -H "Accept: application/xml" \
  -d @gateway_request.xml

Example Request Data

gateway_request.xml

download
<?xml version="1.0" encoding="UTF-8"?>
<GatewayRequest xmlns="http://xml.appriss.com/gateway" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Requester>
    <SenderSoftware><!-- Optional -->
      <Developer>Software Inc.</Developer>
      <Product>Product Name</Product>
      <Version>Version info</Version>
    </SenderSoftware>
    <RequestDestinations><!-- Optional. If not included the PMP systems queried will be based on the configuration of the user account settings. -->
      <Pmp>OH</Pmp>
      <Pmp>VA</Pmp>
      <Pmp>IN</Pmp>
    </RequestDestinations>
    <Provider>
      <Role>Physician</Role>
      <FirstName>Jon</FirstName>
      <LastName>Doe</LastName>
      <!-- At least one identifier is required: DEANumber, NPINumber, or ProfessionalLicenseNumber. -->
      <DEANumber>AB1234579</DEANumber>
      <NPINumber>1212345671</NPINumber>
      <ProfessionalLicenseNumber>
        <Type>String</Type>
        <Value>A1231xbzy-bx</Value>
        <StateCode>KS</StateCode>
      </ProfessionalLicenseNumber>
    </Provider>
    <Location>
      <Name>Store #123</Name>
      <!-- At least one identifier is required: DEANumber, NPINumber, or NCPDPNumber. -->
      <DEANumber>AB1234579</DEANumber>
      <NPINumber>1234567890</NPINumber>
      <NCPDPNumber>1234567</NCPDPNumber>
      <Address>
        <Street>String</Street>
        <Street>String</Street>
        <City>String</City>
        <StateCode>KS</StateCode>
        <ZipCode>40242</ZipCode>
        <ZipPlusFour>4242</ZipPlusFour>
      </Address>
    </Location>
  </Requester>
  <PrescriptionRequest>
    <DateRange>
      <Begin>2008-11-01</Begin>
      <End>2010-11-30</End>
    </DateRange>
    <Patient>
      <Name>
        <First>John</First>
        <Middle>Jacob Jingleheimer</Middle><!-- Optional -->
        <Last>Schmidt</Last>
      </Name>
      <Birthdate>1900-01-01</Birthdate>
      <SexCode>M</SexCode>
      <Address>
        <Street>123 Main St</Street>
        <Street>Apt B</Street>
        <City>Columbus</City>
        <StateCode>KS</StateCode>
        <ZipCode>43215</ZipCode>
        <ZipPlusFour>4321</ZipPlusFour>
      </Address>
      <Phone>1234567890</Phone>
      <SSN>123-45-6789</SSN>
      <DriversLicenseIdentifier>
        <Value>S01-45-6789</Value>
        <StateCode>KS</StateCode>
      </DriversLicenseIdentifier>
      <PharmacyBenefitsMemberID>String</PharmacyBenefitsMemberID>
      <MedicalBenefitsMemeberID>String</MedicalBenefitsMemeberID>
    </Patient>
 </PrescriptionRequest>
</GatewayRequest>

Example Response

<?xml version="1.0" encoding="UTF-8"?>
<GatewayResponse xmlns="http://xml.appriss.com/gateway" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <RequestID>5407</RequestID>
  <Response>
    <Pmp>OH</Pmp>
    <NoData>
      <Message>No data.</Message>
      <Details><![CDATA[No Data]]></Details>
      <Source>PMP</Source>
    </NoData>
  </Response>
  <Disclaimer></Disclaimer>
</GatewayResponse>

Minimal Example

The Gateway request has many optional data elements. Additionally, some elements are conditional, meaning that your request must include at least one element out of a set of possible elements.

This example is the most minimalistic request possible. It includes all required elements and the conditional elements which are most commonly used. Providing less information will result in XML validation errors.

Definition

POST https://gateway-prep.pmp.appriss.com/search_request/create

Example Request

curl https://gateway-prep.pmp.appriss.com/search_request/create \
  -u username:password \
  -H "Content-Type: application/xml" \
  -H "Accept: application/xml" \
  -d @gateway_request__minimal.xml

Example Request Data

gateway_request__minimal.xml

download
<?xml version="1.0" encoding="UTF-8"?>
<GatewayRequest xmlns="http://xml.appriss.com/gateway">
  <Requester>
    <Provider>
      <Role>Physician</Role>
      <FirstName>Jon</FirstName>
      <LastName>Doe</LastName>
      <!-- At least one identifier is required: NPINumber, DEANumber, or ProfessionalLicenseNumber. -->
      <NPINumber>1234567890</NPINumber>
    </Provider>
    <Location>
      <Name>Some Medical Center</Name>
      <!-- At least one identifier is required: NPINumber, DEANumber, or NCPDPNumber. -->
      <NPINumber>9876543210</NPINumber>
      <Address>
        <StateCode>KS</StateCode>
      </Address>
    </Location>
  </Requester>
  <PrescriptionRequest>
    <DateRange>
      <Begin>2015-01-01</Begin>
      <End>2015-12-31</End>
    </DateRange>
    <Patient>
      <Name>
        <First>Bob</First>
        <Last>Testpatient</Last>
      </Name>
      <Birthdate>1900-01-01</Birthdate>
      <!-- ZipCode or Phone is required. -->
      <Address>
        <ZipCode>67203</ZipCode>
      </Address>
    </Patient>
 </PrescriptionRequest>
</GatewayRequest>

Example Response

<?xml version="1.0" encoding="UTF-8"?>
<GatewayResponse xmlns="http://xml.appriss.com/gateway" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <RequestID>5410</RequestID>
  <Response>
    <Pmp>KS</Pmp>
    <PrescriptionData>
      <ReportInfo>
        <DocumentPublicationTime>00:15:24</DocumentPublicationTime>
        <ExecutionDate>2015-10-26</ExecutionDate>
        <ExecutionTime>00:15:24</ExecutionTime>
        <DateRange>
          <Begin>2015-01-01</Begin>
          <End>2015-12-31</End>
        </DateRange>
      </ReportInfo>
      <Prescription>
        <PrescriptionNumber>B00003</PrescriptionNumber>
        <RefillNumber source="1">1</RefillNumber>
        <FilledDate>2015-03-27</FilledDate>
        <WrittenDate>2015-03-27</WrittenDate>
        <RefillsAuthorizedCount source="0">0</RefillsAuthorizedCount>
        <DaysSupplyCount source="30">30</DaysSupplyCount>
        <DispensedQuantity source="8.0">8.0</DispensedQuantity>
        <MethodOfPaymentCode>01</MethodOfPaymentCode>
        <Drug>
          <ProductName>ENDOCET 10-325 MG TABLET</ProductName>
          <Strength/>
          <UnitOfMeasure>each</UnitOfMeasure>
          <ProductIdentifier>
            <Type>NDC</Type>
            <Value>60951071270</Value>
          </ProductIdentifier>
        </Drug>
        <Dispenser>
          <OrganizationName>Alice's PHARMACY</OrganizationName>
          <Address>
            <Street>1111 FAKE ST SEC A</Street>
            <City>WICHITA</City>
            <StateCode>KS</StateCode>
            <ZipCode>67202</ZipCode>
          </Address>
          <Phone>3165555555</Phone>
        </Dispenser>
        <Patient>
          <Name>
            <Prefix/>
            <First>BOB</First>
            <Middle/>
            <Last>TESTPATIENT</Last>
            <Suffix/>
            <FullName>BOB TESTPATIENT</FullName>
          </Name>
          <Birthdate>1900-01-01</Birthdate>
          <Address>
            <Street>1023 NOT REAL ST</Street>
            <City>WITCHITA</City>
            <StateCode>KS</StateCode>
            <ZipCode>67203</ZipCode>
          </Address>
        </Patient>
        <Prescriber>
          <Name>
            <Prefix/>
            <First>BOB</First>
            <Middle/>
            <Last>TESTPRESCRIBER</Last>
            <Suffix/>
            <FullName>BOB TESTPRESCRIBER</FullName>
          </Name>
          <Address>
            <Street>8888 NOWHERE ST</Street>
            <City>WICHITA</City>
            <StateCode>KS</StateCode>
            <ZipCode>67203</ZipCode>
          </Address>
        </Prescriber>
      </Prescription>
      <Prescription>
        <PrescriptionNumber>B00002</PrescriptionNumber>
        <RefillNumber source="0">0</RefillNumber>
        <FilledDate>2015-02-27</FilledDate>
        <WrittenDate>2015-02-27</WrittenDate>
        <RefillsAuthorizedCount source="0">0</RefillsAuthorizedCount>
        <DaysSupplyCount source="30">30</DaysSupplyCount>
        <DispensedQuantity source="120.0">120.0</DispensedQuantity>
        <MethodOfPaymentCode>01</MethodOfPaymentCode>
        <Drug>
          <ProductName>ACETAMINOPHEN-COD #3 TABLET</ProductName>
          <Strength/>
          <UnitOfMeasure>each</UnitOfMeasure>
          <ProductIdentifier>
            <Type>NDC</Type>
            <Value>00406048462</Value>
          </ProductIdentifier>
        </Drug>
        <Dispenser>
          <OrganizationName>Alice's PHARMACY</OrganizationName>
          <Address>
            <Street>1111 FAKE ST SEC A</Street>
            <City>WICHITA</City>
            <StateCode>KS</StateCode>
            <ZipCode>67202</ZipCode>
          </Address>
          <Phone>3165555555</Phone>
        </Dispenser>
        <Patient>
          <Name>
            <Prefix/>
            <First>BOB</First>
            <Middle/>
            <Last>TESTPATIENT</Last>
            <Suffix/>
            <FullName>BOB TESTPATIENT</FullName>
          </Name>
          <Birthdate>1900-01-01</Birthdate>
          <Address>
            <Street>1023 NOT REAL ST</Street>
            <City>WITCHITA</City>
            <StateCode>KS</StateCode>
            <ZipCode>67203</ZipCode>
          </Address>
        </Patient>
        <Prescriber>
          <Name>
            <Prefix/>
            <First>ALICE</First>
            <Middle/>
            <Last>TESTPRESCRIBER</Last>
            <Suffix/>
            <FullName>ALICE TESTPRESCRIBER</FullName>
          </Name>
          <Address>
            <Street>1111 FAKE ST</Street>
            <City>WICHITA</City>
            <StateCode>KS</StateCode>
            <ZipCode>67203</ZipCode>
          </Address>
        </Prescriber>
      </Prescription>
      <Prescription>
        <PrescriptionNumber>B00001</PrescriptionNumber>
        <RefillNumber source="0">0</RefillNumber>
        <FilledDate>2015-04-13</FilledDate>
        <WrittenDate>2015-03-02</WrittenDate>
        <RefillsAuthorizedCount source="1">1</RefillsAuthorizedCount>
        <DaysSupplyCount source="30">30</DaysSupplyCount>
        <DispensedQuantity source="30.0">30.0</DispensedQuantity>
        <MethodOfPaymentCode>01</MethodOfPaymentCode>
        <Drug>
          <ProductName>ZOLPIDEM TART ER 12.5 MG TAB</ProductName>
          <Strength/>
          <UnitOfMeasure>each</UnitOfMeasure>
          <ProductIdentifier>
            <Type>NDC</Type>
            <Value>10370011610</Value>
          </ProductIdentifier>
        </Drug>
        <Dispenser>
          <OrganizationName>Alice's PHARMACY</OrganizationName>
          <Address>
            <Street>1111 FAKE ST SEC A</Street>
            <City>WICHITA</City>
            <StateCode>KS</StateCode>
            <ZipCode>67202</ZipCode>
          </Address>
          <Phone>3165555555</Phone>
        </Dispenser>
        <Patient>
          <Name>
            <Prefix/>
            <First>BOB</First>
            <Middle/>
            <Last>TESTPATIENT</Last>
            <Suffix/>
            <FullName>BOB TESTPATIENT</FullName>
          </Name>
          <Birthdate>1900-01-01</Birthdate>
          <Address>
            <Street>1023 NOT REAL ST</Street>
            <City>WITCHITA</City>
            <StateCode>KS</StateCode>
            <ZipCode>67203</ZipCode>
          </Address>
        </Patient>
        <Prescriber>
          <Name>
            <Prefix/>
            <First>ALICE</First>
            <Middle/>
            <Last>TESTPRESCRIBER</Last>
            <Suffix/>
            <FullName>ALICE TESTPRESCRIBER</FullName>
          </Name>
          <Address>
            <Street>1111 FAKE ST</Street>
            <City>WICHITA</City>
            <StateCode>KS</StateCode>
            <ZipCode>67203</ZipCode>
          </Address>
        </Prescriber>
      </Prescription>
      <Prescription>
        <PrescriptionNumber>B00001</PrescriptionNumber>
        <RefillNumber source="1">1</RefillNumber>
        <FilledDate>2015-03-02</FilledDate>
        <WrittenDate>2015-03-02</WrittenDate>
        <RefillsAuthorizedCount source="1">1</RefillsAuthorizedCount>
        <DaysSupplyCount source="30">30</DaysSupplyCount>
        <DispensedQuantity source="30.0">30.0</DispensedQuantity>
        <MethodOfPaymentCode>01</MethodOfPaymentCode>
        <Drug>
          <ProductName>ZOLPIDEM TART ER 12.5 MG TAB</ProductName>
          <Strength/>
          <UnitOfMeasure>each</UnitOfMeasure>
          <ProductIdentifier>
            <Type>NDC</Type>
            <Value>10370011610</Value>
          </ProductIdentifier>
        </Drug>
        <Dispenser>
          <OrganizationName>Alice's PHARMACY</OrganizationName>
          <Address>
            <Street>1111 FAKE ST SEC A</Street>
            <City>WICHITA</City>
            <StateCode>KS</StateCode>
            <ZipCode>67202</ZipCode>
          </Address>
          <Phone>3165555555</Phone>
        </Dispenser>
        <Patient>
          <Name>
            <Prefix/>
            <First>BOB</First>
            <Middle/>
            <Last>TESTPATIENT</Last>
            <Suffix/>
            <FullName>BOB TESTPATIENT</FullName>
          </Name>
          <Birthdate>1900-01-01</Birthdate>
          <Address>
            <Street>1023 NOT REAL ST</Street>
            <City>WITCHITA</City>
            <StateCode>KS</StateCode>
            <ZipCode>67203</ZipCode>
          </Address>
        </Patient>
        <Prescriber>
          <Name>
            <Prefix/>
            <First>ALICE</First>
            <Middle/>
            <Last>TESTPRESCRIBER</Last>
            <Suffix/>
            <FullName>ALICE TESTPRESCRIBER</FullName>
          </Name>
          <Address>
            <Street>1111 FAKE ST</Street>
            <City>WICHITA</City>
            <StateCode>KS</StateCode>
            <ZipCode>67203</ZipCode>
          </Address>
        </Prescriber>
      </Prescription>
      <Prescription>
        <PrescriptionNumber>B00004</PrescriptionNumber>
        <RefillNumber source="1">1</RefillNumber>
        <FilledDate>2015-04-13</FilledDate>
        <WrittenDate>2015-04-13</WrittenDate>
        <RefillsAuthorizedCount source="1">1</RefillsAuthorizedCount>
        <DaysSupplyCount source="30">30</DaysSupplyCount>
        <DispensedQuantity source="8.0">8.0</DispensedQuantity>
        <MethodOfPaymentCode>01</MethodOfPaymentCode>
        <Drug>
          <ProductName>ENDOCET 10-325 MG TABLET</ProductName>
          <Strength/>
          <UnitOfMeasure>each</UnitOfMeasure>
          <ProductIdentifier>
            <Type>NDC</Type>
            <Value>60951071270</Value>
          </ProductIdentifier>
        </Drug>
        <Dispenser>
          <OrganizationName>Bob's PHARMACY</OrganizationName>
          <Address>
            <Street>1234 NOT-A-REAL-PLACE DR </Street>
            <City>WICHITA</City>
            <StateCode>KS</StateCode>
            <ZipCode>67202</ZipCode>
          </Address>
          <Phone>3160000000</Phone>
        </Dispenser>
        <Patient>
          <Name>
            <Prefix/>
            <First>BOB</First>
            <Middle/>
            <Last>TESTPATIENT</Last>
            <Suffix/>
            <FullName>BOB TESTPATIENT</FullName>
          </Name>
          <Birthdate>1900-01-01</Birthdate>
          <Address>
            <Street>1023 NOT REAL ST</Street>
            <City>WITCHITA</City>
            <StateCode>KS</StateCode>
            <ZipCode>67203</ZipCode>
          </Address>
        </Patient>
        <Prescriber>
          <Name>
            <Prefix/>
            <First>CAROL</First>
            <Middle/>
            <Last>TESTPRESCRIBER</Last>
            <Suffix/>
            <FullName>CAROL TESTPRESCRIBER</FullName>
          </Name>
          <Address>
            <Street>2910 HIGH ST</Street>
            <City>WICHITA</City>
            <StateCode>KS</StateCode>
            <ZipCode>67203</ZipCode>
          </Address>
          <DEANumber>XC5555555</DEANumber>
        </Prescriber>
      </Prescription>
    </PrescriptionData>
  </Response>
  <Disclaimer></Disclaimer>
</GatewayResponse>

Gateway Responses

Because of the distributed architecture of the PMP network, there are many factors which impact the response to a Gateway request. This section explains some of the common responses and what they mean.

No Data

If a PMP system has no prescription data for the specified patient, it returns a NoData response.

Response Details

The Pmp node contains the state abbreviation for the PMP system which the response is for.

The Message node will be a simple text explanation of what happened. This should be appropriate to display to users.

The Source node describes where in the request lifecycle the error originated. This may be helpful in troubleshooting.

Example Request Data

response__no_data.xml

download
<?xml version="1.0" encoding="UTF-8"?>
<GatewayResponse xmlns="http://xml.appriss.com/gateway" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <RequestID>5424</RequestID>
  <Response>
    <Pmp>OH</Pmp>
    <NoData>
      <Message>No data.</Message>
      <Details><![CDATA[No Data]]></Details>
      <Source>PMP</Source>
    </NoData>
  </Response>
  <Disclaimer></Disclaimer>
</GatewayResponse>

Error

If something prevented the request from being processed, the response will be an error. This could be accompanied by an non-200 HTTP response code.

Response Details

The Pmp node contains the state abbreviation for the PMP system which the response is for.

The Message node will be a simple text explanation of what happened. This should be appropriate to display to users.

The Source node describes where in the request lifecycle the error originated. This may be helpful in troubleshooting.

Example Request Data

response__error.xml

download
<?xml version="1.0" encoding="UTF-8"?>
<GatewayResponse xmlns="http://xml.appriss.com/gateway" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <RequestID>5424</RequestID>
  <Response>
    <Pmp>VA</Pmp>
    <Error>
      <Message>Could not find request destination.</Message>
      <Source>GATEWAY</Source>
    </Error>
  </Response>
  <Disclaimer></Disclaimer>
</GatewayResponse>

Disallowed

Your account with PMP Gateway does not have permission to query the specified PMP system.

Because of the distributed architecture of the PMP network, each PMP has its own administrator who manages permissions. To gain permission to query a specific PMP, contact the Appriss Project Manager who handles your account. Our project managers work with the PMP administrators to manage permissions requests.

Response Details

The Pmp node contains the state abbreviation for the PMP system which the response is for.

The Message node will be a simple text explanation of what happened. This should be appropriate to display to users.

The Source node describes where in the request lifecycle the error originated. This may be helpful in troubleshooting.

Example Request Data

response__disallowed.xml

download
<?xml version="1.0" encoding="UTF-8"?>
<GatewayResponse xmlns="http://xml.appriss.com/gateway" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <RequestID>5424</RequestID>
  <Response>
    <Pmp>IN</Pmp>
    <Disallowed>
      <Message>Your licensee is not allowed to make requests to IN</Message>
      <Source>GATEWAY</Source>
    </Disallowed>
  </Response>
  <Response>
    <Pmp>VA</Pmp>
    <Disallowed>
      <Message>A Optometrist from OH is not allowed to make requests to VA</Message>
      <Source>INTERCONNECT</Source>
    </Disallowed>
  </Response>
  <Disclaimer></Disclaimer>
</GatewayResponse>