To aid in the migration from version 2 to version 3 of the medicare-api this document
provides specific notes where breaking changes exist.
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 |
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 pharmacyretail: 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 planpart_b.monthly_premium: part b monthly premiumpart_b.monthly_premium_reduction: part b monthly premium reduction
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:
mailandretailpricing 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>
}
}
},
...
]
}
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>
}
}
},
...
]
}
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.
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, ... ]
}
},
...
}
},
...
]
}
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.
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>
}
}
},
...
]
}