Household

If a household is not included, will default to Individual household

HealthcareMedicareMedicaidFHIRBulk DataOpen DataGovernmentFederalClaimsInsuranceACAMarketplaceQualityHealth InsuranceFederal GovernmentDrug SpendingProvider DataQuality MeasuresClaims DataGovernment Data

Properties

Name Type Description
income number household's yearly income in dollars
unemployment_received string 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 a
people array people in household applying for coverage/seeking eligibility esimate; first is considered the subscriber
has_married_couple boolean
effective_date string The effective date of the application (YYYY-MM-DD)
View JSON Schema on GitHub

JSON Schema

cms-gov-household-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cms-gov/json-schema/cms-gov-household-schema.json",
  "title": "Household",
  "description": "If a household is not included, will default to Individual household",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cms-gov-households-eligibility-api-openapi.yml#/components/schemas/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": "#/$defs/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}$"
    }
  },
  "type": "object",
  "$defs": {
    "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": "#/$defs/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"
    },
    "GenderEnum": {
      "enum": [
        "Male",
        "Female"
      ],
      "type": "string"
    },
    "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": "#/$defs/GenderEnum"
        },
        "utilization_level": {
          "$ref": "#/$defs/UtilizationEnum"
        },
        "relationship": {
          "$ref": "#/$defs/Relationship"
        },
        "does_not_cohabitate": {
          "type": "boolean"
        },
        "aptc_eligible": {
          "description": "is the given person eligible for APTC",
          "type": "boolean"
        },
        "current_enrollment": {
          "$ref": "#/$defs/CurrentEnrollment"
        }
      },
      "type": "object",
      "required": [
        "age",
        "dob"
      ]
    },
    "PlanID": {
      "type": "string",
      "pattern": "^[0-9]{5}[A-Z]{2}[0-9]{7}$",
      "properties": {}
    },
    "Relationship": {
      "description": "Should match one of the [listed valid relationships](#introduction/more-information-about-households).",
      "type": "string",
      "properties": {}
    },
    "UtilizationEnum": {
      "enum": [
        "Low",
        "Medium",
        "High"
      ],
      "type": "string"
    }
  }
}

Work with this as data

Every JSON Schema 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 schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • 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.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/cms-gov-household"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

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.