NAV Navbar

Introduction

#    .-------....                  ....-------|
#    /ssssssyyso++:.            .:++osyyssssss:
#    /ssssssyyyyo+++:         `/+++syyyyssssss:
#    /ssssssyyyyy++++:        +++++yyyyyssssss:
#    +++++oooooo++++++////////+++++ooooooo++++/
#    +++++++++++++++++++++++++++++++++++++++++/
#    +++++++++++++++++++++++++++++++++++++++++/
#    +++++sydhhddhs++++++++++++++shdhhdhyo++++/
#    +++odh/``.``:ydo++++++++++yms-`..`.+dh+++/
#    ++oms :hmm/-: omo++++++++ym: odmm.:.`hd++/
#    ++yN.`dmmmmmm`.mmddddddddmd -mmmmmms +mo+/
#    ++omo /dmmmm+ +mo++++++++ym-`smmmmh.`hd++/
#    +++smy-`-:-`-smo+++++++++/yd+.`::.`:hdo++/
#    +++++shdhyhhhs///+++++++///+yhhyyhdyo++++/
#    +++++///////:/:://++++++//::/:////:/+++++/
#    +++++/:::::::::::/++++o+///::::::::/+++++/
#    +++++/::::::::::://++os//::/:::::::/+++++/
#    hmhs+//////////////+/++/:--:////////+oydm+
#    hmmmmh+/////////////////:--:///////odmmmm/
#    hmmmmmmh+::::://///:////::::::::/odmmmmmm/
#    ymmmmmmmmy////::/:::://:://////+hmmmmmmmm/
#    ymmmmmmmmmdo+++///++/:/:/+++++ommmmmmmmmm/
#    smmmmmmmmmmmo+++++++++//+++++smmmmmmmmmmm+
#    smmmmmmmmmmmmo++++++++++++++smmmmmmmmmmmm/
#    +mmmmmmmmmmmmdoo++++++++++oommmmmmmmmmmmm:
#    .mmmmmmmmmmmmmyoooooooooooohmmmmmmmmmmmmd
#     :mmmmmmmmmmmmmooooooooooosmmmmmmmmmmmmm-
#      /mmmmmmmmmmmmyoooooooooohmmmmmmmmmmmd.
#       .hmmmmmmmmmmy+osssssso+dmmmmmmmmmms`
#         /dmmmmmmmmh+++osso+++dmmmmmmmmh:
#          `/dmmmmmmh++++++++++mmmmmmmy:
#             :hmmmms-/++++++/:mmmmmy-
#               :hmms  -/++/.  dmmy-
#                 :ho    -.    dy-
#                              `

Welcome!

Picwell's Medicare API primarily generates recommendations for packages of eligible Medicare plans based on a user's demographics, drug usage, and other information. All the packages considered offer coverage for both health and drug:

The API also supports recommendations for specific Medicare plan types, as described here.

Changelog

API

Documentation

Environments

Picwell operates two distinct and isolated environments on behalf of its clients.

UAT

Our User Acceptance Testing environment is a shared testing environment between Picwell and a client. New features and functionality are regularly released into UAT for preview by our clients. Pending their validation, they are released into Production.

Production

Our Production environment is our live environment, geared for serving live traffic from our clients. New features and functionality are only deployed here after clearing UAT preview.

Change Management

Changes to Picwell's APIs are first previewed in our UAT environment. Changes to UAT can occur as frequently as every 2 weeks, synchronized with our agile development process. Pending client validation, new features are eligible to pushed into production.

Security

Picwell is committed to securely managing data collected through our clients. Our broad security posture includes:

To this end, Picwell will require from its clients:

Formats

Encoding

All POST and PUT requests made to the Medicare API must specify a Content-Type header of application/json.

All API responses will contain a Content-Type of application/json by default.

Authentication

The Medicare service uses authentication tokens to allow access to the API. Once acquired, the authentication token must be included in the header of all requests to the server.

Once a session token is created, it is valid for one day. This token should be used for every subsequent request until the token expires.

Reusing session tokens across requests allows for optimal performance while using Picwell's API.

Get Authorized

Request Body

{
  "username":"your-username",
  "password":"your-password"
}

