Cache Benefits

Pre-load health plan inventory and benefits

In order to deliver a seamless and performant end-user experience, we recommend caching available plans and their benefits on a regular cadence. This data can then be accessed more quickly in real-time to present to end users.

Bulk Exports

The "Create Bulk Export" endpoint (API docs) is built to service this workflow. This endpoint supports asynchronous generation of complete plan benefits files.

To pull all the plans that are available to be quoted, you can iterate through the market, state, product_line, and year parameters. Repeat this process for every set of parameters you plan to support in real-time quoting to ensure all available plans are captured.

The "Plans in Bulk" endpoint always returns the complete set of available plans with the latest benefit updates. Given this, runs to add or update plan benefit inventory should always fully replace data from previous runs. A plan in the SG Medical market is defined uniquely by its HIOS ID and plan year (represented in the response schema id and year fields). An overview of the benefit grammar and schema can be found in the Medical Benefit Grammar Guide section.

A sample request that would return paginated results for Small Group Medical plans for plan year 2025 in the state of California:

POST /plans/bulk?per_page=100&page=1

{
    "state": "CA",
    "year": "2025",
    "market": "small_group",
    "product_line": "medical"
}

The default pagination for this endpoint enforces a maximum of 20 results per page. We recommend including pagination parameters in your request structure and requesting 100 per page to optimize performance.

Running the Batch Process

Cadence of Automated Runs

We recommend scheduling the cadence of your automated runs depending on the time of year. The cadences recommended below reflect the increased frequency of plan additions and updates when plans for the new plan year are being processed. All automated runs should be scheduled overnight (for United States time zones) in order to optimize performance.

• September - November: daily runs, as plan inventory is being added to and updated more regularly as plans for the new plan year are being acquired and processed.

• Outside of September - November: weekly runs, as plan inventory is updated less regularly.

Ad Hoc Runs

We also recommend maintaining a process that mirrors the automated runs - or some subset iterations of it - that can be manually triggered as needed. This can be used for high-priority plan updates or additions that might come up between automated run schedules.

Catch All for New Plans

During the September through November time range, when new plans are being added more regularly, it is possible that plans are published midday, prior to automated runs bringing in their benefit data. While in reality this type of scenario is rare, it is worth planning for in order to always present all available plans and their benefits to users. If this scenario occurs, we recommend performing an ad-hoc request to the "Medical Plan Search" endpoint (API docs) configured with the below parameters. This will return the benefits sets for the requested plans.

POST /plans/medical/search

{
    "zip_code": <Quoted Zip Code>,
    "fips_code": <Quoted FIPS Code>,
    "enrollment_date": <Quoted Enrollment Date>,
    "market": "small_group",
    "ids": [
        <List of HIOS IDs that are not yet cached>
    ]
}