MMIT API Business Quickstart


This API highlights MMIT’s Formulary data, and includes all of the supporting resources needed to retrieve Formulary coverage information. There are many ways to consume this Formulary data, and we hope to highlight some basic scenarios in the examples below. Following this Business Quickstart is a Technical Quickstart, which covers some of the technical aspects of the API.

Formulary Coverage


The main use of this API is to retrieve Formulary coverage information. Formulary coverage is defined as how a particular Product (or medical drug) is covered for a particular U.S. health Plan (or set of Plans). This coverage information includes status information and restriction information. You will need these two elements (Products and Plans) whenever retrieving formulary coverage.

Product Search


A Product is defined as any drug that is currently on the market. A product is unique based on the FirstDataBank MedId, Therapeutic Class Id, and the Route and Dose. Our database of Products can be searched using several criteria (Medid or NDC or RxCUI or DDI, product name or Therapeutic Class Id, for example). The goal is to retrieve the MMIT Product Id(s) that you will use to retrieve coverage information. Below is an example of how to search for Products:

https://api.mmitnetwork.com/Formulary/v1/Products?Name=loratadine
This search for this generic allergy medication, loratadine, returns several products because it comes in different strengths, routed dose forms, and is under different therapeutic classes. Let’s take two of these products for our example.

  1. loratadine oral solution (Antihistamines), with Product Id of 2936
  2. loratadine tablet (Antihistamines), with Product Id of 4244

Parent Search


Every health Plan has two or three parents: a Payer and/or a PBM, and a Controller. The Payer is the corporate owner of the plan and the PBM is the pharmacy benefit manager for the plan. The Controller is the entity (Payer, PBM, or other) that controls the coverage decisions of the health plan. For example, the health plan “Aetna Better Health of Nebraska” has a Controller of “The State of Nebraska” since they control the coverage decisions. The corporate Payer for this plan is, of course, Aetna, Inc. The parent is important in that the coverage search can be based on a Payer Id, PBM Id, or Controller Id (as well as other parameters). Below is an example of how to search for a Parent:

https://api.mmitnetwork.com/Formulary/v1/Parents?Name=Aetna
This search for Aetna, returns two Parents:

Aetna, Inc. and Aetna Pharmacy Management.
Let’s use the parent, Aetna, Inc. (with a Parent Id of 3156), for our coverage search example.

Coverage Search


Now that we have our Product Ids and Parent Id, we can search for formulary coverage using the following call:

Example Request (JSON)
curl
-H "Authorization: Bearer $MMIT-API-TOKEN"
-H "Accept: application/json"
"https://api.mmitnetwork.com/Formulary/v1/Coverage?ProductId=2936"

Example Response (JSON)
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-FormularyApi-Version: 1.0.0

{
"controllercoverage":
{
 "controller": "Aetna, Inc.",
 "controllerid": 3156,
 "druglisttier":
 {
  "lives": 5152779,
  "percentage": 43,
  "plancount": 63,
  "tier": "Non-formulary"
 },
 "monthid": 202001,
 "plancoverages": {...},
 "product": "loratadine oral solution",
 "productid": 2936,
 "unifiedtier":
 {
  "lives": 8899726,
  "percentage": 75,
  "plancount": 113,
  "tier": Unknown
 }
}
}
The coverage response groups the results by the Product and the Controller, and then provides a list of plans (along with the coverage information) under each Controller.

The Controller coverage always includes a “winning” DrugList Tier status and a “winning” Unified Tier status, along with the percentage of the lives of the underlying plans that have that winning status.

Other Resources


In the examples above, you noticed that several parameters require identifiers. We provide resources to retrieve these identifiers along with their values and meaning. Below are a few examples.

Therapeutic Classes

The Product search allows you to search by Therapeutic Class Id. In order to retrieve a list of Therapeutic Classes, you can make the following call:

https://api.mmitnetwork.com/Formulary/v1/Products/TherapeuticClasses

Parent Types

The Parent search allows you to search by the ParentType Id. You can retrieve a list of these by making any of the following calls:

https://api.mmitnetwork.com/Formulary/v1/Parents/ParentTypes

States and CBSAs

The Parent search and Coverage search allows you to search by the State Id or the CBSA Id. You can retrieve a list of these by making any of the following calls:

https://api.mmitnetwork.com/Formulary/v1/Geographic/States
https://api.mmitnetwork.com/Formulary/v1/Geographic/CBSAs

Benefit Designs, Channels, and Plan Types

The Coverage search allows you to search by Benefit Design Id, Channel Id, or Plan Type Id. You can retrieve a list of these by making any of the following calls:

https://api.mmitnetwork.com/Formulary/v1/Plans/BenefitDesigns
https://api.mmitnetwork.com/Formulary/v1/Plans/Channels
https://api.mmitnetwork.com/Formulary/v1/Plans/PlanTypes

MMIT API Technical Quickstart


Welcome to the MMIT API quickstart guide.

The MMIT API is based on the REST architectural style. The API is technology and programming language agnostic. This means if you follow the REST guidelines below; you can use any programming language, browser or tooling that can communicate with the Formulary API REST Resources.