Response Body

{
  "auth_token":"your-picwell-auth-token"
}

This endpoint will retrieve an authentication token to be used in subsequent requests.

Endpoint

POST http://{{medicare-api-host}}/auth/

Stay Authorized

Since we need to authorize every request you make, we expect the authentication token to be included in the headers of every subsequent request. The header should look like this:

Picwell-Auth-Token: your-picwell-auth-token

Surveys

Get Survey Questions

# The survey questions are returned as a list with a consistent structure.
# They may change at any time, so staging this data is unwise and incorrect.
[
...
{
  "question": "How many times were you admitted to a hospital in the last 12 months?",
  "type": "utilization",
  "id": "5",
  "answers": [
    {
      "answer": "not_applicable",
      "display": false,
      "label": "This input variable is not available"
    },
    {
      "answer": "0",
      "label": "I was not admitted to a hospital last year"
    },
    {
      "answer": "1",
      "label": "1 time"
    },
    {
      "answer": "gte_2",
      "label": "2 or more times"
    }
  ]
}
...
]

Endpoint

GET /survey/

Response

a List of Survey Question objects

Notes

The presentation of survey questions where id == 1 || id == 2 is optional depending on whether the user indicates any preferred healthcare providers (if the client UI requires the input of preferred healthcare providers before survey questions are presented). The optionality is in regards to whether these questions are presented to a given user via client UI, not whether the user can opt to answer them. An appropriate response should still be provided in the Survey Answer object for each question (e.g. "not_applicable" for question 1 and "0" for question 2 should the user have no preferred heathcare providers).

The presentation of survey questions where id == 3 || id == 4 || id == 5 is optional depending on whether the client UI is allowed/approved to present users questions about their historical utilization of medical services. The optionality is in regards to whether these questions are presented to users via client UI, not whether users can opt to answer them. An appropriate response should still be provided in the Survey Answer object for each question (e.g. "not_applicable" for questions 3, 4, and 5 should the client UI not be allowed/approved to ask users about medical services utilization).

Users

A User object provides valuable context required for recommendations.

Creating

This endpoint will create a user object based on information provided in the request body.

Request Body

{
  "zip_code_3":     "193",
  "state_code":     "PA",
  "age":            66, 
  "gender":         "female",
  "prescriptions":  [],
  "uses_tobacco":   true,
  "survey":         [],
  "enrolled_in":    []
}

Response Body

{
  "id":"user reference id"
  "unknown_ndcs" : {
    "2015" : ["ndc", ...],
    "2016" : ["ndc2", ...]
  },
  "remapped_ndcs": {
    "2015' : ["ndc", ...],
    "2016' : ["ndc2", ...]
  }
}

Optionally, this may include three 'errors' sub-keys: unknown_ndcs, remapped_ndcs, nonpuf_ndcs.

If the NDC is not present in Picwell's drug database, it will be be staged in the user object on creation/edit. All subsequent requests, though, will remove that NDC from the object to provide valid responses for known NDCs.

Remapped NDCs are a result of an inconsistency between the RxCUIs within CMS public use files and the NDCs that are current as provided by the NLM RxNorm database. Whenever issues like these occur, the Picwell API will attempt to remap the underlying data appropriately. This error key is provided to be able to identify the occurrence of the underlying remapping.

When an NDC is mapped to an RXCUI, but that RXCUI is not present in the CMS public use files, the nonpuf_ndcs error key will be provided. It will contain all NDCs meeting that criteria. We denote these NDCs because we are unable to map those NDCs to the underlying coverage or cost data. Those NDCs will be reported as uncovered drugs in our recommendation responses for the user.

Endpoint

POST http://{{medicare-api-host}}/user/

Getting

This endpoint will retrieve details about a user object.

Endpoint

GET http://{{medicare-api-host}}/user/{User.id}/

Response

a user object

Notes

Updating

This endpoint will update a user object based on information provided in the request body.

Request Body

{
  "zip_code_3":     "193",
  "state_code":     "PA",
  "age":            76, 
  "gender":         "female",
  "prescriptions":  [],
  "uses_tobacco":   false,
  "survey":         [],
  "enrolled_in":    []
}

