Plans

Export plan benefit datasets through Ideon's API

Creating a bulk export with a type of plans generates a file containing plans that are available to the user and their associated benefits. In this file, each JSON Line represents a unique plan object. The following request will generate a file with all plans that are available for quoting in the given filters.year, based on the permissions of the API key making the request.

POST /bulk_exports

{ 
    "type": "plans",
    "filters": {
        "year": 2026
    }
}

In the Individual Medical, Small Group Medical, and Medicare Advantage markets, plans are unique by plan year. In these markets, plan identifiers (HIOS IDs or Medicare Advantage Contract IDs) can be re-used across years, but plans are specific to the given year. Ancillary and Level Funded plans can be available across multiple years; plans unique by their id will be consistent across years.

The schema for each plan object can differ based on the product line and audience for the plan. The schema for the benefits and metadata for the plan can be found in the various "Show Plan" endpoints in Ideon's technical API documentation. Additionally, complete grammar guides for some product lines are included in the Benefit Grammar Guide section. The id field present for every plan can be used to uniquely identify the plan for the given year. The product_line and audience keys can be used to identify which plan schema to expect.

Truncated Sample Plan Benefit JSON Line

{
    "id": "12345NY0000001",
    "product_line": "medical",
    "audience": "individual",
    "service_area_id": "12345-2026-NY001-individual",
    // .... additional benefit and metadata keys vary by product_line and audience
}

Caching Benefits

The bulk export always returns the complete set of available plans given the filter parameters. Given this, processes to generate bulk exports to cache benefits should always fully replace data for any plans returned in previous files.

In order to deliver a seamless and performant end-user experience, we recommend caching benefits on a regular cadence using the bulk exports endpoint. This data can then be accessed more quickly in real-time to present to end users. Cached benefits can be linked by ID and year to the plan IDs returned for the real-time quote.

We recommend configuring the cadence of exports to cache benefits based 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.

Filtered Exports

It is also recommended to maintain the ability to pull a filtered plan export file on an ad hoc basis. This can be useful if users are looking to capture important plan updates or additions between automated runs. Filters can optionally be used to reduce processing time and file size for these types of runs. As an example, the following request could be used to export the individual medical plans available in NY for plan year 2026.

POST /bulk_exports

{
   "type": "plans",
    "filters": {
        "product_line": "medical",
        "market": "individual",
        "year": 2026,
        "states": ["NY"]
    }
}

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. These plans can then be quoted in real-time by a user, leading to the scenario where a plan is quoted but it's benefits are not yet cached.

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 Plan Search endpoint for the associated line of coverage. An example of this can be seen below with the "Medical Plan Search" endpoint (API docs). 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>"
    ]
}