Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
AON Medicare Upgrade (2 -> 3)

Migrating from v2 to v3

To aid in the migration from version 2 to version 3 of the medicare-api this document provides specific notes where breaking changes exist.

0. Requesting versions

As the medicare-api grows and requires versioning to accomodate the needs of clients to use stable APIs while there are requests for newer features, the API allows the client to request a specific version using the HTTP Accept header.

It is NOT safe to mix versions of the API within a session (eg. creating a user with v2 API and subsequently requesting a v3 recommendation). Do not do it.

The method of Accept header versioning is the same as used by Github. Currently, the medicare-api does not worry or care what is sent in the HTTP Accept header of a request. If you choose to send it, there are forms and associated interpretations of version that are associated as follows:

Accept value version requested description
null or empty v2 when not provided, the oldest version is assumed
*/* v2 when wildcarded, the oldest version is assumed
application/json v2 when not provided, the oldest version is assumed
application/vnd.picwell+json v2 when not provided, the oldest version is assumed
application/vnd.picwell.v2 v2 this selects v2 of the api explicitly
application/vnd.picwell.v3+json v3 this selects v3 of the api explicitly
application/vnd.picwell.v9+json v2 this selects v9 but that doesn't exist so it would use v2

1. Naming conventions

Relates to

  • API: Recommendation API, Drug Breakdown API, General Convention

Both mail order and retail providers of prescription drugs are pharmacies. To simplify any confusion, references to the two will have keys denoted:

  • mail : mail order pharmacy
  • retail : a retail pharmacy

To clarify that values such as premium, part_b.premium, and part_b.premium_reduction are monthly figures, we have renamed them as such:

  • monthly_premium : monthly premium of the plan
  • part_b.monthly_premium : part b monthly premium
  • part_b.monthly_premium_reduction : part b monthly premium reduction

2. Picwell Score

Relates to

  • API: Recommendation API
  • endpoint : /recommendations/<int: year>/<string: user.id>/
  • returns: Recommendation Object

The score within a Recommendation Object has been changed to include:

  • mail and retail pricing based scores
  • other features compared across the recommended packages

Where in the old structure, score was an integer,

{
  ...
  "results": [
    {
      ...
      "score": <int>
    },
    ...
  ]
}

The new response structure is:

{
  ...
  "results": [
    {
      ...
      "score": {
        "mail": {
          "dimensions": {
            "medicare_star_ratings": <float: 0-100>,
            "risk_protection": <float: 0-100>,
            "health_provider_locations": <float: 0-100>,
            "real_cost": <float: 0-100>
          },
          "picwell_score": <float: 0-100>,
          "tier": <enum>
        },
        "retail": {
          "dimensions": {
            "medicare_star_ratings": <float: 0-100>,
            "risk_protection": <float: 0-100>,
            "health_provider_locations": <float: 0-100>,
            "real_cost": <float: 0-100>
          },
          "picwell_score": <float: 0-100>,
          "tier": <enum>
        }
      }
    },
    ...
  ]
}

3. Partial year recommendations

Relates to

  • API: Recommendation API
  • endpoint : /recommendations/<int: year>/<string: user.id>/
  • returns: Recommendation Object

Estimates for full year costs will always be provided regardless of whether a start_date is provided. They will be reported under the costs.full keys. When the start_date is not within january, a key containing partial year estimates will be provided within costs as a partial key.

The original costs object represented an estimate for the time period requested,

{
  ...
  "results": [
    {
      ...
      "costs": {
        "services": {
          "in_network": <float>,
          "out_network": <float>
        },
        "drugs": {
          "mail": {
            "uncovered": <float>,
            "covered":<float>
          },
          "retail": {
            "uncovered": <float>,
            "covered": <float>
          }
        },
        "part_b": {
          "premium_reduction": <float>,
          "premium": <float>
        },
        "premium": <float>,
        "real_cost": <float>
      }
    },
    ...
  ]
}

To extend this to provide out of pocket cost estimates for both a prorated and full year of coverage, this cost object has been bifurcated to the following structure that is consistently used regardless of input start_date. The partial key within the costs object will NOT be provided when a full year request is made or the proration start_date is within january.

This makes the new structure look like:

{
  ...
  "results": [
    {
      ...
      "costs": {
        "full": {
          "services": {
            ...
          },
          "drugs": {
            "mail": {
              "uncovered": <float>,
              "covered":<float>
            },
            "retail": {
              "uncovered": <float>,
              "covered": <float>
            }
          },
          "part_b": {
            "premium_reduction": <float>,
            "premium": <float>
          },
          "premium": <float>,
          "real_cost": <float>
        },
        "partial": {
          "services": {
            ...
          },
          "drugs": {
            "mail": {
              "uncovered": <float>,
              "covered":<float>
            },
            "retail": {
              "uncovered": <float>,
              "covered": <float>
            }
          },
          "part_b": {
            "premium_reduction": <float>,
            "premium": <float>
          },
          "premium": <float>,
          "real_cost": <float>
        }
      }
    },
    ...
  ]
}

4. BYO Drug Costs

Relates to

  • API: Recommendation API
  • endpoint : /recommendations/<int: year>/<string: user.id>/
  • returns: Recommendation Object

To allow extensibility and easier integration, the API now accepts total drug costs as an input to recommendation requests within the Plan Reference.

To provide these drug costs, the Plan Reference POST body object has been updated to include a drug_costs key. This makes the object look like:

[{
  "type": <string>,
  "external_id": <string>,
  "drug_costs": {
    "retail": <float>,
    "mail": <float>
  },
  ...
},
...
]

Because these drug costs are externally provided, Picwell can no longer provide as granular cost estimates and this is reflected in the use of the total key within the costs.drugs object. When recommendations are provided, the costs object is changed to parrot back the client-provided costs. This output looks like:

{
  ...
  "results": [
    {
      ...
      "costs": {
        "full": {
          "services": {
            ...
          },
          "drugs": {
            "mail": {
              "total": <client provided float>,
            },
            "retail": {
              "total": <client provided float>,
            }
          },
          "part_b": {
            "premium_reduction": <float>,
            "premium": <float>
          },
          "premium": <float>,
          "real_cost": <float>
        },
        "partial": {
          "services": {
            ...
          },
          "part_b": {
            "premium_reduction": <float>,
            "premium": <float>
          },
          "premium": <float>,
        }
      }
    },
    ...
  ]
}

Note When providing drug_costs and making a partial year request (start_date is set and not january 1st), the drugs key within the costs.partial object will not be present.

This is also true of the real_cost and drug_coverage fields. Since real_cost is a function of drug_costs, it cannot be represented for partial years with client-provided data. drug_coverage is removed because it requires information about fills and costs that are unavailable.

5. RealCost

Instead of being a single figure, the real_cost is now split into two separate pieces to provide better visibility. The mean as well as the deciles for the distribution of the real_cost are now values. This will allow representation of the distribution.

This makes the real_cost attribute within a package look like:

{
  ...
  "results": [
    {
      ...
      "costs": {
        "full": {
          ...
          "real_cost": {
            "mean": <float>,
            "deciles": [ float, float, float, float, float, ... ]
          }
        },
        ...
      }
    },
    ...
  ]
}

5. Extended Health Provider Locations

Relates to

  • API: Recommendation API, Breakdown API
  • endpoint: /recommendations/<int: year>/<string: user.id>/, /recommendation/breakdown/...

Beyond simply in- and out- of health network locations, there is an "extended" health provider location within the world of medicare health insurance. To support this, we've added this to our Plan reference object that is input as a consideration for the Recommendation and Breakdown APIs.

This adds a key extended_network to health_provider_locations in the Plan Reference. For example,

{
  ...
  "health_provider_locations" : {
    "in_network": [{...}, ...],
    "extended_network": [
      {
        "external_id": "exampleexternalid",
        "type": "mapd",
        "specialty": "eating""
      },
      ...
    ],
    "out_of_network": [{...}, ...]
  }
}
  • API: Recommendation API
  • endpoint : /recommendations/<int: year>/<string: user.id>/
  • returns: Recommendation Object

To allow extensibility and easier integration, the API now accepts total drug costs as an input to recommendation requests within the Plan Reference.

7. Services Costs statistics

Relates to

  • API: Recommendation API
  • endpoint: /recommendations/<int: year>/<string: user.id>/

To add detail to our in- and out- of network cost estimates, we will now be providing them with mean and deciles. In the case of out_network, the deciles is not included.

Where the original costs substructure to the Recommendation object inside of the results looked like,

{
  ...
  "results": [
    {
      ...
      "costs": {
        "full": {
          "services": {
            "in_network": <float>,
            "out_network": <float>
          },
          "drugs": {...},
          ...
          "real_cost": <float>
        }
      }
    },
    ...
  ]
}

the new form of the cost structure extends it to look like:

{
  ...
  "results": [
    {
      ...
      "costs": {
        "full": {
          "services": {
            "in_network": {
              "mean": <float>,
              "deciles": [float, float, ...]
            }
            "out_network": {
              "mean": <float>
            }
          },
          "drugs": {...},
          ...
          "real_cost": <float>
        }
      }
    },
    ...
  ]
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.