Response Body

{
  "id":"user-id",
  "unknown_ndcs" : {
    "2015" : ["ndc", ...],
    "2016" : ["ndc2", ...]
  },
  "remapped_ndcs": {
    "2015' : ["ndc", ...],
    "2016' : ["ndc2", ...]
  }
}

Optionally, this may include three 'errors' sub-keys: unknown_ndcs, remapped_ndcs, nonpuf_ndcs.

If the NDC is not present in Picwell's drug database, it will be be staged in the user object on creation/edit. All subsequent requests, though, will remove that NDC from the object to provide valid responses for known NDCs.

Remapped NDCs are a result of an inconsistency between the RxCUIs within CMS public use files and the NDCs that are current as provided by the NLM RxNorm database. Whenever issues like these occur, the Picwell API will attempt to remap the underlying data appropriately. This error key is provided to be able to identify the occurrence of the underlying remapping.

When an NDC is mapped to an RXCUI, but that RXCUI is not present in the CMS public use files, the nonpuf_ndcs error key will be provided. It will contain all NDCs meeting that criteria. We denote these NDCs because we are unable to map those NDCs to the underlying coverage or cost data. Those NDCs will be reported as uncovered drugs in our recommendation responses for the user.

Endpoint

PUT http://{{medicare-api-host}}/user/{{user-id}}/

Drug Search

Drugs are classified using NDCs and represent information about a specific packaging of a drug.

Resolving Names

You may use this endpoint to retrieve all drugs matching a (partial) name

Response Body

[
  {"generic_name": "Clonazepam", 
   "default_quantity": 30, 
   "ndc": "00093083201", 
   "default_period": 30, 
   "brand_name": "Clonazepam", 
   "description": "Clonazepam, 100 TABLET in 1 BOTTLE "},
  # { drug object 2},
  ...
]

Endpoint

GET http://{{medicare-api-host}}/drugs/

Query Parameters

key value
query a partial drug name

Response Fields

keys type description
ndc string the Medicare 11-digit ndc
brand_name string the (potentially) branded name of the drug (optional)
generic_name string the generic drug name
description string the display name of drug inclusive of dosage and format
default_quantity int most commonly prescribed quantity of this medication
default_period int most commonly prescribed refill period of this medication

Recommendations

For All Medicare Packages

Endpoint

POST /recommendation/<int: year>/{User.id}/{params}

Post Body

list of Plan Reference

Response

a Result Set object (with N recommendations)

Notes

For A Single Medicare Product

Endpoint

POST /recommendation/<string: product>/<int: year>/{User.id}/{params}

Post Body

list of Plan Reference

Response

a Result Set object (with N recommendations)

Notes

For Multiple Medicare Products

Endpoint

POST /recommendation/<string: comma-separated product codes>/<int: year>/{User.id}/{params}

Post Body

list of Plan Reference

Response

a Result Set object (with N recommendations)

Notes

For A Single Medicare Package

Endpoint

POST /recommendation/<string: package code>/<int: year>/{User.id}/{params}

Post Body

list of Plan Reference

Response

a Result Set object (with N recommendations)

Notes

For Several Medicare Packages

Endpoint

POST /recommendation/<string: comma-separated package codes>/<int: year>/{User.id}/{params}

Post Body

a list of Plan Reference

Response

a Result Set object (with N recommendations)

Notes

Request

POST /recommendation/tm+gap+pdp,ma+pdp/2015/user123/

Response Body

# Response will only contain tm+gap+pdp, ma+pdp combinations
# (not mapd, or tm+pdp, due to constraint in request)
{ gap1, gap2, mapd1, mapd2, pdp1, ma1, ma2 }

# If no ma plans are provided, ma+pdp combinations will be missing from the response, which will only contain tm+gap+pdp combinations.
{ gap1, gap2, pdp1 }

Proration

# To request prorated cost estimates for Medicare Packages
# of types `mapd,ma+pdp,gap+pdp`, for user `abcde`, for
# the period of Oct 2015 to Dec 2015:
POST /recommendation/mapd,ma+pdp,tm+gap+pdp/2015/abcde/?start_date=2015-10-01