Not all REST API implementations are the same. Therefore, the goal of his quickstart is to get yourself familiar with the REST conventions implemented in the MMIT API. After reading this quickstart, you will be able to get up and running within minutes.

Base URL


All URLs referenced in the MMIT API begin with the following base URL:
https://api.mmitnetwork.com/Formulary/v1/
Note
Every request made to the MMIT API must be made over HTTPS. HTTP is not supported and those requests will result in failure.

Versioning


The MMIT API's current version is v1 (1.0). However, the API will include periodic updates, which will be labeled with specific version numbers. The API is versioned using conventions based on the base URL. For example, note the base URL above is appended with "v1" which denotes "major version 1". The versioning convetion is implemented as: major, minor and patch versions:
  • Major: New release and breaking changes are introduced
  • Minor: No breaking changes. However additional non-breaking changes can be introduced; such as:
    • New Formulary Resources
    • Additional fields to the return objects
    • Additional expansion of children objects
    • New HTTP response headers & error codes
  • Patch: Bug fixes and performance tuning. No new resources, schema changes or breaking changes are introduced.
Note
Only the major version is exposed in the base URL. For example, version 2.3.1 of the MMIT API would be exposed as a base URL of:
https://api.mmitnetwork.com/formulary/v2. Notice the minor and patch versions are not exposed of the complete version number.
Each request to the MMIT API includes a X-FormularyApi-Verion header that includes the major, minor and patch version of the used API. This header can be used to validate the minor and patch versions. Furthermore, it can be used as an indication of a new API version.

Example Response (Headers)
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-FormularyApi-Version: 1.0.0

Tip
Follow these guidelines to ensure your client consuming the API functions normally during periodic updates:
  • Do not use position ordinals directly on the response objects. Instead use field names of objects.
  • Do not rely on the default ordering of the response object collections returned from resources. The order may change in the future.
  • Do not rely on the position ordinals of the response headers. Instead use the header names of the HTTP responses.
  • Do not mix API versions in a single client application.
  • Do not reuly on API defaults. Use explicit options whenever possible (i.e. Response Format).

Authentication


All MMIT API calls are authenticated using a token. The token is retrieved by sending a POST to the Token resource using an assigned username and password. In the response, the token can be found in the "access_token" object and can be used as long as it's valid (found in the "expires_in" value).

Example Request
curl -X POST
-H "Accept: application/x-www-form-urlencoded"
-d "grant_type=password&username=yourusername&password=yourpassword"
"https://api.mmitnetwork.com/Token"

Example Response (JSON)
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-FormularyApi-Version: 1.0.0

{
"access_token":"2XkdxcyewlkdkcxvXelcw232mnD0211x..."
"expires_in": 199219
"token_type": "bearer"
}

Example C# Code
using Newtonsoft.Json;
using System;
using System.Net;
using System.Web;

namespace GetToken
{
 class Program
 {
  static void Main(string[] args)
  {
   WebClient Client = new WebClient();
   String Username = HttpUtility.UrlEncode("Username");
   String Password = HttpUtility.UrlEncode("Password");
   String URL = "https://api.mmitnetwork.com/Token";
   String PostData = String.Format("grant_type=password&username={0}&password={1}", Username, Password);
   String Response = Client.UploadString(URL, PostData);
   TokenResponse TokenResponse = JsonConvert.DeserializeObject<TokenResponse>(Response);
  }
 }

 public class TokenResponse
 {
  public String access_token { get; set; }
  public String token_type { get; set; }
  public Int32 expires_in { get; set; }
 }
}

Response Formats


Currently the MMIT API supports two response formats: JSON (application/json) and XML (application/xml) respectively. All of the Formulary API resources support both of these response formats.

Following the RESTful content negotion standards, returning the desired reponse format is as simple as setting the proper Accept header in the GET request.

Example Request (JSON)
curl
-H "Authorization: Bearer $MMIT-API-TOKEN"
-H "Accept: application/json"
"https://api.mmitnetwork.com/Formulary/v1/ParentTypes?ParentTypeId=1"

Example Response (JSON)
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-FormularyApi-Version: 1.0.0

{
"ParentTypeId": 1,
"Name": "Sample Name"
}
Note
The default response format is JSON (application/json) without explicitly selecting the HTTP Accept header. However, this may change in the future and it is not recommended to rely on as the default. Always explictly provide the desired response format in the HTTP Accept header.

Errors & Response Codes


Errors can occur on the API server as well while interfacing with the REST API endpoints. The MMIT API uses HTTP Status Codes as well as a custom error object that provides detailed information.

HTTP Status Codes
Response CodeDescription
200 OK

Successful Request
204 OK

No Content
400 BAD REQUEST

Bad Request
401 UNAUTHORIZED

Authentication credentials are required to access the resource. All requests must be authenticated.
404 NOT FOUND

The resource requested based on the URI could not be found.
406 NOT ACCEPTABLE

The MMIT API supports two resource formats: application/json or application/xml. An incorrect resource format was set in the Accept header.
429 TOO MANY REQUESTS

Your application has reached the rate limit ceiling.
500 SERVER ERROR

