NAV
return data

Pharmacy Systems API

Last updated: November 28, 2017

Published By:
CoverMyMeds, L.L.C.
Columbus, OH 43215
866-452-5017
www.covermymeds.com

Copyright © 2017 by CoverMyMeds, LLC.

Pharmacy Claims

GETTING STARTED

HOW THE API WORKS

  1. When you see a claim response for a prior authorization rejection (generally codes MR, AG, A6, 70, 75, 76), show the user a “Submit PA” option or button.
  2. When the user clicks this option, make an HTTP POST containing the claim and meta-data to the API endpoint URL.
  3. Open the user’s browser to the URL returned from the API request. The user will be logged into the CoverMyMeds website and can then work on the PA.

THE API REQUEST AND RESPONSE

Request: You make an HTTP POST containing an NCPDP 5.1 or D.0 claim, the pharmacy’s CoverMyMeds username and password, an API key, and optional meta-data. Response: An HTTP header and a body. You can receive the body in three different formats. To specify each format, simply call a resource (at base URL of claims.covermymeds.com/cmmimport):

The default. We return the URL(s) for each PA created in plain text in an HTML document, or an error message.

Verbose output in JSON format. This is useful for automated unit testing or if you wish to process more structured response data, particularly in a web application.

Not recommended for most systems. We return a blank body with no URL. This is useful only if you do not wish to open the user’s browser to the PA.

We accept B1 and B2 claims. B1 claims initiate a prior authorization and B2 claims delete a prior authorization. Note that if the prior authorization has already been shared with the physician before the B2 transaction is sent, that access to the PA will be removed for the pharmacy but the physician will still be able to process the PA. We support multiple claims for each header as specified in the NCPDP telecom specifications. You can download a few sample claims, or can use your own.

If a duplicate B1 or B2 transaction is sent, the API will return the response for the initial PA (that is, rather than creating a duplicate, we will send the URL for the existing prior authorization). Note that at some point we may allow pharmacies to “resubmit” the PA to the prescriber by resubmitting a duplicate request more than 24 hours after the initial request. In these cases, the original URL will be returned but this request will also cause the prescriber fax or email to be re-transmitted.

What Data to Send

The combination of the claim plus the meta-data must satisfy our payer sheet requirements. If values are provided “outside” of the claim as POST variables, they will override the claim values. Generally, it is best to implement the entire payer sheet as a claim edit and only provide POST variables for values that cannot be encapsulated in the claim (e.g., Prescriber Email Address).

The only required POST variables are the pharmacist’s username and password, an API key (assigned by CoverMyMeds), and the claim. All other fields are optional, but including them will improve the experience for the pharmacy user, since they won’t need to enter the data on the CoverMyMeds website. The most important optional fields to send are the prescriber contact info and the rejection info from the claim response segment.

DEBUGGING AND TESTING INTERFACE

We provide a web-based debugging and testing interface that generates the API request POST. You can use this tool to test API submissions with your own claims and meta-data. Because this tool itself uses the Claim API, it is useful for solving claim parsing problems if you are editing your claims before submission to the CoverMyMeds API, as well as to explore how the meta-data is used.

You can access the interface at https://claims.covermymeds.com/.

B1 REQUIRED FIELDS (PAYER SHEET)

Send just the Request claim, not the Response. A few fields from the Response should be sent as POST variables but sending the whole Response is not necessary and may concern some pharmacies as their payment rates could be determined by a 3rd party.

Field Description Note
101-A1 BIN You may overide this by sending POST variable ‘bin_number’
102-A2 Version
103-A3 Transaction Code
104-A4 Processor Control Number You may overide this by sending POST variable ‘pcn_number’
109-A9 Transaction Count
110-AK Software Vendor/Certification ID
111-AM Segment Identification
201-B1 Service Provider ID Qualifier
202-B2 Service Provider ID
301-C1 Group ID You may overide this by sending POST variable ‘group_id’
302-C2 Cardholder ID
303-C3 Person Code
304-C4 Date of Birth
305-C5 Patient Gender Code
306-C6 Patient Relationship Code
310-CA Patient First Name
311-CB Patient Last Name
322-CM Patient Street Address
323-CN Patient City Address
324-CO Patient State/Province Code
325-CP Patient Zip/Postal Code
401-D1 Date of Service
402-D2 Prescription/Service Reference Number
405-D5 Days’ Supply
407-D7 Product/Service ID
411-DB Prescriber ID You may overide this by sending POST variable ‘physician_npi’ or ‘physician_dea’ or both.
427-DR Prescriber Last Name You may overide this by sending POST variable ‘physician_lname’
436-E1 Product/Service ID Qualifier
442-E7 Quantity Dispensed
455-EM Prescription/Service Reference Number Qualifier
466-EZ Prescriber ID Qualifier

