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:
    PlanID:
      type: string
      pattern: ^[0-9]{5}[A-Z]{2}[0-9]{7}$
      properties: {}
    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: {}
    GenderEnum:
      enum:
      - Male
      - Female
      type: string
    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
    MetalLevelEnum:
      enum:
      - Catastrophic
      - Silver
      - Bronze
      - Gold
      - Platinum
      type: string
      properties: {}
    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
    Eligibility:
      properties:
        aptc:
          format: float
          type: number
        csr:
          $ref: '#/components/schemas/CSREligibilityEnum'
        hardship_exemption:
          type: boolean
        is_medicaid_chip:
          type: boolean
      type: object
    Relationship:
      description: Should match one of the [listed valid relationships](#introduction/more-information-about-households).
      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
    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
    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
    LowestCostPlanPerson:
      properties:
        age:
          format: integer
          type: number
        uses_tobacco:
          type: boolean
          default: false
      type: object
    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
    UtilizationEnum:
      enum:
      - Low
      - Medium
      - High
      type: string
  parameters:
    year-required:
      x-example: 2019
      name: year
      description: 4 digit market year.
      in: query
      required: true
      schema:
        type: number
        format: integer
    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
  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