{
  "openapi": "3.1.0",
  "info": {
    "title": "SJI private-only health insurance estimates",
    "version": "1.0.0",
    "description": "State and household estimates without income, employer eligibility or CMS access. Not named carrier quotes."
  },
  "servers": [
    {
      "url": "https://sjiadvisory.com"
    }
  ],
  "security": [],
  "paths": {
    "/api/private-estimate": {
      "get": {
        "operationId": "getPrivateHealthEstimate",
        "summary": "Private estimate; no query returns instructions",
        "description": "Supply all required fields for a calculation. Omit the whole query for service documentation.",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "AL",
                "AK",
                "AZ",
                "AR",
                "CA",
                "CO",
                "CT",
                "DE",
                "DC",
                "FL",
                "GA",
                "HI",
                "ID",
                "IL",
                "IN",
                "IA",
                "KS",
                "KY",
                "LA",
                "ME",
                "MD",
                "MA",
                "MI",
                "MN",
                "MS",
                "MO",
                "MT",
                "NE",
                "NV",
                "NH",
                "NJ",
                "NM",
                "NY",
                "NC",
                "ND",
                "OH",
                "OK",
                "OR",
                "PA",
                "RI",
                "SC",
                "SD",
                "TN",
                "TX",
                "UT",
                "VT",
                "VA",
                "WA",
                "WV",
                "WI",
                "WY"
              ],
              "description": "Two-letter state code. This estimate uses state-level rates; a ZIP is not needed."
            }
          },
          {
            "name": "age",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 18,
              "maximum": 64,
              "description": "Primary adult age."
            }
          },
          {
            "name": "sex",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "male",
                "female"
              ],
              "description": "Primary adult sex used by the rate method."
            }
          },
          {
            "name": "kids",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 6,
              "description": "Number of children seeking coverage. Use zero only if no children are included."
            }
          },
          {
            "name": "year",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "enum": [
                2026,
                2027
              ],
              "description": "Explicit coverage year. The estimate basis is currently 2026; 2027 returns unavailable."
            }
          },
          {
            "name": "spouse_age",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 18,
              "maximum": 64,
              "description": "Optional spouse age. Supply spouse_sex too."
            }
          },
          {
            "name": "spouse_sex",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "male",
                "female"
              ],
              "description": "Optional spouse sex used by the rate method. Supply spouse_age too."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A private estimate, or service documentation for a bare GET. Unavailable estimates have no prices.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "required": [
                        "ok",
                        "status",
                        "calculated_at",
                        "inputs",
                        "private",
                        "citation"
                      ],
                      "properties": {
                        "ok": {
                          "type": "boolean",
                          "const": true
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "available",
                            "unavailable"
                          ]
                        },
                        "calculated_at": {
                          "type": "string",
                          "format": "date-time",
                          "description": "UTC timestamp of this calculation. Private-only results are calculated per request and are not cached."
                        },
                        "requested_plan_year": {
                          "type": "integer"
                        },
                        "currency": {
                          "const": "USD"
                        },
                        "payment_period": {
                          "const": "month"
                        },
                        "inputs": {
                          "type": "object",
                          "properties": {
                            "state": {
                              "type": "string",
                              "enum": [
                                "AL",
                                "AK",
                                "AZ",
                                "AR",
                                "CA",
                                "CO",
                                "CT",
                                "DE",
                                "DC",
                                "FL",
                                "GA",
                                "HI",
                                "ID",
                                "IL",
                                "IN",
                                "IA",
                                "KS",
                                "KY",
                                "LA",
                                "ME",
                                "MD",
                                "MA",
                                "MI",
                                "MN",
                                "MS",
                                "MO",
                                "MT",
                                "NE",
                                "NV",
                                "NH",
                                "NJ",
                                "NM",
                                "NY",
                                "NC",
                                "ND",
                                "OH",
                                "OK",
                                "OR",
                                "PA",
                                "RI",
                                "SC",
                                "SD",
                                "TN",
                                "TX",
                                "UT",
                                "VT",
                                "VA",
                                "WA",
                                "WV",
                                "WI",
                                "WY"
                              ],
                              "description": "Two-letter state code. This estimate uses state-level rates; a ZIP is not needed."
                            },
                            "age": {
                              "type": "integer",
                              "minimum": 18,
                              "maximum": 64,
                              "description": "Primary adult age."
                            },
                            "sex": {
                              "type": "string",
                              "enum": [
                                "male",
                                "female"
                              ],
                              "description": "Primary adult sex used by the rate method."
                            },
                            "kids": {
                              "type": "integer",
                              "minimum": 0,
                              "maximum": 6,
                              "description": "Number of children seeking coverage. Use zero only if no children are included."
                            },
                            "year": {
                              "type": "integer",
                              "enum": [
                                2026,
                                2027
                              ],
                              "description": "Explicit coverage year. The estimate basis is currently 2026; 2027 returns unavailable."
                            },
                            "spouse_age": {
                              "type": "integer",
                              "minimum": 18,
                              "maximum": 64,
                              "description": "Optional spouse age. Supply spouse_sex too."
                            },
                            "spouse_sex": {
                              "type": "string",
                              "enum": [
                                "male",
                                "female"
                              ],
                              "description": "Optional spouse sex used by the rate method. Supply spouse_age too."
                            }
                          }
                        },
                        "private": {
                          "type": "object",
                          "properties": {
                            "status": {
                              "enum": [
                                "rough_estimate",
                                "unavailable"
                              ]
                            },
                            "estimate_basis_year": {
                              "type": "integer"
                            },
                            "low_monthly_usd": {
                              "type": "number"
                            },
                            "high_monthly_usd": {
                              "type": "number"
                            },
                            "middle_monthly_usd": {
                              "type": "number"
                            },
                            "tiers_monthly_usd": {
                              "type": [
                                "array",
                                "null"
                              ],
                              "items": {
                                "type": "number"
                              }
                            },
                            "method": {
                              "type": "string"
                            },
                            "is_carrier_quote": {
                              "const": false
                            },
                            "reason": {
                              "type": "string"
                            },
                            "pricing_levels": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "name": {
                                    "type": "string"
                                  },
                                  "description": {
                                    "type": "string"
                                  },
                                  "monthly_usd": {
                                    "type": "number"
                                  }
                                }
                              }
                            }
                          }
                        },
                        "citation": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "url": {
                              "type": "string",
                              "format": "uri"
                            },
                            "methodology_url": {
                              "type": "string",
                              "format": "uri"
                            }
                          }
                        },
                        "assumptions": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "limitations": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "scope": {
                          "const": "private_only"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "ok": {
                          "const": true
                        },
                        "status": {
                          "const": "documentation"
                        },
                        "scope": {
                          "const": "private_only"
                        }
                      },
                      "required": [
                        "ok",
                        "status",
                        "scope"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid fields; missing fields include definitions."
          },
          "405": {
            "description": "Use GET or POST."
          },
          "413": {
            "description": "Body exceeds 4096 bytes."
          },
          "415": {
            "description": "Use application/json."
          },
          "503": {
            "description": "Temporarily unavailable."
          }
        }
      },
      "post": {
        "operationId": "postPrivateHealthEstimate",
        "summary": "Calculate a private household estimate",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "state",
                  "age",
                  "sex",
                  "kids",
                  "year"
                ],
                "properties": {
                  "state": {
                    "type": "string",
                    "enum": [
                      "AL",
                      "AK",
                      "AZ",
                      "AR",
                      "CA",
                      "CO",
                      "CT",
                      "DE",
                      "DC",
                      "FL",
                      "GA",
                      "HI",
                      "ID",
                      "IL",
                      "IN",
                      "IA",
                      "KS",
                      "KY",
                      "LA",
                      "ME",
                      "MD",
                      "MA",
                      "MI",
                      "MN",
                      "MS",
                      "MO",
                      "MT",
                      "NE",
                      "NV",
                      "NH",
                      "NJ",
                      "NM",
                      "NY",
                      "NC",
                      "ND",
                      "OH",
                      "OK",
                      "OR",
                      "PA",
                      "RI",
                      "SC",
                      "SD",
                      "TN",
                      "TX",
                      "UT",
                      "VT",
                      "VA",
                      "WA",
                      "WV",
                      "WI",
                      "WY"
                    ],
                    "description": "Two-letter state code. This estimate uses state-level rates; a ZIP is not needed."
                  },
                  "age": {
                    "type": "integer",
                    "minimum": 18,
                    "maximum": 64,
                    "description": "Primary adult age."
                  },
                  "sex": {
                    "type": "string",
                    "enum": [
                      "male",
                      "female"
                    ],
                    "description": "Primary adult sex used by the rate method."
                  },
                  "kids": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 6,
                    "description": "Number of children seeking coverage. Use zero only if no children are included."
                  },
                  "year": {
                    "type": "integer",
                    "enum": [
                      2026,
                      2027
                    ],
                    "description": "Explicit coverage year. The estimate basis is currently 2026; 2027 returns unavailable."
                  },
                  "spouse_age": {
                    "type": "integer",
                    "minimum": 18,
                    "maximum": 64,
                    "description": "Optional spouse age. Supply spouse_sex too."
                  },
                  "spouse_sex": {
                    "type": "string",
                    "enum": [
                      "male",
                      "female"
                    ],
                    "description": "Optional spouse sex used by the rate method. Supply spouse_age too."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A private estimate, or service documentation for a bare GET. Unavailable estimates have no prices.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "required": [
                        "ok",
                        "status",
                        "calculated_at",
                        "inputs",
                        "private",
                        "citation"
                      ],
                      "properties": {
                        "ok": {
                          "type": "boolean",
                          "const": true
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "available",
                            "unavailable"
                          ]
                        },
                        "calculated_at": {
                          "type": "string",
                          "format": "date-time",
                          "description": "UTC timestamp of this calculation. Private-only results are calculated per request and are not cached."
                        },
                        "requested_plan_year": {
                          "type": "integer"
                        },
                        "currency": {
                          "const": "USD"
                        },
                        "payment_period": {
                          "const": "month"
                        },
                        "inputs": {
                          "type": "object",
                          "properties": {
                            "state": {
                              "type": "string",
                              "enum": [
                                "AL",
                                "AK",
                                "AZ",
                                "AR",
                                "CA",
                                "CO",
                                "CT",
                                "DE",
                                "DC",
                                "FL",
                                "GA",
                                "HI",
                                "ID",
                                "IL",
                                "IN",
                                "IA",
                                "KS",
                                "KY",
                                "LA",
                                "ME",
                                "MD",
                                "MA",
                                "MI",
                                "MN",
                                "MS",
                                "MO",
                                "MT",
                                "NE",
                                "NV",
                                "NH",
                                "NJ",
                                "NM",
                                "NY",
                                "NC",
                                "ND",
                                "OH",
                                "OK",
                                "OR",
                                "PA",
                                "RI",
                                "SC",
                                "SD",
                                "TN",
                                "TX",
                                "UT",
                                "VT",
                                "VA",
                                "WA",
                                "WV",
                                "WI",
                                "WY"
                              ],
                              "description": "Two-letter state code. This estimate uses state-level rates; a ZIP is not needed."
                            },
                            "age": {
                              "type": "integer",
                              "minimum": 18,
                              "maximum": 64,
                              "description": "Primary adult age."
                            },
                            "sex": {
                              "type": "string",
                              "enum": [
                                "male",
                                "female"
                              ],
                              "description": "Primary adult sex used by the rate method."
                            },
                            "kids": {
                              "type": "integer",
                              "minimum": 0,
                              "maximum": 6,
                              "description": "Number of children seeking coverage. Use zero only if no children are included."
                            },
                            "year": {
                              "type": "integer",
                              "enum": [
                                2026,
                                2027
                              ],
                              "description": "Explicit coverage year. The estimate basis is currently 2026; 2027 returns unavailable."
                            },
                            "spouse_age": {
                              "type": "integer",
                              "minimum": 18,
                              "maximum": 64,
                              "description": "Optional spouse age. Supply spouse_sex too."
                            },
                            "spouse_sex": {
                              "type": "string",
                              "enum": [
                                "male",
                                "female"
                              ],
                              "description": "Optional spouse sex used by the rate method. Supply spouse_age too."
                            }
                          }
                        },
                        "private": {
                          "type": "object",
                          "properties": {
                            "status": {
                              "enum": [
                                "rough_estimate",
                                "unavailable"
                              ]
                            },
                            "estimate_basis_year": {
                              "type": "integer"
                            },
                            "low_monthly_usd": {
                              "type": "number"
                            },
                            "high_monthly_usd": {
                              "type": "number"
                            },
                            "middle_monthly_usd": {
                              "type": "number"
                            },
                            "tiers_monthly_usd": {
                              "type": [
                                "array",
                                "null"
                              ],
                              "items": {
                                "type": "number"
                              }
                            },
                            "method": {
                              "type": "string"
                            },
                            "is_carrier_quote": {
                              "const": false
                            },
                            "reason": {
                              "type": "string"
                            },
                            "pricing_levels": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "name": {
                                    "type": "string"
                                  },
                                  "description": {
                                    "type": "string"
                                  },
                                  "monthly_usd": {
                                    "type": "number"
                                  }
                                }
                              }
                            }
                          }
                        },
                        "citation": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "url": {
                              "type": "string",
                              "format": "uri"
                            },
                            "methodology_url": {
                              "type": "string",
                              "format": "uri"
                            }
                          }
                        },
                        "assumptions": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "limitations": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "scope": {
                          "const": "private_only"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "ok": {
                          "const": true
                        },
                        "status": {
                          "const": "documentation"
                        },
                        "scope": {
                          "const": "private_only"
                        }
                      },
                      "required": [
                        "ok",
                        "status",
                        "scope"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid fields; missing fields include definitions."
          },
          "405": {
            "description": "Use GET or POST."
          },
          "413": {
            "description": "Body exceeds 4096 bytes."
          },
          "415": {
            "description": "Use application/json."
          },
          "503": {
            "description": "Temporarily unavailable."
          }
        }
      }
    }
  },
  "externalDocs": {
    "url": "https://sjiadvisory.com/estimate/private-guide.txt"
  }
}