Recommendation responses can include prorated cost estimates (for individuals signing up for coverage less than 1 year). This may be of value to individuals becoming Medicare eligible outside of the October-December annual enrollment period (e.g. someone turning 65 years of age in March). In such a situation, the enrollee might be interested in viewing prorated cost estimates.

Syntax for prorated requests is consistent across recommendation requests:

POST /recommendation/.../.../?start_date={date}

Pagination

ResultSets provided by the Picwell API may include several hundred package combinations. To simplify, access and use, results are provided in a form that allows pagination.

Use the pagination methods to navigate the pages of a Result Set. {Result Set.pages} indicates the number of pages generated by a recommendation request.

Endpoint

GET /recommendation/results/{Result Set.id}/page/<page number: int>/

Response

a Result Set object with the next page for recommendations

The number of results presented per page can be controlled by the num parameter. If excluded (as illustrated above), the default value of num is set to 100. If num is set to all, all the results are returned in a single page.

Endpoint

GET /recommendation/results/{Result Set.id}/page/<page number: int>/?num={n}

Response

a Result Set object with the next page for recommendations, with the number of results per page set to n

Filtering

Use the filtering methods to apply filter predicates (expressions) to Result Sets generated by a recommendation request.

Endpoints:

POST /recommendation/results/{Result Set.id}/filter/

GET /recommendation/results/{Result Set.id}/filter/page/<page number: int>/

Post Body

a Filter Expression object

Response Body

a Result Set object with paginated filtered recommendations. To be included in the response, a Recommendation must meet every rule in the provided Filter Expression.

Sorting

Generally, ResultSets provided by the Picwell API are sorted using the picwell_score that is calculated using the retail pharmacy costs. In cases where the user is more interested in the picwell_score calculated using the mail pharmacy costs, we have provided a way to change the sort order of a recommendation request.

While the original recommendation request will continue to be served and sorted by the retail pharmacy score, you can now make subsequent requests to the filtering and pagination endpoints with a sort_by parameter.

The sort_by query parameter can be : mail, retail.

note: when a score doesn't exist for a package, it will be sorted by a consistent hash of the picwell_id to maintain stability.

Endpoint

GET /recommendation/results/{Result Set.id}/page/<page number: int>/?sort_by=<mail|retail>
POST /recommendation/results/{Result Set.id}/filter/?sort_by=<mail|retail>
GET /recommendation/results/{Result Set.id}/filter/page/<page number: int>/?sort_by=<mail|retail>

Response

a Result Set object with the next page for recommendations sorted with the appropriate sort_by ordering.

Prescription Drug Plan Costs

Endpoint

POST /recommendation/breakdown/{User.id}/

Post Body

a single Plan Reference

Response

list of Drug Cost Breakdown objects

Notes

Analytics Parameters

Recommendation requests can be supplemented with analytics-related information that can aid with downstream analytics provided by Picwell. Data must be specified as valid key-value pairs, formatted as a valid query string. At this time, Picwell supports the following parameters:

Personal information prohibited

Picwell does not permit the transmission of user personal information (including Personal Health Information) via Analytics Parameters. As such, any information supplied to Picwell must comply with HIPAA Safe Harbor standards of de-identification of PHI.

Example usage:

Medicare Packages recommendation request from call-center:
POST /recommendation/2017/c2392ff4-f7c0-4137-baf0-fa0448c1be1f/?source=callcenter

Medicare Packages recommendation request from self-service website:
POST /recommendation/2017/c2392ff4-f7c0-4137-baf0-fa0448c1be1f/?source=selfservice

Part D recommendation request from call-center:
POST /recommendation/pdp/2017/c2392ff4-f7c0-4137-baf0-fa0448c1be1f/?source=callcenter

Object Reference

All objects are serialized as JSON.

Costs

