Form CMS-10558 QHP Network and Formulary - Developer Documentation

APPENDIX A

Developer Documentation
Learn how to describe what providers and drugs are covered by a particular health plan.

JSON
All information must be described in the JSON file format. JSON is a lightweight and
simple way to represent machine-readable data. It is quickly becoming the de facto
standard for shuttling data across the internet, fueled primarily by the rise of mobile and
APIs. Modern programming languages can interpret and produce JSON out of the box.
Learn about JSON >

Public Discoverability
Organizations must post their plans.json, providers.json, and drugs.json files on their
websites, accessible to the public.
The path to the URLs will be submitted via HIOS to CMS.
The JSON URLs listed above must be provided over HTTPS to ensure the integrity of
the data.

Health Plans - plans.json
Description
plans.json contains a list of health plans and their corresponding network of providers

and formularies.

Schema
Field

plan_id_type

Label

ID Type

Definition

Type of Plan ID. The preferred is the HIOS

Required

Always

APPENDIX A
Field

Label

Definition

Required

Plan ID - HIOS-PLAN-ID

plan_id

marketing_name

summary_url

marketing_url

formulary_url

Unique
Identifier

number. (Plan IDs must be unique, even

The name of the plan as it is displayed on

Name

HealthCare.gov

URL for

The URL that goes directly to the summary

Plan

of benefits and coverage for the specific

Information

standard plan or plan variation.

URL for

The URL that goes directly to the plan

Plan

brochure for the specific standard plan or

Information

plan variation.

URL for
Formulary

Email
Address for
Plan

Always

across different markets.)

Marketing

Contact
plan_contact

The 14-character, HIOS-generated Plan ID

Always

Always

No

The URL that goes directly to the formulary
brochure for the specific standard plan or

No

plan variation.

An email address for developers/public to
report mistakes in the network and

Always

formulary data.

network

Network

Array of networks

Always

formulary

Formularies

Array of drug lists

Always

APPENDIX A
Field

Label

Benefits

benefits

Definition

Required

Array of benefits

No

ISO 8601 format (e.g. YYYY-MM-DD)

Always

Last
Updated

last_updated_on

On

Network sub-type
Field

network_tier

Label

Definition

Network

Tier for network (Example Values: PREFERRED, NON-

Tier

PREFERRED, etc. Values should be all uppercase. )

Required

Always

Formulary sub-type
Field

Label

Definition

Required

Tier for formulary - (Example
Values: GENERIC, PREFERRED-GENERIC,NONdrug_tier

Drug

PREFERRED-GENERIC, SPECIALTY, BRAND, PREFERRED-

Tier

BRAND,NON-PREFERRED-BRAND, ZERO-COST-SHARE-

Always

PREVENTIVE, MEDICAL-SERVICE, etc. Values should be

all uppercase.)

mail_order

cost_sharing

Mail

Does the formulary cover mail order? -

Order

(Values: true or false)

Cost

Array of cost sharing values (see "Cost sharing sub-

Sharing

type" below)

Always

Always

APPENDIX A

Cost sharing sub-type
Field

Label

Definition

Required

Pharmacy type (Example Values: 1pharmacy_type

Pharmacy
Type

MONTH-IN-RETAIL, 1-MONTH-OUT-RETAIL, 1MONTH-IN-MAIL, 1-MONTH-OUT-MAIL,3-

Always

MONTH-IN-RETAIL, 3-MONTH-OUT-RETAIL, 3MONTH-IN-MAIL, 3-MONTH-OUT-MAIL)

copay_amount

copay_opt

coinsurance_rate

coinsurance_opt

Copay
amount

Copay
option

Coinsurance
rate

Coinsurance
option

Amount of copay, in $ (number)

Always

Qualifier of copay amount (Values: AFTERDEDUCTIBLE,BEFORE-DEDUCTIBLE, NO-

Always

CHARGE, NO-CHARGE-AFTER-DEDUCTIBLE

Rate of coinsurance (float, 0.0 to 1.0)

Always

Qualifier for coinsurance rate
(Values: AFTER-DEDUCTIBLE, NO-

Always

CHARGE, NO-CHARGE-AFTER-DEDUCTIBLE)

Benefits sub-type
The Benefits sub-type is an optional section and will be shaped depending on what
industry and consumers find valuable.
For example, many health plans are offering telemedicine as an additional health
benefit and that can be highlighted by adding a telemedicine entry.
Field

Label

Definition

Required

APPENDIX A
Field

telemedicine

Label

Definition

Offers

Does the plan cover telemedicine? -

Telemedicine

(Values: true orfalse)

Example
[

{

"plan_id_type": "HIOS-PLAN-ID",
"plan_id": "12345XX9876543",
"marketing_name": "Sample Gold Health Plan",
"summary_url": "http://url/to/summary/benefits/coverage",
"marketing_url": "http://url/to/health/plan/information",
"formulary_url": "http://url/to/formulary/information",
"plan_contact": "[email protected]",
"network": [
{
"network_tier": "PREFERRED"
},
{
"network_tier": "NON-PREFERRED"
}
],
"formulary": [
{
"drug_tier": "GENERIC",
"mail_order": true,
"cost_sharing": [
{
"pharmacy_type": "1-MONTH-IN-RETAIL",
"copay_amount": 20.0,
"copay_opt": "AFTER-DEDUCTIBLE",
"coinsurance_rate": 0.10,
"coinsurance_opt": "BEFORE-DEDUCTIBLE"
},
{
"pharmacy_type": "1-MONTH-IN-MAIL",
"copay_amount": 0.0,
"copay_opt": "NO-CHARGE",
"coinsurance_rate": 0.20,
"coinsurance_opt": null
}
]
},
{
"drug_tier": "BRAND",
"mail_order": true,
"cost_sharing": [

Required

No

APPENDIX A
{

},
{

]

]

}

}

"pharmacy_type": "1-MONTH-IN-RETAIL",
"copay_amount": 15.0,
"copay_opt": null,
"coinsurance_rate": 0.0,
"coinsurance_opt": null
"pharmacy_type": "1-MONTH-IN-MAIL",
"copay_amount": 20.0,
"copay_opt": "AFTER-DEDUCTIBLE",
"coinsurance_rate": 0.10,
"coinsurance_opt": "BEFORE-DEDUCTIBLE"

}
],
"last_updated_on": "2015-03-17"

Providers - providers.json
Description
providers.json contains a list of providers and the plans that cover their services.

Schema
Field

Label

Definition

National

The National Provider Identifier (NPI) is a

Provider

unique identification number for covered health

ID

care providers

type

Type

Specify if INDIVIDUAL or FACILITY

plans

Plans

last_updated_on

Last

npi

Array of plans that cover this provider (see
"Plans sub-type" below)

Date of when the record for this provider has

Required

Always

Always

Always

Always

APPENDIX A
Field

Label

Definition

Updated

been last updated or refreshed - ISO 8601

On

format (e.g. YYYY-MM-DD)

Required

If the entry is for an INDIVIDUAL then the following fields should be present:
Field

Label

Definition

Required

name

Name

-

Always

prefix

Prefix

-

No

first

First Name

-

Always

middle

Middle Name

-

No

last

Last Name

-

Always

suffix

Suffix

-

No

address

Address

-

Always

-

Always

-

No

-

Always

address

address_2

city

Street
Address

Street
Address 2

City

APPENDIX A
Field

Label

State

state

Abbreviation

Zip Code

zip

phone

specialty

accepting

gender

languages

Phone
Number

Specialty
Type

Definition

Required

-

Always

-

Always

-

Always

An array of speciality types.

Always

Accepting

Is the provider accepting patients? -

Patients

(Values: true or false)

Gender

Values: Male, Female, Other

Optional

An array of the languages spoken

Optional

Languages
Spoken

Always

If the entry is for a FACILITY then the following fields should be present:
Field

Label

Definition

Required

facility_name

Facility Name

-

Always

facility_type

Facility Type

An array of facility types.

Always

address

Address

-

Always

address

Street Address

-

Always

APPENDIX A
Field

Label

Definition

Required

address_2

Street Address 2

-

No

city

City

-

Always

state

State Abbreviation

-

Always

zip

Zip Code

-

Always

phone

Phone Number

-

Always

Plans sub-type
Field

Label

plan_id_type

ID Type

Unique

plan_id

Identifier

network_tier

Definition

Type of Plan ID. The preferred is the HIOS Plan ID
- HIOS-PLAN-ID

{

Always

The 14-character, HIOS-generated Plan ID
number. (Plan IDs must be unique, even across

Always

different markets.)

Network

Tier for network (Example Values: PREFERRED, NON-

Tier

PREFERRED, etc. Values should be all uppercase. )

Example
[

Required

"npi": "1234567890123456",
"type": "INDIVIDUAL",
"name": {
"first": "Sarah",

Always

APPENDIX A
"middle": "Maya",
"last": "Ngyuen",
"suffix": "Jr."

},
{

},
"address": {
"address": "123 Main Street",
"address_2": "Suite 120",
"city": "Little Rock",
"state": "AR",
"zip": "72201"
},
"phone": "2025551212",
"specialty": ["Ophthalmology"],
"accepting": true,
"plans": [
{
"plan_id_type": "HIOS-PLAN-ID",
"plan_id": "12345XX9876543",
"network_tier": "PREFERRED"
},
{
"plan_id_type": "HIOS-PLAN-ID",
"plan_id": "12345XX9876543",
"network_tier": "NON-PREFERRED"
}
],
"languages": ["English", "Spanish", "Mandarin"],
"last_updated_on": "2015-03-17"
"npi": "1234567890123949",
"type": "FACILITY",
"facility_name": "Main Street Hospital",
"facility_type": ["Hospital"],
"address": {
"address": "123 Main Street",
"address_2": "Suite 120",
"city": "Little Rock",
"state": "AR",
"zip": "72201"
},
"phone": "2025551212",
"plans": [
{
"plan_id_type": "HIOS-PLAN-ID",
"plan_id": "12345XX9876543",
"network_tier": "PREFERRED"
},
{
"plan_id_type": "HIOS-PLAN-ID",
"plan_id": "12345XX9876543",
"network_tier": "NON-PREFERRED"
}
],
"last_updated_on": "2015-03-17"

APPENDIX A
]

}

Drugs - drugs.json
Description
drugs.json contains a list of drugs and the plans that cover them.

Schema
Field

rxnorm_id

drug_name

Label

Drug
Identifier

Drug
Name

Plans

plans

Definition

Required

RxCUI (Specific drug identifier from RXNORM)

Always

Name of Drug

Always

Array of plans that cover this drug (see "Plans subtype" below)

Always

Plans sub-type
Field

plan_id_type

plan_id

Label

ID Type

Unique
Identifier

Definition

Type of Plan ID. The preferred is the
HIOS Plan ID - HIOS-PLAN-ID

Required

Always

The 14-character, HIOS-generated Plan
ID number. (Plan IDs must be unique,
even across different markets.)

Always

APPENDIX A
Field

Label

Definition

Required

Tier for formulary (Example
Values: GENERIC, PREFERREDGENERIC, NON-PREFERRED-

drug_tier

Drug Tier

GENERIC, SPECIALTY, BRAND,PREFERREDBRAND, NON-PREFERRED-BRAND, ZERO-

Always

COST-SHARE-PREVENTIVE, MEDICALSERVICE, etc. Values should be all

uppercase. )

Prior
prior_authorization

Authorization
Required

Step
step_therapy

Therapy
Required

quantity_limit

Is prior authorization required? (Values: true or false)

Is step therapy required? (Values: true or false)

Quantity

Is there a quantity limit for this drug? -

Limit

(Values: true orfalse)

Example
[

{

"rxnorm_id": "209459",
"drug_name": "Acetaminophen 500 MG Oral Tablet [Tylenol]",
"plans": [
{
"plan_id_type": "HIOS-PLAN-ID",
"plan_id": "12345XX9876543",
"drug_tier": "GENERIC",
"prior_authorization": false,
"step_therapy": false,
"quantity_limit": false
},
{

Always

Always

Always

APPENDIX A

},
{

]

}

]

}

"plan_id_type": "HIOS-PLAN-ID",
"plan_id": "56748XXX123933",
"drug_tier": "GENERIC",
"prior_authorization": false,
"step_therapy": false,
"quantity_limit": false

"rxnorm_id": "248656",
"drug_name": "Azithromycin 500 MG Oral Tablet [Zithromax]",
"plans": [
{
"plan_id_type": "HIOS-PLAN-ID",
"plan_id": "12345XX9876543",
"drug_tier": "GENERIC",
"prior_authorization": false,
"step_therapy": false,
"quantity_limit": true
},
{
"plan_id_type": "HIOS-PLAN-ID",
"plan_id": "56748XXX123933",
"drug_tier": "GENERIC",
"prior_authorization": false,
"step_therapy": false,
"quantity_limit": false
}
]