An error occured on the MMIT API Server. Check the developerMessage for more information.

Formulary API Error Object
When an unsuccessful request occurs, the MMIT API will return an error object in the response body in addition to the HTTP Status Code. The schema of the error object is shown below.
Field Name Description Type
status

The HTTP Status Code

 integer
message

A simple message that can be surfaced to an end-user.

 string
developerMessage

A complex message that is meant for a developer or a technical end-user.

 string

Example Error Response
HTTP/1.1 404 NOT FOUND
Content-Type: application/json;charset=UTF-8
X-FormularyApi-Version: 1.0.0

{
"status": 404,
"message": "Formulary Resource not found."
"developerMessage": "The specific Formulary Resource has not been found. Ensure the proper ID and/or type has been passed into the request URI."
}

Compression


The MMIT REST API offers flexible support for delivering message responses using either compressed or non-compressed payloads. Compression is an opt-in feature that is controlled via request headers. The current API supports two compression mechanisms:
  • gzip
  • deflate

Using Compression
By default API requests are not compressed. In order to opt-in to use compression, the Accept-Encoding request header must be properly formed. The following usage scenarios are supported:
  • No compression: Do not provide the Accept-Encoding request header
  • Compression using gzip: Set Accept-Encoding request header value to "gzip"" (Accept-Encoding: gzip )
  • Compression using deflate: Set Accept-Encoding request header value to "deflate" (Accept-Encoding: deflate )
  • Compression using either gzip or deflate: Set Accept-Encoding request header value to "gzip, deflate" (Accept-Encoding: gzip, deflate ). Note: set the compression you would like to take presedence first in the list. In this example, gzip will be used as it is listed first and the secondary fallback is deflate.

Requests that have a proper Accept-Header set will be responded to with a response header collection that includes a Content-Encoding header. This header value will be set to value of the compression used in the message payload (either: gzip or deflate). If no Accept-Encoding (compression) header is passed in, the response header collection will not include a Content-Encoding response header.

Example Request (with compresion)
curl
-H "Authorization: Bearer $MMIT-API-TOKEN"
-H "Accept: application/json"
-H "Accept-Header: gzip, deflate"
"https://api.mmitnetwork.com/Formulary/v1/ParentTypes?ParentTypeId=1"

Example Response (with compression)
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Encoding: gzip
X-FormularyApi-Version: 1.0.0

...
Note
Most SDKs include network libraries that can automatically handle un-compression of the message payload. Before using the MMIT compresion conventions, ensure your library supports compression natively. If your library does not support compression, you can still use the MMIT compression conventions however you will have to handle un-compression manually.

Rate Limiting


The MMIT API includes a global rate limiting model. Each authenticated user (access token) is subject to the rate limits for a given timeframe window.

Rate Limit Window
Rate limits in the MMIT API are divided into 60 minute windows. Each 60 minute window, includes a maximum of 100 API requests. The rate limit window is enforced globally on a per user (access token) basis. Therefore, all authenticated requests to the MMIT API are monitored to ensure the maximum limit is not reached in a given window. After the 60 minute window has ellapsed, a new window timeframe is started with the maximum number of requests reset to 100.

Rate Limit Headers
Every request to the MMIT API will include three response headers associated with Rate Limiting. These response headers should be monitored in your application. Proactively monitoring Rate Limit response headers will ensure your application is not exceeding rate limits and can gracefully handle when the limit is reached.
  • X-RateLimit-Limit: This is the maximum (ceiling) number of requests allowed in a throttling window. This number does not change.
  • X-RateLimit-Remaining: This is the number of requests remaining in the throttling window, before the requests start getting throttled.
  • X-RateLimit-Reset: This is the time in seconds, before the Rate Limit ceiling is reset.

Note
The provided rate limits in this documentation are defaults. Your MMIT contract may include larger rate limit threshholds.
As a best practice, do not hardcode limits into your application as they may change. Use the provided response headers in the MMIT API.

Example Response (with Rate Limiting headers) (only response headers are shown for brevity)
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-FormularyApi-Version: 1.0.0
Content-Encoding: gzip
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 50
X-RateLimit-Reset: 1000
...
In the example response above, the three provided rate limit headers provide valuable information. By looking at the X-RateLimit-Limit header you can verify the maximum number of requests per window timeframe is 100. By inspective the X-RateLimit-Remaining header, you can see that there are 50 requests remaining in the window timeframe before the rate limit is reached. Lastly, by inspecting the X-RateLimit-Reset header you can see that the timeframe window will reset in 1,500 seconds.

Rate Limit Error Codes
When the MMIT API Rate Limit has been reached for a given timeframe window, the API will respond with a 429 (Too Many Requests) response code.

Example Rate Limit Error Responses
HTTP/1.1 429 TOO MANY REQUESTS
Content-Type: application/json;charset=UTF-8
X-FormularyApi-Version: 1.0.0

{
"status": 429,
"message": "The allowed number of requests has been exceeded."
}

Note
If your application is making the same requests within a short timeframe; consider caching the results in a small data store on the client. This will not only reduce the amount of requests made to the MMIT API, but it will also improve performance.