keys type description
real_cost{mean} float The mean of costs incurred by people like the user for this package of plans (optional key)
real_cost{deciles} [float] The costs incurred by people like the user, sampled at each decile of RealCost(tm), for this package of plans (optional key)
monthly_premium float dollar value for monthly premium
part_b{monthly_premium} float dollar value for monthly Part B premium (optional key)
part_b{monthly_premium_reduction} float dollar value for monthly Part B premium reduction (optional key)
services{in_network{mean}} float The mean dollar value for services in network (optional key)
services{in_network{deciles}} [float] The dollar value for services in network, sampled at each decile, for this package of plans (optional key)
services{out_network{mean}} float The mean dollar value for services out of network (optional key)
drugs{mail{total}} float cost of drugs covered by plan when using mail when provided by client (optional key)
drugs{mail{covered}} float cost of drugs covered by plan, at mail order pharmacies (optional key)
drugs{mail{uncovered}} float cost of drugs not covered by plan, at mail order pharmacies (optional key)
drugs{retail{total}} float cost of drugs covered by plan at retail pharmacies when provided by client (optional key)
drugs{retail{covered}} float cost of drugs covered by plan, at retail pharmacies (optional key)
drugs{retail{uncovered}} float cost of drugs not covered by plan, at retail pharmacies (optional key)

Drug

A representation of a specific packaging of a drug

keys type description
ndc string the Medicare 11-digit ndc
brand_name string the (potentially) branded name of the drug (optional key)
generic_name string the generic drug name
description string the display name of drug inclusive of dosage and format
default_quantity int most commonly prescribed quantity of this medication
default_period int most commonly prescribed refill period of this medication

Drug Cost Breakdown