B2 REQUIRED FIELDS (PAYER SHEET)

Field Description Note
101-A1 BIN You may overide this by sending POST variable ‘bin_number’
102-A2 Version
103-A3 Transaction Code
104-A4 Processor Control Number You may overide this by sending POST variable ‘pcn_number’
109-A9 Transaction Count
436-E1 Product/Service ID Qualifier
202-B2 Service Provider ID
401-D1 Date of Service
110-AK Software Vendor
301-C1 Group ID You may overide this by sending POST variable ‘group_id’
302-C2 Cardholder ID
455-EM Prescription/Service Reference Number Qualifier
402-D2 Prescription/Service Reference Number
407-D7 Product/Service ID
466-EZ Prescriber ID Qualifier

REQUIRED POST VARIABLES

POST variable Sample value Note
username sample_user
password ********
ncpdp_claim NCPDP 5.1 or D.0 B1 or B2. See sample claims
api_key U2FtcGxlIEFQSSBQYXJ0bmVyIE5hbWU= Assigned by CoverMyMeds

OPTIONAL POST VARIABLES

POST variable Sample value Note
physician_fname John
physician_lname Smith
physician_specialty Cardiology
physician_npi 1234567890
physician_dea 1234567890
physician_street 123 Anyplace St.
physician_city New York
physician_state NY
physician_zip 10001
physician_phone 555-555-5555
physician_fax 555-555-6666
physician_email foo@bar.com
pharmacy_plan_name Humana Medicare Part D
prescription_sig BID
rejection_code 75 548-6F – Reject Code1
rejection_msg Consider Alternative Drug or call (555) 555-5555. 526-FQ – Additional Message Information (Rejection Message)
help_phone 5555555555 550-8F – Help Desk Phone Number
preferred_product_id_qualifier 3 552-AP – Preferred Product ID Qualifier
preferred_product_id 12345678910 553-AR – Preferred Product ID
preferred_product_description Omeprazole 10MG Tablets 556-AU – Preferred Product Description
bin_number 121212 101 – BIN Number2
pcn_number 23232323bb 104 – Processor Control Number
group_id 987654321 301-C6 – Group ID

1 Some fields can be collected from the claim rejection response from the health plan/processor. If included, they are very useful for display to the user and as additional data input for prior-authorization form selection.

2 If the integrating system uses a “secondary” claim to capture the prior authorization request, these fields can be sent from the corresponding original claim that was rejected. When sent, they will be used for form-selection and other information helpful to the user.

Handling errors and providing user feedback

For a successful implementation, you MUST handle a few types of errors.

Each API request will return an API response consisting of an HTTP header with a and message body. You may use the HTTP response code in the header and optionally, the message body to handle errors. It may also be desirable to show a “PA created” message in your pharmacy system while also opening the user’s browser to the returned URL.

An error will be any response code that is not 2xx (e.g., 200 or 201), however you can expect to see only a few error codes.

Upon error, it is best to show the user a simple error message with instruction to help them resolve the issue. This error can be shown in your pharmacy system. Suggestions are below:

Response Code What this means Suggested Error Message
2xx – Success PA Created Successfully PA Created. Manage PA at the CoverMyMeds website.
3xx – Redirection Problem with redirection or proxy error. The issue could be on either the pharmacy’s internet connection side or a problem with CoverMyMeds. Usually, this problem will occur when the pharmacy is running an internet proxy to share bandwidth across multiple stores. Oops, there was a connection problem. Please try one more time, then contact CoverMyMeds at 1-866-452-5017/help@covermymeds.com and they will help you diagnose this issue.
400 – Bad Request Request cannot be made due to bad syntax. This error is usually caused by sending a malformed request by the pharmacy system. Oops, there was a connection problem. Please try one more time, then contact CoverMyMeds at 1-866-452-5017/help@covermymeds.com and they will help you diagnose this issue.
403 – Forbidden The username or password that were submitted are incorrect or do not exist. Oops, login failed for the username or password that was submitted. Please check the username and password in your account settings in your Pharmacy System and at the CoverMyMeds website to make sure they match. If you still have trouble, please contact CoverMyMeds at 1-866-452-5017/help@covermymeds.com and they will help you fix this issue.
404 – Not Found There are several problems that could cause this issue. API requests to the incorrect URL, or missing required POST variables. If the issue was caused by missing POST variables, they will be reported in the HTTP body. Oops, there was a problem. Please check the username and password in your account settings in your Pharmacy System and at the CoverMyMeds website to make sure they match. If you still have trouble, please contact CoverMyMeds at 1-866-452-5017/help@covermymeds.com and they will help you fix this issue.
408 – Request Timeout A timeout occurred. This should occur rarely or never and could be due to a connectivity issue or if the CoverMyMeds service is having trouble responding. Oops, there was a timeout. Please try the request again in one minute. If you still have trouble, please contact CoverMyMeds at 1-866-452-5017/help@covermymeds.com and they will help you fix this issue.
422 – Unprocesessable Request cannot be made due to unprocessable fields. This error is usually caused by an unrecognizable NDC, which could indicate a new drug that is not in our system, or a typo in the NDC. Oops, there was a problem. Please check if the NDC is correct. If you still have trouble, please contact CoverMyMeds at 1-866-452-5017/ help@covermymeds.com and they will help you fix this issue.
500 – Server Error This issue is usually caused by an improperly formatted claim. When possible, we will return detail about the error in the HTTP body. It is also possible, but rare, that this error could be caused by a problem at CoverMyMeds. CoverMyMeds can diagnose these issues and will involve you if you need to make any modifications to your code. Oops, there was a problem. Please try the request again in one minute. If you still have trouble, please contact CoverMyMeds at 1-866-452-5017/help@covermymeds.com and they will help you diagnose this issue.

Pharmacy Callbacks

As part of the Pharmacy Claims API, you can recieve callbacks from CoverMyMeds about changes in workflow status for prior authorization requests you create. This allows you to keep the status within your system up-to-date as changes happen with the CoverMyMeds system.

To integrate callbacks into your system, you need to provide a single HTTPS URL where CoverMyMeds can send callbacks. Your server will need a valid SSL certificate. When the workflow status of a request changes, CoverMyMeds will send a POST request to the URL you specify with JSON data describing the request and its current status. If desired, CoverMyMeds can include Basic Authentication credentials you specify as part of the HTTP POST.

When a callback is recieved, your server should return an HTTP 200 status code to indicate success. CoverMyMeds will retry the callback after a delay if any other status code is received. Correspondingly, you should not return a 200 status code if your system was unable to receive the callback.

Work with your account manager to enable callbacks.

Additional implementation tips

STORING CoverMyMeds USERNAMES AND PASSWORDS

Each pharmacy will need to have a CoverMyMeds account consisting of a username and password. These accounts may be established by each pharmacy at the CoverMyMeds website, they may be established by you, or CoverMyMeds can set them up from an import file.

Regardless of initial setup, it is best to allow each pharmacy to manage their username and password in a “settings” option that they can control. This way, the pharmacy can reset their password at the CoverMyMeds website and make the corresponding update in their settings in the pharmacy system.

Care must be taken to use only the pharmacy that is submitting the PAs user account credentials for each API request. Using a different pharmacy’s account will expose claim data to an unauthorized pharmacy.

MAKING THE POST AND TAKING THE USER TO THEIR PA FORM

To make the post, you can use your favorite HTTP library. You could even do this with cURL:

curl --data-urlencode \
"username=<username>&password=<password> \
&api_key=<api_key> \
&ncpdp_claim=<ncpdp_claim>" \

https://claims.covermymeds.com/cmmimport/

Note that all POST variables need to be URL-encoded. For example, if you want the data to contain a space, you need to replace that space with %20 etc.

OPENING THE USER’S BROWSER

We recommend that you use the operating system default browser, rather than a Web Control in your pharmacy software so that the user will have a modern browser they are comfortable using, and so that bookmarks and the “back” button will work. You can open the user’s browser making an operating system call (e.g., Process.Start(target_url); or webbrowser.open(target_url)).

LOGGING THE USER INTO THEIR DASHBOARD

A button or link that logs the user into their PA Dashboard is a nice additional touch. This feature can be implemented in addition to implementing the method that takes the user to a specific PA form described above.

To implement this feature, post the username and password (just as done when making a claim API request) like this:

curl -X POST --data "username=<username>&plaintext_password=<password>" https://www.covermymeds.com/user/authtoken

If the username and password are valid, the content of the response body will be an authorization token that can be used to access most pages with a session that is set to the username that was authenticated in the POST.

Use the authorization token by parsing the response content and then GETing additional pages, for example by opening them in the user’s web-browser at a URL like this:

Remember that POST variables must be URL-encoded as described in the above section.

MORE INFO AND PARAMETERS

Rollout / Deployment

Before rolling out, you will need to get in touch with CoverMyMeds. If we haven’t already, we’ll assign an Account Manager to make sure you and your customers have direct access to our staff. Your Account Manager will provide:

– Training for your staff and customers - Exceptional help and marketing materials - Promotional support for your pharmacy system - A production API key (you’ll need to change this API key before going live)

You’ll complete the following checklist with your Account Manager before the production API key is issued:

PRE-DEPLOYMENT CHECKLIST

Item Complete?
Training for staff completed Y or N
Exchanged support contact info Y or N
Demo of full integration completed Y or N
All Errors handled in System Code Y or N
CoverMyMeds Account Setup Plan Y or N

FAQs

Which other systems have you integrated with? Thousands of pharmacies are successfully using the CoverMyMeds API. You can see a list of systems that have already integrated with CoverMyMeds.

How does the pharmacy send the PA to the prescriber? The pharmacy can fax or email the request to the prescriber directly from CoverMyMeds. Right after submitting the PA through the system, they just need to click “Email request” or “Fax request.”

How does the pharmacy know when the PA is approved? The plan will decide whether to approve or deny the request within 72 hours of when they receive the PA from the physician. At this point, the pharmacy may hear back from the plan or physician, or they may learn about the approval by resubmitting the originally denied claim.

What are system requirements for the pharmacy? Just a web browser and internet connection. Learn about supported browsers here.

Pharmacy Outcomes

Overview

The Outcomes API allows the pharmacy dispensing system to sychchronize the status of prior authorizations (PA) with CoverMyMeds. This status information allows CoverMyMeds to provide prompting, physician outreach, and performance monitoring on behalf of the pharmacy.

The Outcomes API is similar to the CoverMyMeds Pharmacy Claims API in that Telecom claim information forms the basic building block of the transaction. In this case, the PBM response information is used by CoverMyMeds to prompt the pharmacy to initiate a PA, or in the case of a previously submitted prior authorization, to mark a request as completed (with a paid claim response) or to determine that the PA is not yet complete (based on a rejected response).

This API should be implemented with the Pharmacy Claim API integration. If the pharmacy dispensing system has already implemented the Claim API in addition to “Messaging,” the core work for this transaction is completed. To enable follow-up services, the dispensing system just needs to begin sending paid claims in addition to the rejected claims which are already transmitted.

SENDING “PA” REJECTED CLAIMS

After a claim rejection that includes a rejection code for prior authorization or related coverage restrictions (codes 70, 75 or 76), the API should be called and used to replace the rejection message and customized “Easy Button” before it is shown to the pharmacy user. This involves a very short additional pause (up to 1500 milliseconds) before the rejected claim is shown to the pharmacy.

API requests for PA-rejected claims (codes 70, 75, 76) will receive a response that includes:

  1. A modified rejection message which may include a short piece of informative text to supplement the PBM’s message. Sometimes we will not include this text and will return the rejection message unchanged.
  2. A short text string which should be used as a button or menu item to invoke the Claim API prior authorization assistance process (“Easy Button”). If you have already implemented our Claim API, this text should replace the static text in your “submit PA” button or menu item.

SENDING PAID AND OTHER CLAIMS

All other claims should result in the call to the Outcomes API at the same time or after the PBM response is shown to the user. If sent at the same time, the API transaction should be asychronous or in a different thread from the pharmacy user interface-this way the “wait time” isn’t added to the pharmacy user experience as in the case of claims which require a prior authorization.

API Request and Response

Your pharmacy system will talk to this API using a simple web-service composed of an HTTP request and response. This API is available at the URL https://message.covermymeds.com/.

Requests to the base URL (/) will return the response as an HTML document, which is useful for exploring the API or for debugging purposes. POST requests to a URL suffix will return an API response more convenient for your application to use in either JSON or text format. You may specify JSON (https://message.covermymeds.com/message/json) or text (https://message.covermymeds.com/message/text) with the URL suffix.

JSON responses look like this for PA claims:

{ "button_label": "Submit", "message": "Submit your rejection to CoverMyMeds. And here is more additional message information from the PBM" }

Whereas text responses look like this:

Submit;Submit your rejection to CoverMyMeds. And here is more additional message information from the PBM

The button text is delimited from the message text with the ‘;’ character. Note that we will never use a ; character in the button text, so you may reliably split the response using the first instance of this delimiter you find in the response.

WHAT TO SEND

Data is sent to the API using url-encoded POST variables. For example, if you want the data to contain a “space”, you need to replace the space with %20 and so on.

All fields are required.

Field POST Variable Name Note
N/A api_key Use the same API Key used for Claim API
101-A1 bin BIN number
104-A4 pcn Processor Control Number
301-C1 group_id Group ID
548-6F approval_code If multiples are returned by PBM, they can be comma-separated and sent in one string
511-FB rejection_code If multiples are returned by PBM, they can be comma-separated and sent in one string
526-FQ rejection_message Send the full text of what your system displays as the “Rejection Message from the PBM”
402-D2 prescription_reference_number Prescription/Service Reference Number
455-EM prescription_reference_number_qualifier Prescription/Service Reference Number Qualifier
407-D7 product_service_id Product/Service ID
436-E1 product_service_id_qualifier Product/Service ID Qualifier
202-B2 service_provider_id Service Provider ID
201-B1 service_provider_id_qualifier Service Provider ID Qualifier
302-C2 cardholder_id Cardholder ID
303-C3 person_code Person Code
411-DB prescriber_id Prescriber ID
466-EZ prescriber_id_qualifier Prescriber ID Qualifier
405-D5 days_supply Days Supply
403-D3 fill_number Fill Number
422-E7 quantity_dispensed Quantity Dispensed
112-AN transaction_response_status Transaction Response Status
N/A patient_age Patient Age
N/A prescriber_fax Prescriber Fax. Include area code

Security and Privacy

CoverMyMeds retains only the minimally necessary data to support the services for which our pharmacy users have designated. For example, identifying data from API requests for paid claims are not retained unless they relate to a service CoverMyMeds is providing, such as a previously submitted prior authorization.

All data in transit, at-rest, and disposed is protected using our full HIPAA-compliant policies and procedures used for protection of protected health information (PHI).

This API uses the currently recognized best practice for transmission of data in secure web-based health care applications. Data transmitted over the Public internet is encrypted with 256-bit TLS. SHA-1 is used for the message digest and Verisign is the Certificate Authority.

More information is available at our Privacy Center.

Timeouts and handling errors

In the case of PA rejections, the API should be called so that the modified rejection message can be shown at the same time as the claim response-this means two transactions occur before the pharmacy receives their response-the original claim rejection to the PBM and the API request to CoverMyMeds. Because our response is very fast, and because the API is only used in the case of a prior authorization rejection, there should not be any noticeable delay to the pharmacy.

If for any reason the API response from CoverMyMeds is not returned within 1500 milliseconds in wall-clock time from when the HTTP request is made, the pharmacy system should “time out” this request and return the claim response including the original rejection message. Please note that this recommended timeout value may change over time.

Your error handling for this API is also very simple-any HTTP response other than an 200 status code should be treated the same way as the timeout-simply return the claim response and original rejection message. Please note that a successful implementation of the Pharmacy Claim API requires more involved error handling.

Additional Resources