Centers for Medicare and Medicaid Services Households & Eligibility API
Household specific calculations, including eligibility information, out of pocket costs, poverty levels, and cost benchmarks.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/cms-households-eligibility-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Marketplace Households & Eligibility API
version: '1'
description: '# About
The Marketplace API delivers data that helps users find and evaluate health care insurance plans, providers, and coverage information on the marketplace.'
servers:
- url: https://marketplace.api.healthcare.gov/api/v1
security:
- API Key: []
tags:
- name: Households & Eligibility
description: Household specific calculations, including eligibility information, out of pocket costs, poverty levels, and cost benchmarks.
paths:
/households/eligibility/estimates:
x-summary: Eligibility Estimates
post:
tags:
- Households & Eligibility
description: '#### Note
Use this JSON example in the **POST** Body in the request pane to view results:
```
{
"household": {
"income": 52000,
"people": [
{
"dob": "1992-01-01",
"aptc_eligible": true,
"gender": "Female",
"uses_tobacco": false
}
]
},
"market": "Individual",
"place": {
"countyfips": "37057",
"state": "NC",
"zipcode": "27360"
},
"year": 2019
}
```
Create an eligibility estimate for a household. Index of each
object in response array is index into Household.people array:
i.e., that eligibility estimate is for that person'
parameters:
- $ref: '#/components/parameters/apikey'
- $ref: '#/components/parameters/year-with-default'
responses:
'200':
description: Successful response
content:
application/json:
schema:
properties:
estimates:
items:
$ref: '#/components/schemas/Eligibility'
example:
- aptc: 448.08296071163227
csr: 94% AV Level Silver Plan CSR
hardship_exemption: false
is_medicaid_chip: false
type: array
type: object
requestBody:
content:
application/json:
schema:
properties:
household:
$ref: '#/components/schemas/Household'
place:
$ref: '#/components/schemas/Place'
year:
format: integer
type: number
required:
- place
example:
place: {}
year: 2019
type: object
description: eligibility estimate request object
required: true
summary: Create households eligibility estimates
x-summary-source: derived
operationId: postHouseholdsEligibilityEstimates
x-operation-id-source: derived
/households/ichra:
x-summary: Calculate ICHRA affordability
post:
tags:
- Households & Eligibility
description: '#### Note
Use this JSON example in the **POST** Body in the request pane to view results:
```
{
"household": {
"income": 52000,
"people": [
{
"dob": "1992-01-01",
"aptc_eligible": true,
"gender": "Female",
"uses_tobacco": false
}
]
},
"market": "Individual",
"place": {
"countyfips": "37057",
"state": "NC",
"zipcode": "27360"
},
"hra": 500,
"year": 2020
}
```
Get the lowest cost silver plan for a household and ICHRA affordability.
Response is determination of affordability and lowest cost silver plan premium set to the rate for the household.'
parameters:
- $ref: '#/components/parameters/apikey'
- $ref: '#/components/parameters/year-with-default'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ICHRAResponse'
summary: Get affordability and premium of the lowest cost silver plan
requestBody:
content:
application/json:
schema:
properties:
household:
$ref: '#/components/schemas/LowestCostPlanHousehold'
place:
$ref: '#/components/schemas/Place'
year:
format: integer
type: number
hra:
format: float
type: number
required:
- place
type: object
description: ichra request object
required: true
operationId: postHouseholdsIchra
x-operation-id-source: derived
/households/lcbp:
x-summary: Lookup LCBP
post:
tags:
- Households & Eligibility
description: '#### Note
Use this JSON example in the **POST** Body in the request pane to view results:
```
{
"household": {
"income": 52000,
"people": [
{
"dob": "1992-01-01",
"aptc_eligible": true,
"gender": "Female",
"uses_tobacco": false
}
]
},
"market": "Individual",
"place": {
"countyfips": "37057",
"state": "NC",
"zipcode": "27360"
},
"year": 2020
}
```
Get the lowest cost bronze plan for a household.
Response is a plan object with the premium set to the
rate for the household.'
parameters:
- $ref: '#/components/parameters/apikey'
- $ref: '#/components/parameters/year-with-default'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LowestCostPlanResponse'
summary: Get lowest cost bronze plan for a household
requestBody:
content:
application/json:
schema:
properties:
household:
$ref: '#/components/schemas/LowestCostPlanHousehold'
place:
$ref: '#/components/schemas/Place'
year:
format: integer
type: number
required:
- place
type: object
description: lcbp request object
required: true
operationId: postHouseholdsLcbp
x-operation-id-source: derived
/households/slcsp:
x-summary: Lookup SLCSP
post:
tags:
- Households & Eligibility
description: '#### Note
Use this JSON example in the **POST** Body in the request pane to view results:
```
{
"household": {
"income": 52000,
"people": [
{
"dob": "1992-01-01",
"aptc_eligible": true,
"gender": "Female",
"uses_tobacco": false
}
]
},
"market": "Individual",
"place": {
"countyfips": "37057",
"state": "NC",
"zipcode": "27360"
},
"year": 2020
}
```
Get the second lowest cost silver plan for a household.
Response is a plan object with the premium set to the rate for the household.
Note -- when calculating the SLCSP for a household that has members in different rating areas, the household must be split by rating area and multiple SLCSP requests must be sent, with the results summed at the end (applies only to 2019 ratings).'
parameters:
- $ref: '#/components/parameters/apikey'
- $ref: '#/components/parameters/year-with-default'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LowestCostPlanResponse'
summary: Get second lowest cost silver plan
requestBody:
content:
application/json:
schema:
properties:
household:
$ref: '#/components/schemas/LowestCostPlanHousehold'
place:
$ref: '#/components/schemas/Place'
year:
format: integer
type: number
required:
- place
type: object
description: slcsp request object
required: true
operationId: postHouseholdsSlcsp
x-operation-id-source: derived
/households/lcsp:
x-summary: Lookup LCSP
post:
tags:
- Households & Eligibility
description: '#### Note
Use this JSON example in the **POST** Body in the request pane to view results:
```
{
"household": {
"income": 52000,
"people": [
{
"dob": "1992-01-01",
"aptc_eligible": true,
"gender": "Female",
"uses_tobacco": false
}
]
},
"market": "Individual",
"place": {
"countyfips": "37057",
"state": "NC",
"zipcode": "27360"
},
"year": 2020
}
```
Get the lowest cost silver plan for a household.
Response is a plan object with the premium set to the rate for the household.
Note -- when calculating the LCSP for a household that has members in different rating areas, the household must be split by rating area and multiple LCSP requests must be sent, with the results summed at the end (applies only to 2019 ratings).'
parameters:
- $ref: '#/components/parameters/apikey'
- $ref: '#/components/parameters/year-with-default'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LowestCostPlanResponse'
summary: Get lowest cost silver plan
requestBody:
content:
application/json:
schema:
properties:
household:
$ref: '#/components/schemas/LowestCostPlanHousehold'
place:
$ref: '#/components/schemas/Place'
year:
format: integer
type: number
required:
- place
type: object
description: lcsp request object
required: true
operationId: postHouseholdsLcsp
x-operation-id-source: derived
/households/pcfpl:
x-summary: Poverty Level Percentage
get:
tags:
- Households & Eligibility
description: Household income as a percentage of the federal poverty level
parameters:
- $ref: '#/components/parameters/apikey'
- $ref: '#/components/parameters/year-required'
- description: 2-letter USPS state abbreviation, uppercased.
in: query
name: state
required: true
x-example: VA
schema:
type: string
- description: Total size of household
in: query
name: size
required: true
x-example: 5
schema:
type: number
format: integer
- description: Household Income
in: query
name: income
required: true
x-example: 40000
schema:
type: number
format: integer
responses:
'200':
description: Successful response
content:
application/json:
schema:
properties:
pc_fpl:
description: Household income as a percentage of the Federal poverty level
format: float
type: number
type: object
example:
pc_fpl: 146.91
summary: Get households pcfpl
x-summary-source: derived
operationId: getHouseholdsPcfpl
x-operation-id-source: derived
components:
schemas:
GenderEnum:
enum:
- Male
- Female
type: string
Relationship:
description: Should match one of the [listed valid relationships](#introduction/more-information-about-households).
type: string
properties: {}
Eligibility:
properties:
aptc:
format: float
type: number
csr:
$ref: '#/components/schemas/CSREligibilityEnum'
hardship_exemption:
type: boolean
is_medicaid_chip:
type: boolean
type: object
LowestCostPlanHousehold:
properties:
income:
description: household's yearly income in dollars
format: float
type: number
people:
description: people in household applying for coverage/seeking eligibility esimate
items:
$ref: '#/components/schemas/LowestCostPlanPerson'
type: array
example:
income: 60000
people:
- dob: '1979-01-06'
current_plan: 45127PA0020020
csr_variant: no_csr_eligibility
relationship: Self
uses_tobacco: false
age: 39
effective_date: '2019-01-01'
type: object
Household:
description: If a household is not included, will default to Individual household
properties:
income:
description: household's yearly income in dollars
format: float
type: number
unemployment_received:
description: Specifies whether a tax payer or tax dependent in the household received unemployment benefits for market year 2021. May affect ATPC and CSR calulations due to income percentage capping if income is above 133% of the Federal poverty level. If the person who received unemployment is a tax dependent, only the eligible CSRs will be affected. Defaults to None
enum:
- Adult
- Dependent
- None
type: string
people:
description: people in household applying for coverage/seeking eligibility esimate; first is considered the subscriber
items:
$ref: '#/components/schemas/Person'
type: array
has_married_couple:
type: boolean
effective_date:
description: The effective date of the application (YYYY-MM-DD)
type: string
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
example:
income: 20000
people:
- age: 34
dob: '1984-01-06'
is_pregnant: false
is_parent: false
uses_tobacco: false
gender: Male
has_married_couple: false
type: object
Place:
properties:
countyfips:
description: 5-digit county FIPS code
type: string
state:
description: 2-letter USPS state abbreviation
type: string
zipcode:
description: 5-digit ZIP Code
type: string
required:
- countyfips
- state
- zipcode
example:
countyfips: '51107'
state: VA
zipcode: '20103'
type: object
LowestCostPlanResponse:
properties:
id:
type: string
name:
type: string
premium:
type: number
metal_level:
$ref: '#/components/schemas/MetalLevelEnum'
example:
id: 11111PA0000000
name: The Best Plan You Ever Did See
premium: 850.16
metal_level: Bronze
type: object
UtilizationEnum:
enum:
- Low
- Medium
- High
type: string
ICHRAResponse:
properties:
affordable:
type: boolean
premium:
type: number
example:
affordable: 'true'
premium: 850.16
type: object
CurrentEnrollment:
description: Current/existing enrollment information used to determine tobacco status for CiC enrollments. This will ensure rate calculation is done correctly.
required:
- plan_id
- effective_date
- uses_tobacco
properties:
plan_id:
$ref: '#/components/schemas/PlanID'
effective_date:
description: Date plan went into effect (ISO-8601 YYYY-MM-DD)
type: string
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
x-example: '2020-01-01'
uses_tobacco:
type: boolean
type: object
CSREligibilityEnum:
type: string
description: Cost-sharing reduction (CSR)
enum:
- 73% AV Level Silver Plan CSR
- 87% AV Level Silver Plan CSR
- 94% AV Level Silver Plan CSR
properties: {}
PlanID:
type: string
pattern: ^[0-9]{5}[A-Z]{2}[0-9]{7}$
properties: {}
LowestCostPlanPerson:
properties:
age:
format: integer
type: number
uses_tobacco:
type: boolean
default: false
type: object
MetalLevelEnum:
enum:
- Catastrophic
- Silver
- Bronze
- Gold
- Platinum
type: string
properties: {}
Person:
properties:
age:
format: integer
type: number
description: required if dob not provided
dob:
description: A person's date of birth (YYYY-MM-DD) required if age not provided
type: string
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
x-example: '2020-01-01'
has_mec:
description: has minimum essential coverage
type: boolean
is_parent:
type: boolean
is_pregnant:
description: Indicates whether the individual is pregnant or not. If this is true and `pregnant_with` is not provided, `pregnant_with` is assumed to be 1.
type: boolean
pregnant_with:
description: The number of expected children from a pregnancy. If this value is > 0, `is_pregnant` is assumed to be true, even if specified otherwise.
type: number
uses_tobacco:
type: boolean
last_tobacco_use_date:
description: The last date of regular tobacco use (YYYY-MM-DD)
type: string
pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
gender:
$ref: '#/components/schemas/GenderEnum'
utilization_level:
$ref: '#/components/schemas/UtilizationEnum'
relationship:
$ref: '#/components/schemas/Relationship'
does_not_cohabitate:
type: boolean
aptc_eligible:
description: is the given person eligible for APTC
type: boolean
current_enrollment:
$ref: '#/components/schemas/CurrentEnrollment'
type: object
required:
- age
- dob
parameters:
year-with-default:
x-example: 2019
name: year
description: 4 digit market year (Defaults to the current year when not specified).
in: query
required: false
schema:
type: number
format: integer
apikey:
name: apikey
description: API key used for authentication
in: query
required: true
x-example: d687412e7b53146b2631dc01974ad0a4
schema:
type: string
year-required:
x-example: 2019
name: year
description: 4 digit market year.
in: query
required: true
schema:
type: number
format: integer
securitySchemes:
API_Key:
x-summary: API Key Auth
description: Your API key should be included as a query parameter with the request. You can [fill out this form](https://cms.gov1.qualtrics.com/jfe/form/SV_4N2GHCJfNuX7n8x) to request an API key.
type: apiKey
in: query
name: apikey
x-example: d687412e7b53146b2631dc01974ad0a4