keys type description
ndc string the Medicare 11-digit ndc
period int period of drug refill (as specified in User object)
quantity int numeric quantity of the drug`
covered boolean drug covered by plan
tier int tier of drug on plan formulary (optional key)
step_therapy boolean formulary requires step therapy for drug (optional key)
prior_authorization boolean formulary requires prior authorization for drug (optional key)
quantity_limit boolean formulary enforces quantity limit for drug
retail_price float retail unit price of the drug for specified refill period and quantity
user_multiplier float ratio of the user's rate of consumption to the default rate of consumption
costs{retail} float cost of drug at retail pharmacy
costs{mail} float cost of drug at mail order pharmacy
fill_costs{retail}{initial_coverage} float cost of retail pharmacy fill for drug in initial coverage phase
fill_costs{mail}{initial_coverage} float cost of mail order pharmacy fill for drug in initial coverage phase

Drug Coverage

keys type description
covered [string] a list of 11-digit NDCs covered by the plan
uncovered [string] a list of 11-digit NDCs not covered by the plan
partial [string] a list of 11-digit NDCs partially covered by the plan
donut_hole boolean indicator of whether drug expenses move user into coverage gap
catastrophic boolean indicator of whether drug expenses move user into catastrophic phase

External Drug Costs

Rather than using drug cost estimates determined by Picwell's Part D calculator, the client can provide their own estimates for inclusion in Picwell's plan/package scoring. This is an optional part of a [Plan Reference] object.

keys type description
retail float The drug costs associated for the drugs the user is seeking coverage for, when they are receiving all their drugs from a retail pharmacy
mail float The drug costs associated for the drugs the user is seeking coverage for, when they are receiving all their drugs from a mail order pharmacy

Health Provider Location

A representation of a user's healthcare provider (doctor, nurse practioner, clinic etc) at a specific location. Health Provider Locations combine the concept of healthcare providers and the locations a provider practices at. This is necessary because a given health provider practicing at one location may be covered by a plan, but the same health provider practicing at another may not be covered by the same plan.

Health Provider Locations also encompass the concept of health facilities that a user might express a preference towards (clinics, general hospitals etc).

keys type description
external_id string unique identifier for health provider location
type string one of {specialist, pcp, facility}
specialty [string] the provider's or facility's specialty

Filter Expression

keys type description
plans [string] a list of external or Picwell identifiers for plans
health_provider_locations [string] a list of health provider location identifiers
package_types [string] a list of package types, can be any of mapd, tm+gap+pdp, ma+pdp, tm+pdp

Plan

A representation of a specific insurance plan

keys type description
id bigint an internally used identifier for a plan
external_id string unique, mutually bound, identifier for the plan
type enum one of "pdp", "ma", "mapd", "gap"
carrier string a human readable plan carrier name
name string a human readable plan name
detail string additional plan information for medigap plans
letter string medigap plan letter in Picwell schema (optional key)
medicare_id string in the form H0000-000-000

Plan Reference

A reference to plans that a client would like to consider for a request

keys type description
type string enum of 'ma', 'pdp', 'mapd', 'gap'
picwell_id string unique internal identifier for plan and offering year (optional key)
external_id string unique, mutually bound, identifier for plan and offering year (optional key)
monthly_premium float the monthly premium for the plan (optional key)
drug_costs [External Drug Costs] Rather than using our Part D calculator, the client can provide their own calculated value, which we will then use to compute a plan or packages score (optional key)
health_provider_locations{in_network} [Health Provider Location] list of provider-locations in-network
health_provider_locations{extended_network} [Health Provider Location] list of provider-locations in-network
health_provider_locations{out_of_network} [Health Provider Location] list of provider-locations out-of-network

Generally, during API usage, the picwell_id field is for bpoa requests against the Medicare plan universe.

Prescription

A prescription of a given drug

key type description
ndc string 11 digit ndc
quantity int numeric quantity of the drug
period int days between refills

Recommendation

A recommendation for a package of plans

key type description
components enum one of "pdp", "ma", "mapd", "gap", "ma+pdp", "tm+pdp", "tm+gap+pdp"
type enum one of "package", "standalone"; distinguish result type
plans [Plan] list of plans constituting this package
score [Score] Picwell Score values for this package
costs{full} Costs costs of premiums, services, and drugs for the full year
costs{partial} Costs costs of premiums, services, and drugs for the partial year, if making a partial year request (optional key)
drug_coverage Drug Coverage breakdown of covered and uncovered drugs, won't be provided in the presence of client-provided drug costs (optional key)
health_provider_locations [Health Provider Location] the providers in network for the plan

Result Set

key type description
id string identifier for this result set (optional key)
results [Recommendation] list of package recommendations
current_page int current page number of result set
total_results int number of recommendations associated with entire result set
total_pages int number of pages associated with entire result set
errors{unmatched} [string] list of external plan IDs that were not matched (optional key)
errors{parameter} string indication of query string argument error (optional key)

Score

The relative Picwell Score for this package amongst all packages in the ResultSet

key type description
retail{picwell_score} float (0-100) The relative Picwell Score value when comparing this package against other packages when receiving all drugs from a retail pharmacy (optional key)
retail{tier} enum Picwell color tier, one of "red", "green", "yellow" (optional key)
retail{dimensions{real_cost}}} float (0-100) The relative Real Cost value when comparing this package against other packages when receiving all drugs from a retail pharmacy (optional key)
retail{dimensions{risk_protection}} float (0-100) The relative risk protection this package provides when comparing this package against other packages when receiving all drugs from a retail pharmacy (optional key)
retail{dimensions{health_provider_locations}} float (0-100) Compared to other plans in the result set, how well this plan covers your preferred health providers (optional key)
retail{dimensions{medicare_star_ratings}} float (0-100) The relative Medicare star rating value when comparing this package against other packages when receiving all drugs from a retail pharmacy (optional key)
mail{picwell_score} float (0-100) The relative Picwell Score value when comparing this package against other packages when receiving all drugs from a mail order pharmacy (optional key)
mail{tier} enum Picwell color tier, one of "red", "green", "yellow" (optional key)
mail{dimensions{real_cost}} float (0-100) The relative Real Cost value when comparing this package against other packages when receiving all drugs from a mail order pharmacy (optional key)
mail{dimensions{risk_protection}} float (0-100) The relative risk protection this package provides when comparing this package against other packages when receiving all drugs from a mail order pharmacy (optional key)
mail{dimensions{health_provider_locations}} float (0-100) Compared to other plans in the result set, how well this plan covers your preferred health providers (optional key)
mail{dimensions{medicare_star_ratings}} float (0-100) The relative Medicare star rating value when comparing this package against other packages when receiving all drugs from a mail order pharmacy (optional key)
score dimension mapd ma gap pdp
real_cost yes yes yes yes
risk_protection yes yes yes no
health_provider_locations yes yes yes no
medicare_star_ratings yes yes no yes

Survey Question

A health services or personality survey question

key type description
id string unique identifier for the survey question
type string one of {risk, physician, utilization}
question string UI-friendly prompt for the survey question
answers list a list of Presented Survey Answer objects

Note: the list of answers is ordered as they should appear when visually represented.

Presented Survey Answer

An answer and the presentation for the given answer.

key type description
answer string the answer key as is used in User edit/create structure
label string the presentable label for the answer
display bool optional. If false, then do not show this answer/label to the user.

*These answers are used either internally or for alternative user flows.

Survey Response Answer

A health services or personality survey response

key type description
question_id string unique identifier for the survey question
answer enum selection from {Survey Question.answers}

User

A representation of a user

keys type description
zip_code_3 string the user's 3-digit ZIP code
state_code string the user's two-character U.S. state code
age int the user's age, in years
gender enum either "male" or "female"
prescriptions [Prescription] list of the user's prescriptions
uses_tobacco boolean does the user use tobacco products?
survey [Survey Answer] responses to survey questions
enrolled_in [string] list of identifiers for the plan(s) the user is enrolled in (optional key)

Semantics for enrolled_in field:

Client Provided Drug Costs

Here is a quick summary of what a client should know if they would like to provide their own calculated values for drug costs rather than use our Part D calculator. The following information is also scattered throughout the API documentation for contextual reference.

How to Invoke Functionality
Functionality is invoked if the drug_costs key in the Plan Reference object is provided for either pdp or mapd plans. drug_costs is of the type [External Drug Costs]. Read the section about the External Drug Costs object carefully to see how to appropriately format this object for the request you would like to make.

Changes in the Cost Object
The uncovered/covered keys will not exist. If the retail costs for a plan is not specified, then the realcost{mean} and realcost{deciles} will not be provided because these are based on retail costs.

Changes in the Recommendation Object
The drug_coverage key will not be provided.

Changes in the Score Object
A plan/package will have no retail scores if the retail drug_costs are not provided for that plan/package. The same is true for mail scores. If neither of these costs is provided for a plan/package, then the Score object will be an empty dictionary.

Errors

While the Picwell API uses standard HTTP status codes, many times body data is also provided to help consumers correct any issues after the fact. Following is a table of error codes used, their context, and some expectation of how to handle them.

Status Meaning Handling
400 Bad request Any request that is missing a required field. Review the response body for further handling.
401 Unauthorized Authentication token has expired. Create a new authentication token and retry the operation.
404 Object not found A request for an object which does not exist. Consider recreating the missing object (user profile, result set, etc), if necessary.
405 Method Not Allowed A request was made with an invalid HTTP action. Check the verb of your request and try again.
500 Server Error Picwell encountered an internal error. While you may retry the request as the error may have been temporary, persisting failures may indicate service downtime.
503 Temporary Server Error Picwell encountered an internal error. Retry the request as the error may have been temporary.

Error Objects within Responses

Throughout this API we have used a few error json objects that are within the overarching result of user creation/edit, recommendation, and breakdown requests. In the sidebar is a consolidation of these errror bodies. The explanation for them can be found in the related request sections.


{
  "errors": {
    // plans that don't match via a client data file
    "unmatched" : ["client-plan-id1", "client-plan-id2", ...],
    // plans we were not able to model
    "unmodelled" : ["id1", "id2", ...],
    // ndcs that were unknown within the years that are valid
    "unknown_ndcs" : {
      "2015" : ["ndc1", "ndc2", ...],
      "2016" : ["ndc2", "ndc3", ...]
    },
    // ndcs for drugs that had their underlying RxCUIs remapped
    "remapped_ndcs" : {
      "2015" : ["ndc5", "ndc6", ...],
      "2016" : ["ndc7", "ndc8", ...]
    },
    // ndcs for drugs that have no available cost/coverage info from CMS
    "nonpuf_ndcs": {
      "2015" : ["ndc9", "ndc10", ...],
      "2016" : ["ndc11", ...],
    }
  }
}

Versioning

As the medicare-api evolves, API versioning is required in order to accommodate the need for stable APIs while new features are being developed. Clients are able to make requests to a specific version of the API using HTTP Accept headers.

Picwell's method of Accept header versioning is a widely accepted standard for versioning RESTful APIs. Under v2 APIs, themedicare-api does not care about what is sent in the HTTP Accept header of a request. If you choose to send an Accept header, 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 explicitly selects v2
application/vnd.picwell.v3+json v3 this explicitly selects v3
application/vnd.picwell.v9+json v2 this selects v9, which doesn't exist, so v2 is selected

It is NOT safe to mix versions of the API within a session (e.g. creating a user under v2 and subsequently requesting a recommendation under v3). Usage of Accept headers should be consistent across all requests within a session, including authentication (e.g. if a v3 recommendation request will be made, the v3 Accept header should be provided during authentication).

Frequently Asked Questions

How does Picwell handle drug costs and coverage for plans that don't have drug components?

When responding to a Medigap or Medicare Advantage request, the drugs and drug_coverage fields will both be {}, to represent the fact that drug coverage is absent from these plan types.

Example: .. "drugs": {} }, "drug_coverage": {} }

How is the Picwell RealCost(tm) calculated?

The Picwell RealCost(tm) represents our best estimate of the user's expected annual (or prorated) out-of-pocket cost under that plan package.

The costs.real_cost.mean is computed as follows: costs.real_cost.mean = MONTHS_COVERED * (costs.monthly_premium + costs.part_b.monthly_premium - costs.part_b.monthly_premium_reduction) + costs.services.in_network + costs.drugs.pharmacy + costs.drugs.uncovered

Our recommendation responses include the constituent elements of RealCost to help clients better explain a plan's cost drivers.

How does Picwell recommend rendering the Picwell Score in Package and Plan settings?

If your implementation uses our Plan Package functionality, the Picwell Scores should only be rendered at a Package level. While it is returned for standalone Plan recommendations, it is done so only for the ability to sort plans in an appropriate order. Picwell Scores cannot be compared "apples-to-apples" between Package and Plan settings, and rendering it as such is a violation of our Branding Guidelines. We do permit the use of our color tiers as a selection aid to end users.

Are there other situations where Picwell Scores may not be directly comparable?

Picwell Scores are not comparable if they originate from recommendation requests with different Plan or Package combinations. This is because Picwell Scores are relative values, sensitive to the package or options being considered.

As an example, Picwell Scores returned for a request seeking PDP & Gap or MA & PDP packages: /recommendation/tm+gap+pdp,ma+pdp/2015/user123/ are not comparable to Picwell Scores returned for a request seeking all packages: /recommendation/2015/user123/

How does Picwell handle recommendations for two plan years?

If a user is simultaneoulsy electing partial year's worth of coverage in the current year along with a full year's coverage for the next year, two API calls to our recommendation endpoints are required. The first is a request for prorated recommendations with a list of Plan References for the current years' eligible plans. The second is a request for full year recommendations with a list of Plan References for the next years' eligible plans.

What happens when a recommendation request contains no plans?

Sending an empty list (i.e. []) of Plan References in a recommendation request is an erroneous condition. Picwell will accept the request, but will return a Result Set with no values.

Omitting any payload in the recommendation request (i.e. sending no POST body), will trigger Picwell's own eligibility logic into action - using the provided geographical and other variables, Picwell makes its own determination of plan eligibility for a user. These determinations include ALL available Medicare plans, and are generally not of interest to our clients. Therefore, omitting a payload in the recommendation request is to be generally avoided.

Migrating from v2 to v3

For a detailed guide to the changes between version 2 and 3 of the Medicare API, please reference https://gist.github.com/picwell-allie/c9f161a4a7c00eda61c5.

Support

Suggested Tooling

It is strongly suggested that a client's developers adopt a simple HTTP transaction tool to facilitate debugging against Picwell's APIs. These tools help isolate client platform-specific issues from possible Picwell API issues. In our experience, any of these tools provide excellent HTTP transaction logging and instrumentation, ideal of debugging:

Reporting Issues

If an API request fails in your development environment or platform, please attempt a clean HTTP request (using the tools listed above) to create a clean HTTP trasanction trace. An HTTP transaction trace includes the data points listed below. When reporting Picwell API errors, it is important to provide us with these critical elements of data in order for us to troubleshoot quickly and effectively: