{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cms-gov/json-schema/cms-gov-plan-search-request-schema.json",
  "title": "PlanSearchRequest",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cms-gov-insurance-plans-api-openapi.yml#/components/schemas/PlanSearchRequest",
  "properties": {
    "filter": {
      "$ref": "#/$defs/PlanSearchFilter"
    },
    "household": {
      "$ref": "#/$defs/Household"
    },
    "offset": {
      "type": "number"
    },
    "order": {
      "enum": [
        "asc",
        "desc"
      ],
      "type": "string"
    },
    "place": {
      "$ref": "#/$defs/Place"
    },
    "sort": {
      "enum": [
        "premium",
        "deductible",
        "oopc",
        "total_costs",
        "quality_rating"
      ],
      "type": "string"
    },
    "year": {
      "description": "defaults to current open enrollment year",
      "x-example": 2019,
      "type": "number"
    },
    "market": {
      "$ref": "#/$defs/MarketEnum"
    },
    "aptc_override": {
      "description": "override the aptc calculation with a specific amount",
      "type": "number"
    },
    "csr_override": {
      "$ref": "#/$defs/CSRRequestEnum"
    },
    "catastrophic_override": {
      "description": "Force the display (or suppression) of catastrophic plans",
      "type": "boolean"
    },
    "suppressed_plan_ids": {
      "$ref": "#/$defs/PlanIDList"
    }
  },
  "required": [
    "place",
    "market"
  ],
  "type": "object",
  "$defs": {
    "CSRRequestEnum": {
      "type": "string",
      "description": "Cost-sharing reduction (CSR) override for requests",
      "enum": [
        "CSR73",
        "CSR87",
        "CSR94",
        "LimitedCSR",
        "ZeroCSR"
      ]
    },
    "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"
    },
    "DesignTypeEnum": {
      "enum": [
        "DESIGN1",
        "DESIGN2",
        "DESIGN3",
        "DESIGN4",
        "DESIGN5",
        "NOT_APPLICABLE"
      ],
      "type": "string",
      "properties": {}
    },
    "DiseaseMgmtProgramsEnum": {
      "enum": [
        "Asthma",
        "Heart Disease",
        "Depression",
        "Diabetes",
        "High Blood Pressure and High Cholesterol",
        "Low Back Pain",
        "Pain Management",
        "Pregnancy",
        "Weight Loss Programs"
      ],
      "type": "string",
      "properties": {}
    },
    "GenderEnum": {
      "enum": [
        "Male",
        "Female"
      ],
      "type": "string"
    },
    "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": "#/$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"
    },
    "MarketEnum": {
      "enum": [
        "Individual",
        "SHOP",
        "Any"
      ],
      "type": "string",
      "properties": {}
    },
    "MetalDesignType": {
      "properties": {
        "metal_level": {
          "$ref": "#/$defs/MetalLevelEnum"
        },
        "design_types": {
          "items": {
            "$ref": "#/$defs/DesignTypeEnum"
          },
          "type": "array"
        }
      }
    },
    "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": "#/$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"
      ]
    },
    "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"
      ],
      "type": "object"
    },
    "PlanID": {
      "type": "string",
      "pattern": "^[0-9]{5}[A-Z]{2}[0-9]{7}$",
      "properties": {}
    },
    "PlanIDList": {
      "items": {
        "type": "string",
        "pattern": "^[0-9]{5}[A-Z]{2}[0-9]{7}(,[0-9]{5}[A-Z]{2}[0-9]{7})*$"
      },
      "type": "array"
    },
    "PlanSearchFilter": {
      "description": "plan search filter",
      "properties": {
        "disease_mgmt_programs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/DiseaseMgmtProgramsEnum"
          }
        },
        "division": {
          "$ref": "#/$defs/ProductDivisionEnum"
        },
        "issuer": {
          "description": "Issuer name",
          "type": "string"
        },
        "issuers": {
          "description": "A List of Issuers names",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "metal_levels": {
          "description": "A list of Metalic Levels",
          "type": "array",
          "items": {
            "$ref": "#/$defs/MetalLevelEnum"
          }
        },
        "metal_level": {
          "$ref": "#/$defs/MetalLevelEnum"
        },
        "metal_design_types": {
          "description": "A list of Plan Design Type / Metalic Level Combinations",
          "type": "array",
          "items": {
            "$ref": "#/$defs/MetalDesignType"
          }
        },
        "design_types": {
          "description": "A list of Plan Design Types",
          "type": "array",
          "items": {
            "$ref": "#/$defs/DesignTypeEnum"
          }
        },
        "premium": {
          "type": "number"
        },
        "type": {
          "$ref": "#/$defs/PlanTypeEnum"
        },
        "types": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PlanTypeEnum"
          },
          "description": "a list of plan types"
        },
        "deductible": {
          "type": "number"
        },
        "hsa": {
          "description": "HSA eligibilty",
          "type": "boolean"
        },
        "oopc": {
          "description": "Out of Pocket Costs",
          "type": "number"
        },
        "child_dental_coverage": {
          "description": "Only show plans with child dental coverage",
          "type": "boolean"
        },
        "adult_dental_coverage": {
          "description": "Only show plans with adult dental coverage",
          "type": "boolean"
        },
        "drugs": {
          "description": "A list of RXCUIs",
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9]{5,7}$"
          }
        },
        "providers": {
          "description": "A list of NPIs",
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[0-9]{10}$"
          }
        },
        "quality_rating": {
          "description": "Quality ratings for a plan",
          "type": "number"
        },
        "simple_choice": {
          "type": "boolean"
        },
        "premium_range": {
          "$ref": "#/$defs/Range"
        },
        "deductible_range": {
          "$ref": "#/$defs/Range"
        }
      },
      "type": "object"
    },
    "PlanTypeEnum": {
      "enum": [
        "Indemnity",
        "PPO",
        "HMO",
        "EPO",
        "POS"
      ],
      "type": "string"
    },
    "ProductDivisionEnum": {
      "enum": [
        "HealthCare",
        "Dental"
      ],
      "type": "string"
    },
    "Range": {
      "properties": {
        "min": {
          "format": "float",
          "type": "number"
        },
        "max": {
          "format": "float",
          "type": "number"
        }
      },
      "type": "object"
    },
    "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"
    }
  }
}