NAV
shell ruby python javascript

Picwell Commercial API

This document provides general guidance to developers using our APIs on matters of technical support and infrastructure, and complements the Picwell API specification provided.

Infrastructure

Environments

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

User Acceptance Testing

Our User Acceptance Testing (UAT) 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.

Our UAT environment is accessible at https://uat-api.picwell.net/

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.

Our Production environment is accessible at https://api.picwell.net/

Change management

User management

Demo/Sandbox Clients in UAT

Clients in UAT/PROD

Request for Access

If you are interested in access to our UAT environment, please contact your Picwell rep for more information.

Security

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

Keep your keys safe

Your secret API key can be used to make any API call on behalf of your account, Use the following best practices to keep your keys safe:

Sanitized User Input

If requested, Picwell will sanitize all user input returned by the API, making it safe to insert into an HTML page without modification. This is not a security feature (API client software is responsible for safely handling data), but is offered as a convenience for our customers.

Authentication

Picwell's API offers two methods of authenticating a request. Each are described below.

API Keys

To begin using Picwell API, contact your Picwell representative for an API key. You will receive one key per environment; most likely uat and prod. These URLs can be found below.

Environment URL
uat https://uat-api.picwell.net/
prod https://api.picwell.net/

For all requests, you will specify the following headers:

Header Value
Accept application/vnd.picwell.v1+json
X-Api-Key Your provided API Key.

Legacy API Credentials

To begin using Picwell API, contact your Picwell representative for your API credentials. You will receive one set of credentials per environment; most likely uat and prod. These URLs can be found below.

Environment URL
uat https://uat-commercial-api.picwell.net/
prod https://commercial-api.picwell.net/

Request Body

{
  "username": "<username>",
  "password": "<password>"
}

Response Body

{
  "auth_token": "<temporary-auth-token>"
}

Endpoint

POST /auth

Response

An authentication token

For all other requests, you will specify the following headers:

Picwell-Auth-Token: <temporary-auth-token>

You should expect your auth token to last no longer than 24 hours. At any point, you may request a new one.

Reusing your auth token across requests allows for optimal performance.

When using this authentication method, omit the /comm/ route prefix across all endpoints. For example, GET /comm/plans/health/ becomes GET /plans/health/.

API Versioning

The Picwell API uses custom media types to let consumers specify the version of the API they wish to consume. Picwell media types are of the form:

application/vnd.picwell[.version][+json]

Specifying a version

Specifying a version for your request is required and is done using the Accept header.

Header Value
API Key Auth Accept Header application/vnd.picwell.v1+json
Legacy Auth Accept Header application/vnd.picwell.v6+json 
$ curl https://uat-api.picwell.net/healthcheck/ -I \
  -H "Accept: application/vnd.picwell.v6+json"
HTTP/1.1 200 OK

Backwards-compatible Changes

Picwell considers the following changes to be backwards-compatible:

Changelog

Version 6 (latest)

June 2025

December 2024

March 2024

February 2024

June 2023

April 2023

March 2023

February 2023

December 2022

September 2022

August 2022

June 2022

March 2022

February 2022

August 2021

May 2021

April 2021

February 2021

August 2020

October 2019

September 2019

August 2019

July 2019

November 2018

Version 5 and below

API v1-v5 documentation

December 2024

Content Types

All POST and PUT requests made to the Picwell API must specify a Content-Type header of application/json. If not specified, you will receive an HTTP 415 response stating as such.

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

Compression

Picwell employs GZIP compression on HTTP responses to reduce the byte-size of data transferred between our servers and yours. This compression is activated when the response payload is optimal size to benefit from compression.

If supplied with the standard Accept-Encoding HTTP header, we respond with GZIP compressed payloads as well as the Content-Encoding HTTP header. Most web development frameworks can incorporate HTTP compression easily (e.g. .NET)

Rate Limits

The Picwell API employs a number of safeguards to help maximize its stability. Users who send many requests in quick succession may see error responses. Requests rejected due to surpassing the rate limit receive an HTTP 429 response.

Common Causes

Handling Limiting Gracefully

If you are receiving 429 status codes, you are exceeding the configured limit for a given API resource. One strategy to handle this gracefully is to implement a retry mechanism with exponential backoff so that occasional limited requests can still eventually succeed.

This approach may not be applicable for all scenarios, and for some endpoints it is possible to experience higher latency without being limited. In these cases, you may:

  1. Ignore stale data to improve user experience ("debouncing"). We recommend this for typeahead search interfaces.
  2. Decrease the rate at which you make requests ("throttling"). We recommend this for batch operations.

For Picwell's own front-end applications, we rely on Lodash debounce for handling streams of user input to limit the number of unnecessary requests made to the API.

For more help with Throttle and Debounce, checkout this guide.

Quick Start

Quick Start Guide for Using the Picwell API

Basic steps:

  1. Authenticate
  2. Create a household
  3. Get available plans
  4. Get a health recommendation

Authenticate

API Key Auth

All API calls using API key authentication must have the following two headers set:

Header Value
Accept application/vnd.picwell.v1+json
X-Api-Key Your provided API Key.

See Authentication for more information.

Legacy API Credentials Auth

Before you can make any API calls, you must obtain a session token. This should be sent in the Picwell-Auth-Token header for all subsequent requests.

The Accept header must also be sent to indicate the version of the API.

As of January 2019, the latest version of our API is V6, which can be specified with the Accept header vnd.picwell.v6+json.

See Authentication for more information.

Example auth request

URL=https://uat-commercial-api.picwell.net
USER=your_username_here
PASS=your_password_here

curl -X POST \
  ${URL}/auth/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.picwell.v6+json' \
  -d "{ \"username\": \"${USER}\", \"password\": \"${PASS}\" }"

Example response

{"auth_token": "222a0004-0123-4449-abcd-88cc4b33a7cb"}

Create a household

A household is necessary for obtaining any recommendation.

This entails sending a POST request to /comm/household/.

See Households for more information.

Example POST to /comm/household/

HOUSEHOLD=$( cat <<DONE
    {
    "version": 2021,
    "spending_accounts": [
        { "employee_contribution": 100, "employer_contribution": 50, "type": "hsa" }
    ],
    "enrollment": {
        "network_id": "some_optional_network_id", "plan_id": "plan_01"
    },
    "survey": [
        { "question_id": "1", "answer": "very_important" },
        { "question_id": "2", "answer": "2_3" },
        { "question_id": "4", "answer": "75_100" },
        { "question_id": "5", "answer": "plan_b" },
        { "question_id": "6", "answer": "plan_a" }
    ],
    "members": [
        {
        "external_id": "1234567890ABC",
        "policyholder": true,
        "gender": "female",
        "uses_tobacco": false,
        "planning_for_child": false,
        "age": 45,
        "dependant": false,
        "prescriptions": [
            { "ndc": "12345678901", "frequency": 30, "quantity": 60 }
        ]
        }
    ],
    "zip_code_3": "123"
    }
DONE
)

curl -v -L -X POST \
    ${URL}/comm/household/ \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.picwell.v6+json' \
    -H "Picwell-Auth-Token: ${TOKEN}" \
    -d "${HOUSEHOLD}"

Example response

{
  "id": "3c770943-1234-4e74-a07d-9999999999ae",
  "version": 2021
}

Get available plans

curl -X GET \
  http://${URL}/comm/plans/health/ \
  -H 'Accept: application/vnd.picwell.v6+json' \
  -H "Picwell-Auth-Token: ${TOKEN}"

Example response

{
  "plans": [
    {
      "external_id": "Aetna2000"
    },
    {
      "external_id": "Aetna3500"
    },
    {
      "external_id": "Aetna2700"
    }
  ]
}

This endpoint describes the full set of plans you may request recommendations for. By default, this endpoint will only return you a list of external_ids. View the documentation for Get Health Plans for more information.

With a given set of external_ids, you can now make a recommendation request for a given household.

Get a health recommendation

With a given household_id, you can now get recommendations for any health plan by sending a POST request to /comm/recommendation/${HOUSEHOLD_ID}.

As the request body, supply a Health Recommendation Request to use a specific set of plans.

If the Eligibility Determination and Premium Determination features were set up for your organization during the onboarding process, you can automatically use all plans for which the household is eligible by sending an empty object ({}) in the request body. See Premiums and Eligibility for more information.

Example POST to /comm/recommendation/<household_id> using a plan set

PLAN_DATA=$( cat <<DONE
{
  "plans":[
    {
      "external_id":"plan_01",
      "premiums":{
        "employee_contribution":100,
        "employer_contribution":150
      },
      "health_provider_locations":{
        "in_network":[
          {
            "external_id":"doctor_location_01",
            "type":"pcp",
            "specialty":[
              "Primary Care"
            ]
          },
          {
            "external_id":"doctor_location_02",
            "type":"pcp",
            "specialty":[
              "Pediatrics"
            ]
          }
        ],
        "out_of_network":[
          {
            "external_id":"doctor_location_03",
            "type":"pcp",
            "specialty":[
              "Family Medicine"
            ]
          }
        ]
      }
    },
    {
      "external_id":"plan_02",
      "premiums":{
        "employee_contribution":120,
        "employer_contribution":110
      },
      "health_provider_locations":{
        "in_network":[
          {
            "external_id":"doctor_location_01",
            "type":"pcp",
            "specialty":[
              "Primary Care"
            ]
          }
        ],
        "out_of_network":[
          {
            "external_id":"doctor_location_03",
            "type":"pcp",
            "specialty":[
              "Family Medicine"
            ]
          }
        ]
      }
    },
    {
      "external_id":"plan_03",
      "premiums":{
        "employee_contribution":120,
        "employer_contribution":110
      },
      "health_provider_locations":{
        "in_network":[
          {
            "external_id":"doctor_location_01",
            "type":"pcp",
            "specialty":[
              "Primary Care"
            ]
          },
          {
            "external_id":"doctor_location_02",
            "type":"pcp",
            "specialty":[
              "Pediatrics"
            ]
          }
        ],
        "out_of_network":[]
      }
    }
  ]
}
DONE
)

curl -s -L -X POST \
    ${URL}/comm/recommendation/${HOUSEHOLD_ID}/ \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.picwell.v6+json' \
    -H "Picwell-Auth-Token: ${TOKEN}" \
    -d "${PLAN_DATA}"

Example POST to /comm/recommendation/<household_id> using all eligible plans

curl -s -L -X POST \
    ${URL}/comm/recommendation/${HOUSEHOLD_ID}/ \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.picwell.v6+json' \
    -H "Picwell-Auth-Token: ${TOKEN}" \
    -d "{}"

Example response

{
  "recommendations": [
    {
      "tier": "green",
      "health_provider_locations": [
        {
          "type": "pcp",
          "location": null,
          "external_id": "doctor_location_01",
          "specialty": [ "Primary Care" ],
          "name": null
        },
        {
          "type": "pcp",
          "location": null,
          "external_id": "doctor_location_02",
          "specialty": [ "Pediatrics" ],
          "name": null
        }
      ],
      "score": 96,
      "plan": {
        "external_id": "plan_01",
        "id": "170016530229784360"
      },
      "costs": {
        "drugs": 267.84,
        "real_cost": 2474.46,
        "spending_account_balance_increase": 0,
        "effective_premium": 100,
        "spending_account_benefit": 224.9,
        "services": {
          "in_network": 1231.52
        }
      }
    },
    {
      "tier": "green",
      "health_provider_locations": [
        { "type": "pcp",
          "location": null,
          "external_id": "doctor_location_01",
          "specialty": [ "Primary Care" ],
          "name": null
        }
      ],
      "score": 99,
      "plan": {
        "external_id": "plan_02",
        "id": "170012180586818921"
      },
      "costs": {
        "drugs": 257.34,
        "real_cost": 2364.11,
        "spending_account_balance_increase": 0,
        "effective_premium": 100,
        "spending_account_benefit": 205.43,
        "services": {
          "in_network": 1112.2
        }
      }
    },
    {
      "tier": "green",
      "health_provider_locations": [
        { "type": "pcp",
          "location": null,
          "external_id": "plan_03",
          "specialty": [ "Primary Care" ],
          "name": null
        },
        { "type": "pcp",
          "location": null,
          "external_id": "doctor_location_02",
          "specialty": [ "Pediatrics" ],
          "name": null
        }
      ],
      "score": 98,
      "plan": {
        "external_id": "100093_90014_2021",
        "id": "170012936974611509"
      },
      "costs": {
        "drugs": 269,
        "real_cost": 2472.26,
        "spending_account_balance_increase": 0,
        "effective_premium": 100,
        "spending_account_benefit": 224.52,
        "services": {
          "in_network": 1227.77
        }
      }
    }
  ]
}

See Recommendations for more information.

Premiums and Eligibility

Picwell supports a variety of methods for determining premiums and eligibility for a given recommendation. You may choose to provide rules to determine the plans an end user is eligible for and the premiums they will have to pay during the plan ingestion:

Premium Determination

Static Premiums

If all of your health plans have fixed premiums that do not vary by household, no premium value or additional household information needs to be supplied during a recommendation request. Our API will use the premium that was provided for that plan during the plan ingestion process.

Household Driven Premiums

If any of your health plans have premiums that vary by household, a Client Survey will be created to capture any necessary information that is not currently part of the Household. Using this survey, Picwell can make the appropriate determination based on rules defined during plan ingestion. This allows dynamic premium rules to be applied while keeping the recommendation request simple.

For example, you could support:

Recommendation Request Driven Premiums

If your company chooses not to provide premiums during plan ingestion or wishes to override the provided premiums, send the end user's premium contribution as part of the recommendation request.

Eligibility Determination

Static Eligibility

If all of your end users are eligible for the same set of plans, no eligibility set or additional household information needs to be supplied during a recommendation request. Our API will use all of the plans that were provided as the eligibility set during the plan ingestion process. In most cases the eligibible plans will be include the plans your company provided to Picwell, but we allow it to be a subset.

Household Driven Eligibility

If any of your health plans have eligibility that varies by household, a Client Survey will be created to capture any necessary information that is not currently part of the Household. Using this survey, Picwell can make the appropriate determination based on rules defined during plan ingestion. This allows dynamic eligibility to be applied while keeping the recommendation request simple.

For example, you could support:

Recommendation Request Driven Eligibility

If your company chooses not to provide eligibility information during plan ingestion, or wishes to override the eligibility determination, send the set of plans to consider during the recommendation request. This provides you the flexibility of specifying any set of plans we have ingested.

Combining the Eligibility Determination and Premium Determination features

Generally speaking, the above scenarios can be mixed and matched but certain prerequisites must be met. For example, using any form of household driven eligibility or premiums requires a Household to have a Client Survey. However, this may be overriden by request driven premiums or eligibility.

Additionally, using request driven premiums explicitly requires request driven eligibility and will therefore override other forms of eligibility determination.

See Recommendations and Client Survey for more information.

Client Survey

Client Survey Questions

Example request

GET /comm/client_survey/ HTTP/1.1
Host: api.picwell.net
Content-Type: application/json
Picwell-Auth-Token: <your-auth-token>
Accept: application/vnd.picwell.v6+json

Example responses

200 Response - Survey questions are configured

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "properties": {
    "is_full_time_or_part_time": {
      "description": "Are you full-time or part-time?",
      "enum": ["Full-Time", "Part-Time"],
      "type": "string"
    },
    "is_j1_visa": {
      "description": "Are you here on a J-1 Visa?",
      "enum": ["No", "Yes"],
      "type": "string"
    }
  },
  "type": "object"
}

200 Response - No survey questions are configured

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "properties": {},
  "type": "object"
}

GET /comm/client_survey/

Get client-specific survey questions and valid responses.

Some organizations have specific business rules that affect the recommendations that Picwell makes for the organization's end users. Such rules may include determining which plans a user is eligible for or what their premiums will be, based on the user's work status or location. These rules may be based on data that is not standard for all organizations, and is not part of the Household. This custom data can be collected through a Client Survey.

Picwell provides the ability to gather this data through Client Surveys. As part of the onboarding process, an employer can provide us with the questions and valid responses to these questions, which this API can then take as part of the Household and then use when generating Recommendations.

The Client Survey endpoint returns a JSON Schema object that describes the Client Survey, if there is one.

The most important parts of this document, from an API consumer's point of view, are in the properties section of the response. These properties describe the keys and values that are used to provide answers in the client_survey field that is provided when creating or updating a Household.

Usage Example

  1. Make a GET request to /comm/client_survey/
    • The response will be a JSON Schema object describing any survey questions that your organization has set up with Picwell -- See sidebar.
    • Each property represents a question about a piece of data that is needed.
      • The description field is the text to be displayed to the user.
      • The type field is the data type of the answer to the survey question.
      • If the property has an enum field, its values represent the options that the user can choose from to answer the survey question.
      • If the property has a pattern field, its value represents the regular expression that has to be used to validate the answer.
  2. Provide the question keys and corresponding user-provided answers to these questions in a client_survey property of the Household object to be used in the Recommendation Request. See sidebar for an example, or the Household documentation.

Example Household POST request

{
  "members": { ... },
  "survey": [ ... ],
  "client_survey": {
    "is_full_time_or_part_time": "Full-Time",
    "is_j1_visa": "Yes"
  },
  "income": ...
}

Drug Search

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

Search for Drugs by Partial Name

GET /comm/drugs/?q={partial-drug-name}

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

A common use-case for this endpoint is to act as a search interface for front-end applications. When doing so, be sure to throttle or debounce requests to maximize responsiveness.

See Handling limiting gracefully for more information.

Example request

GET /comm/drugs?q=lipitor HTTP/1.1
Host: api.picwell.net
Content-Type: application/json
Picwell-Auth-Token: <your-auth-token>
Accept: application/vnd.picwell.v6+json

Parameters

Parameter In Type Required Description
q query string true Name of drug to search for. Partial and fuzzy matches are supported.

Example responses

200 Response

{
  "drugs": [
    {
      "form": "Oral Tablet",
      "name": "LIPITOR",
      "strengths": [
        {
          "full_name": "atorvastatin 10 MG Oral Tablet [Lipitor]",
          "generic_name": "atorvastatin 10 MG Oral Tablet",
          "generic_rxcui": "617312",
          "ndc": "00071015510",
          "rxcui": "617314",
          "rxnorm_prescribable_name": "Lipitor 10 MG Oral Tablet",
          "strength": "10 mg"
        },
        {
          "full_name": "atorvastatin 20 MG Oral Tablet [Lipitor]",
          "generic_name": "atorvastatin 20 MG Oral Tablet",
          "generic_rxcui": "617310",
          "ndc": "00071015610",
          "rxcui": "617318",
          "rxnorm_prescribable_name": "Lipitor 20 MG Oral Tablet",
          "strength": "20 mg"
        },
        {
          "full_name": "atorvastatin 40 MG Oral Tablet [Lipitor]",
          "generic_name": "atorvastatin 40 MG Oral Tablet",
          "generic_rxcui": "617311",
          "ndc": "00071015723",
          "rxcui": "617320",
          "rxnorm_prescribable_name": "Lipitor 40 MG Oral Tablet",
          "strength": "40 mg"
        },
        {
          "full_name": "atorvastatin 80 MG Oral Tablet [Lipitor]",
          "generic_name": "atorvastatin 80 MG Oral Tablet",
          "generic_rxcui": "259255",
          "ndc": "00071015823",
          "rxcui": "262095",
          "rxnorm_prescribable_name": "Lipitor 80 MG Oral Tablet",
          "strength": "80 mg"
        }
      ]
    },
    {
      "brand": "LIPITOR",
      "form": "Oral Tablet",
      "name": "Atorvastatin",
      "strengths": [
        {
          "full_name": "atorvastatin 10 MG Oral Tablet",
          "ndc": "00378201505",
          "rxcui": "617312",
          "rxnorm_prescribable_name": "atorvastatin calcium 10 MG Oral Tablet",
          "strength": "10 mg"
        },
        {
          "full_name": "atorvastatin 20 MG Oral Tablet",
          "ndc": "00378201705",
          "rxcui": "617310",
          "rxnorm_prescribable_name": "atorvastatin calcium 20 MG Oral Tablet",
          "strength": "20 mg"
        },
        {
          "full_name": "atorvastatin 40 MG Oral Tablet",
          "ndc": "00378212105",
          "rxcui": "617311",
          "rxnorm_prescribable_name": "atorvastatin calcium 40 MG Oral Tablet",
          "strength": "40 mg"
        },
        {
          "full_name": "atorvastatin 80 MG Oral Tablet",
          "ndc": "00179014145",
          "rxcui": "259255",
          "rxnorm_prescribable_name": "atorvastatin calcium 80 MG Oral Tablet",
          "strength": "80 mg"
        }
      ]
    }
  ],
  "search_term": "lipitor",
  "version": "comm"
}

Responses

Status Meaning Description Schema
200 OK Matching drugs Drug Search Response

Background

Suggestions for Use

Although there are many ways to render a drug search UI/UX using this API, we recommend the following:

  1. With a type-ahead input, iterate through each PrescriptionDrug object in the DrugSet and list the drugs.name and drugs.form fields for each.

  2. Once the name and form for a drug has been selected by the user, prompt the user to select from the relevant strength options (from drugs[].strengths[].strength field).

  3. Persist the value of drugs[].strengths[].ndc for user selected drugs to utilize in downstream API calls to Picwell.

  4. For certain drugs, it may be necessary to require the user to select from additional prescribable volumes to fully specify a drug. Enable this lookup by supporting selections against drugs[].strengths[].rxnorm_prescribable_name

[1] For about 3% of drugs in our database, a name, form, and strength combination is not enough to create a unique identifier because there are duplicate strengths for certain forms. An example of this is the form Prefilled Syringe in the drug Heparin. As you can see in the response below, the strength fields are both 1 unt/ml. This is because the volumes are different but the drug proportions are the same. In this case, we recommend showing a third input step after strength, containing the rxnorm_presribable_name field of the duplicates. This field will give the volume or any other information to distinguish the 2 drugs.

{
  "drugs": [
    {
      "form": "Prefilled Syringe",
      "name": "Heparin, porcine",
      "strengths": [
        {
          "full_name": "3 ML heparin sodium, porcine 1 UNT/ML Prefilled Syringe",
          "ndc": "63807030035",
          "rxcui": "1362029",
          "rxnorm_prescribable_name": "heparin sodium, porcine 3 UNT in 3 ML Prefilled Syringe",
          "strength": "1 unt/ml"
        },
        {
          "full_name": "5 ML heparin sodium, porcine 1 UNT/ML Prefilled Syringe",
          "ndc": "64253044425",
          "rxcui": "1362030",
          "rxnorm_prescribable_name": "heparin sodium, porcine 5 UNT in 5 ML Prefilled Syringe",
          "strength": "1 unt/ml"
        }
        ...
     }]}

Search for Drug by NDC

GET /comm/drug_details/{ndc}

You may use this endpoint to retrieve drug properties for a given ndc.

Responses

200 Response (Branded Drug)

{
  "form": "Topical Lotion",
  "name": "PLEXION",
  "brands": null,
  "ndc": "57883040504",
  "rxcui": "1494824",
  "strength": "9.8-4.8%",
  "full_name": "sulfacetamide sodium 98 MG/ML / sulfur 48 MG/ML Topical Lotion [Plexion]",
  "rxnorm_prescribable_name": "PLEXION 9.8 % / 4.8 % Topical Lotion",
  "generic_rxcui": "1494174",
  "generic_name": "sulfacetamide sodium 98 MG/ML / sulfur 48 MG/ML Topical Lotion"
}
Status Meaning Description Schema
200 OK Matching drug Drug Details Response

Discussion

Households

Methods allow for operations on Objects, and typically generate Object References as side effects. Picwell exposes API endpoints that conform to RESTful semantics.

Create a new household

POST /comm/household/

Establish a household for use in a recommendation request.

Body parameter

{
  "members": [
    {
      "age": 32,
      "gender": "male",
      "prescriptions": [
        {
          "ndc": "00093738598"
        }
      ],
      "uses_tobacco": false,
      "planning_for_child": false,
      "dependant": false,
      "policyholder": true,
      "external_id": "policyholder-id"
    },
    {
      "age": 29,
      "gender": "female",
      "prescriptions": [
        {
          "ndc": "00093738598"
        }
      ],
      "external_id": "DEF_456",
      "dependant": false,
      "policyholder": false,
      "planning_for_child": true,
      "uses_tobacco": false
    }
  ],
  "survey": [
    {
      "question_id": "1",
      "answer": "very_important"
    },
    {
      "question_id": "2",
      "answer": "gt_5"
    },
    {
      "question_id": "4",
      "answer": "100_150"
    },
    {
      "question_id": "5",
      "answer": "plan_b"
    },
    {
      "question_id": "6",
      "answer": "plan_b"
    }
  ],
  "client_survey": {
    "is_j1_visa": "Yes",
    "is_full_time_or_part_time": "Full-Time"
  },
  "income": 75000,
  "spending_accounts": [
    {
      "employee_contribution": 234.0,
      "employer_contribution": 543.0,
      "type": "hsa"
    }
  ],
  "enrollment": {
    "plan_id": "123_345_9878",
    "network_id": "ABC_FGH"
  },
  "zip_code": "12345",
  "version": 2021,
  "external_id": "test",
  "group": "ABC-Employer-Group"
}

Parameters

Parameter In Type Required Description
body body Household true Household definition

Example responses

201 Response

{
  "id": "863d3113-3fec-46b3-8a2a-b4e99f5ba3c2",
  "version": 2021
}

Responses

Status Meaning Description Schema
201 Created Household created HouseholdReference

Discussion

Query household versions -- DEPRECATED

GET /comm/household/

Get all versions of a Household by external_id

DEPRECATED An upcoming release (December 2024) will continue to support this endpoint and the version field, but multiple versions of a household will not be supported or saved. The returned array will contain a single record reflecting the most recently saved household data.

Parameters

Parameter In Type Required Description
external_id query string true Household ID

Example responses

200 Response

[
  {
    "id": "863d3113-3fec-46b3-8a2a-b4e99f5ba3c2",
    "version": 2020
  }
]

Responses

Status Meaning Description Schema
200 OK Household versions List[Household Reference]

Discussion

Create household version -- DEPRECATED

POST /comm/household/{household_id}/

Create a new version of a previously created household.

DEPRECATED An upcoming release (December 2024) will continue to support this endpoint, but multiple versions of a household will not be supported. This endpoint will persist until the next major version, but will be an alias to Update household, always updating the same household record, with no support for mulitple versions of the household.

Body parameter

{
  "members": [
    {
      "age": 32,
      "gender": "male",
      "prescriptions": [
        {
          "ndc": "00093738598"
        }
      ],
      "uses_tobacco": true,
      "planning_for_child": false,
      "dependant": false,
      "policyholder": true,
      "external_id": "policyholder-id"
    }
  ],
  "survey": [
    {
      "question_id": "1",
      "answer": "very_important"
    }
  ],
  "zip_code_3": "123",
  "version": 2021,
  "external_id": "test",
  "group": "ABC-Employer-Group",
  "pay_periods_per_year": 24
}

Parameters

Parameter In Type Required Description
household_id path string true The household ID
body body Household true Household definition

Example responses

200 Response

{
  "id": "863d3113-3fec-46b3-8a2a-b4e99f5ba3c2",
  "version": 2021
}

Responses

Status Meaning Description Schema
200 OK Version created Household Reference

Discussion

Update household

PUT /comm/household/{household_id}/

Update an existing Household.

Body parameter

{
  "members": [
    {
      "age": 32,
      "gender": "male",
      "prescriptions": [
        {
          "ndc": "00093738598"
        }
      ],
      "uses_tobacco": true,
      "planning_for_child": false,
      "dependant": false,
      "policyholder": true,
      "external_id": "policyholder-id"
    }
  ],
  "survey": [
    {
      "question_id": "1",
      "answer": "very_important"
    }
  ],
  "zip_code": "12345",
  "version": 2021,
  "external_id": "test"
}

Parameters

Parameter In Type Required Description
household_id path string true Household ID
updates body Household true Updated household

Example responses

200 Response

{
  "id": "863d3113-3fec-46b3-8a2a-b4e99f5ba3c2",
  "version": 2021
}

Responses

Status Meaning Description Schema
200 OK Household updated Household Reference

Discussion

Get household

GET /comm/household/{household_id}/

Retrieve a specific version of a Household.

DEPRECATED An upcoming release (December 2024) will continue to support this endpoint and the version field, but multiple versions of a household will not be supported or saved. The returned array will contain a single record reflecting the most recently saved household data.

Parameters

Parameter In Type Required Description
household_id path string true Household ID
version query string false DEPRECATED - Desired household version. If not specified, defaults to latest.

Example responses

200 Response

{
  "spending_accounts": [
    {
      "employee_contribution": 234,
      "employer_contribution": 543,
      "employer_percentage_contribution": null,
      "type": "hsa",
      "employer_contribution_limit": null
    }
  ],
  "enrollment": {
    "plan_id": "123_345_9878",
    "network_id": "ABC_FGH"
  },
  "zip_code_3": "123",
  "zip_code": "12345",
  "version": 2021,
  "survey": [
    {
      "question_id": "1",
      "answer": "very_important"
    }
  ],
  "members": [
    {
      "age": 32,
      "gender": "male",
      "prescriptions": [
        {
          "ndc": "00093738598",
          "quantity": 0,
          "frequency": 0
        }
      ],
      "uses_tobacco": true,
      "planning_for_child": false,
      "dependant": false,
      "policyholder": true,
      "external_id": "policyholder-id"
    }
  ],
  "income": 75000,
  "external_id": "test",
  "group": "ABC-Employer-Group",
  "pay_periods_per_year": 24
}

Responses

Status Meaning Description Schema
200 OK Household retrieved Household

Plans

Get Health Plans

GET /comm/plans/health/

Get all available health plans.

Example request

GET /comm/plans/health/?external_ids=Aetna3500,Aetna2700&fields=carrier_name,external_id,hsa_eligible,hra_eligible,name,health_plan_type,benefits.generic_drugs HTTP/1.1
Host: api.picwell.net
Picwell-Auth-Token: <your-auth-token>
Accept: application/vnd.picwell.v6+json

Example response

{
  "plans": [
    {
      "carrier_name": "Aetna",
      "external_id": "Aetna3500",
      "health_plan_type": "POS",
      "hsa_eligible": true,
      "hra_eligible": false,
      "name": "Aetna National 3500/80",
      "benefits": {
        "generic_drugs": {
          "description": "Generic Drugs",
          "in_network": [
            {
              "coinsurance": null,
              "copay": 10,
              "covered": true,
              "days_supply": 30,
              "deductible_applies": false,
              "max_oop_applies": true,
              "min_cost_sharing": 1,
              "max_cost_sharing": 100
            }
          ],
          "secondary_in_network": [
            {
              "coinsurance": null,
              "copay": 15,
              "covered": true,
              "days_supply": 30,
              "deductible_applies": false,
              "max_oop_applies": true,
              "min_cost_sharing": 1,
              "max_cost_sharing": 100
            }
          ],
          "out_of_network": [
            {
              "coinsurance": 40,
              "copay": 10,
              "covered": true,
              "days_supply": 30,
              "deductible_applies": false,
              "max_oop_applies": true,
              "min_cost_sharing": 1,
              "max_cost_sharing": 100
            }
          ]
        }
      }
    },
    {
      "carrier_name": "Aetna",
      "external_id": "Aetna2700",
      "health_plan_type": "HMO",
      "hsa_eligible": true,
      "hra_eligible": false,
      "name": "Aetna National 2700/90",
      "benefits": {
        "generic_drugs": {
          "description": "Generic Drugs",
          "in_network": [
            {
              "coinsurance": null,
              "copay": 10,
              "covered": true,
              "days_supply": 30,
              "deductible_applies": false,
              "max_oop_applies": true,
              "min_cost_sharing": 1,
              "max_cost_sharing": 100
            }
          ],
          "secondary_in_network": [
            {
              "coinsurance": null,
              "copay": 15,
              "covered": true,
              "days_supply": 30,
              "deductible_applies": false,
              "max_oop_applies": true,
              "min_cost_sharing": 1,
              "max_cost_sharing": 100
            }
          ],
          "out_of_network": [
            {
              "coinsurance": 40,
              "copay": 10,
              "covered": true,
              "days_supply": 30,
              "deductible_applies": false,
              "max_oop_applies": true,
              "min_cost_sharing": 1,
              "max_cost_sharing": 100
            }
          ]
        }
      }
    }
  ]
}

Parameters

Parameter In Type Required Description
external_ids query string false Comma-separated list of external ids denoting plans to retrieve. If not specified, all plans are returned.
fields query string false Comma-separated list of desired response fields. If not specified, only external id is returned.

Responses

Status Meaning Schema
200 OK Detailed Health Plan Response

Discussion

Get Health Plan Details

GET /comm/plans/health/{external_id}/

Get full plan details available for a given health plan.

Example request

GET /comm/plans/health/Aetna3500/ HTTP/1.1
Host: api.picwell.net
Picwell-Auth-Token: <your-auth-token>
Accept: application/vnd.picwell.v6+json

Example response

{
  "benefits": {
    "generic_drugs": {
      "description": "Generic Drugs",
      "in_network": [
        {
          "coinsurance": null,
          "copay": 10,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ],
      "secondary_in_network": [
        {
          "coinsurance": null,
          "copay": 15,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ],
      "out_of_network": [
        {
          "coinsurance": 40,
          "copay": 10,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ]
    },
    "non_preferred_brand_drugs": {
      "description": "Non-Preferred Brand Drugs",
      "in_network": [
        {
          "coinsurance": null,
          "copay": 60,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ],
      "secondary_in_network": [
        {
          "coinsurance": null,
          "copay": 65,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ],
      "out_of_network": [
        {
          "coinsurance": 40,
          "copay": 60,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ]
    },
    "preferred_brand_drugs": {
      "description": "Preferred Brand Drugs",
      "in_network": [
        {
          "coinsurance": null,
          "copay": 35,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ],
      "secondary_in_network": [
        {
          "coinsurance": null,
          "copay": 37,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ],
      "out_of_network": [
        {
          "coinsurance": 40,
          "copay": 35,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ]
    },
    "primary_care_visit": {
      "description": "Primary Care Visit to Treat an Injury or Illness",
      "in_network": {
        "coinsurance": 20,
        "copay": null,
        "copay_frequency": null,
        "copay_prior_to_deductible": null,
        "covered": true,
        "deductible_applies": true,
        "limit_quantity": null,
        "limit_unit": null,
        "max_oop_applies": true,
        "minimum_stay": null,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      },
      "secondary_in_network": {
        "coinsurance": 25,
        "copay": null,
        "copay_frequency": null,
        "copay_prior_to_deductible": null,
        "covered": true,
        "deductible_applies": true,
        "limit_quantity": null,
        "limit_unit": null,
        "max_oop_applies": true,
        "minimum_stay": null,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      },
      "out_of_network": {
        "coinsurance": 40,
        "copay": null,
        "copay_frequency": null,
        "copay_prior_to_deductible": null,
        "covered": true,
        "deductible_applies": true,
        "limit_quantity": null,
        "limit_unit": null,
        "max_oop_applies": true,
        "minimum_stay": null,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    },
    "specialist_visit": {
      "description": "Specialist Visit",
      "in_network": {
        "coinsurance": 20,
        "copay": null,
        "copay_frequency": null,
        "copay_prior_to_deductible": null,
        "covered": true,
        "deductible_applies": true,
        "limit_quantity": null,
        "limit_unit": null,
        "max_oop_applies": true,
        "minimum_stay": null,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      },
      "secondary_in_network": {
        "coinsurance": 25,
        "copay": null,
        "copay_frequency": null,
        "copay_prior_to_deductible": null,
        "covered": true,
        "deductible_applies": true,
        "limit_quantity": null,
        "limit_unit": null,
        "max_oop_applies": true,
        "minimum_stay": null,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      },
      "out_of_network": {
        "coinsurance": 40,
        "copay": null,
        "copay_frequency": null,
        "copay_prior_to_deductible": null,
        "covered": true,
        "deductible_applies": true,
        "limit_quantity": null,
        "limit_unit": null,
        "max_oop_applies": true,
        "minimum_stay": null,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    },
    "specialty_drugs": {
      "description": "Specialty Drugs",
      "in_network": [
        {
          "coinsurance": 20,
          "copay": null,
          "covered": true,
          "days_supply": null,
          "deductible_applies": true,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ]
    }
  },
  "carrier_name": "Aetna",
  "deductible": {
    "comprehensive": {
      "combined": null,
      "in_network": {
        "family": 7000,
        "individual": 3500,
        "individual_child": null,
        "individual_spouse": null
      },
      "secondary_in_network": {
        "family": 8000,
        "individual": 4000,
        "individual_child": null,
        "individual_spouse": null
      },
      "out_of_network": {
        "family": 14000,
        "individual": 7000,
        "individual_child": null,
        "individual_spouse": null
      }
    },
    "health_and_drug": null,
    "embedded": false
  },
  "external_id": "Aetna3500",
  "health_plan_type": "HDHP",
  "hsa_eligible": true,
  "hra_eligible": false,
  "max_oop": {
    "comprehensive": {
      "combined": null,
      "in_network": {
        "family": 11900,
        "individual": 5950,
        "individual_child": null,
        "individual_spouse": null
      },
      "secondary_in_network": {
        "family": 12000,
        "individual": 6000,
        "individual_child": null,
        "individual_spouse": null
      },
      "out_of_network": {
        "family": 20000,
        "individual": 10000,
        "individual_child": null,
        "individual_spouse": null
      }
    },
    "health_and_drug": null,
    "embedded": false
  },
  "name": "Aetna National 3500/80"
}

Responses

Status Meaning Schema
200 OK Detailed Health Plan Description

People Like You

Calculate People Like You

GET /comm/ply/{household-id}/

Gets spending categories related to the Household

Picwell’s “People Like You” (PLY) feature calculates a number of statistics about health care utilization and spending for a specific users’ household.

Parameters

Parameter In Type Required Description
household_id path string true Household ID

Responses

Example responses

200 Response

{
  "claim_cost": {
    "emergency_urgent_care": {
      "mean": 1045.06,
      "p25": 190.23,
      "p50": 427.0,
      "p75": 1377.81
    },
    "inpatient": {
      "mean": 8098.72,
      "p25": 1375.46,
      "p50": 7430.38,
      "p75": 12147.42
    },
    "labs_diagnostics": {
      "mean": 478.53,
      "p25": 90.03,
      "p50": 209.03,
      "p75": 537.97
    },
    "office_visits": {
      "mean": 638.67,
      "p25": 264.97,
      "p50": 499.34,
      "p75": 847.905
    }
  },
  "claim_rate": {
    "emergency_urgent_care": 0.382,
    "inpatient": 0.056,
    "labs_diagnostics": 0.794,
    "office_visits": 0.862
  },
  "total_allowed_spending": 3381.16,
  "utilization_level_dist": {
    "high": 0.082,
    "low": 0.412,
    "moderate": 0.506
  }
}
Status Meaning Schema
200 OK PLY Response

Recommendations

Generate Health-Only Recommendations

POST /comm/recommendation/{household_id}/

Make a recommendation for the provided set of health plans for the Household.

If passing a plan_selection_id in the request body, the endpoint will validate that the household_id in the path matches the household_id found in the Eligibility Set.

Body parameter

{
  "plans": [
    {
      "external_id": "health_plan_1",
      "premiums": {
        "employee_contribution": 50,
        "employer_contribution": 50
      }
    },
    {
      "external_id": "health_plan_2",
      "premiums": {
        "employee_contribution": 50,
        "employer_contribution": 50
      }
    }
  ],
  "plan_selection_id": "my_plan_selection",
  "member_ids": ["policyholder-id", "spouse-id"]
}

Parameters

Parameter In Type Required Description
household_id path string true Household ID
recommendation_request body Health Recommendation Request true Health Recommendation request
version query string false *DEPRECATED - * Desired household version. If not specified, defaults to the latest version.

Example responses

200 Response

{
  "recommendations": [
    {
      "costs": {
        "annual_fsa_dollars_used": 0,
        "annual_hra_dollars_used": 0,
        "annual_hra_employer_dollars_used": 0,
        "annual_hsa_dollars_used": 0,
        "annual_hsa_employer_dollars_used": 0,
        "annual_hsa_tax_savings": 0,
        "annual_sihra_dollars_used": 0,
        "annual_tax_benefit": 0,
        "drugs": 0,
        "effective_premium": 50,
        "real_cost": 800.5,
        "services": {
          "in_network": 600.5
        },
        "spending_account_balance_increase": 0,
        "spending_account_benefit": 0
      },
      "tax_rates": {
        "federal": 0.37
      },
      "plan_details": {
        "deductible": {
          "comprehensive": null,
          "health_and_drug": {
            "drug": {
              "combined": null,
              "in_network": {
                "embedded_per_person": null,
                "total": 150.0
              },
              "out_of_network": {
                "embedded_per_person": null,
                "total": 150.0
              },
              "secondary_in_network": null
            },
            "health": {
              "combined": null,
              "in_network": {
                "embedded_per_person": null,
                "total": 1250.0
              },
              "secondary_in_network": null,
              "out_of_network": {
                "embedded_per_person": null,
                "total": 4500.0
              }
            }
          }
        },
        "max_oop": {
          "comprehensive": {
            "combined": null,
            "in_network": {
              "embedded_per_person": null,
              "total": 3500.0
            },
            "secondary_in_network": null,
            "out_of_network": {
              "embedded_per_person": null,
              "total": 31500.0
            }
          },
          "health_and_drug": null
        }
      },
      "health_provider_locations": [],
      "plan": {
        "external_id": "health_plan_1",
        "id": "health_plan_1"
      },
      "score": 95,
      "tier": "green"
    },
    {
      "costs": {
        "annual_fsa_dollars_used": 0,
        "annual_hra_dollars_used": 0,
        "annual_hra_employer_dollars_used": 0,
        "annual_hsa_dollars_used": 0,
        "annual_hsa_employer_dollars_used": 0,
        "annual_hsa_tax_savings": 0,
        "annual_sihra_dollars_used": 0,
        "annual_tax_benefit": 0,
        "drugs": 0,
        "effective_premium": 100,
        "real_cost": 1200.47,
        "services": {
          "in_network": 1000.0
        },
        "spending_account_balance_increase": 0,
        "spending_account_benefit": 0
      },
      "tax_rates": {
        "federal": 0.37
      },
      "plan_details": {
        "deductible": {
          "comprehensive": null,
          "health_and_drug": {
            "drug": {
              "combined": null,
              "in_network": {
                "embedded_per_person": null,
                "total": 150.0
              },
              "out_of_network": {
                "embedded_per_person": null,
                "total": 150.0
              },
              "secondary_in_network": null
            },
            "health": {
              "combined": null,
              "in_network": {
                "embedded_per_person": null,
                "total": 1250.0
              },
              "secondary_in_network": null,
              "out_of_network": {
                "embedded_per_person": null,
                "total": 4500.0
              }
            }
          }
        },
        "max_oop": {
          "comprehensive": {
            "combined": null,
            "in_network": {
              "embedded_per_person": null,
              "total": 3500.0
            },
            "secondary_in_network": null,
            "out_of_network": {
              "embedded_per_person": null,
              "total": 31500.0
            }
          },
          "health_and_drug": null
        }
      },
      "health_provider_locations": [],
      "plan": {
        "external_id": "health_plan_1",
        "id": "health_plan_1"
      },
      "score": 93,
      "tier": "green"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Health Recommendations generated Health Recommendation Response

Generate A&V Recommendations

POST /comm/recommendation/{household_id}/

Make a recommendation for the provided set of Ancillary & Voluntary plans and packages for the Household.

Body parameter

{
  "packages": [["health", "hi"], ["health"]],
  "plans": [
    {
      "premiums": {
        "employee_contribution": 0
      },
      "external_id": "HI_Plan_1",
      "plan_type": "hi"
    },
    {
      "premiums": {
        "employee_contribution": 0
      },
      "external_id": "Health_Plan_1",
      "plan_type": "health"
    },
    {
      "premiums": {
        "employee_contribution": 0
      },
      "external_id": "HI_Plan_2",
      "plan_type": "hi"
    }
  ]
}

Parameters

Parameter In Type Required Description
household_id path string true Household ID
recommendation_request body A&V Recommendation Request true Recommendation request

Example responses

200 Response

{
  "packages": [
    {
      "ceq": 1109.1421577290894,
      "plan_types": ["health", "hi"],
      "plans": [
        {
          "external_id": "250782_90014_2021"
        },
        {
          "external_id": "aetna_B"
        }
      ],
      "premium": 0,
      "real_cost": 688.6843666666665
    },
    {
      "ceq": 1137.7460457190764,
      "plan_types": ["health", "hi"],
      "plans": [
        {
          "external_id": "250782_90014_2021"
        },
        {
          "external_id": "aetna_A"
        }
      ],
      "premium": 0,
      "real_cost": 701.3510333333332
    },
    {
      "ceq": 1197.8325913996032,
      "plan_types": ["health"],
      "plans": [
        {
          "external_id": "250782_90014_2021"
        }
      ],
      "premium": 0,
      "real_cost": 714.0176999999999
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK A&V Recommendations generated A&V Recommendation Response

Discussion

DEPRECATED An upcoming release (December 2024) will continue to support this endpoint and the version field, but multiple versions of a household will not be supported or saved. The returned array will contain a single record reflecting the most recently saved household data.

Supplemental Plans

Generate Supplemental Recommendations

POST /comm/supplemental/recommendation/{household_id}/

Make supplemental plan recommendations on the provided set of supplemental plans. Recommendations are generated for a given household and eligible health plan.

Supplemental Plan Determination

Provided Supplemental Plans

If the plans are provided via the request body, we will generate recommendations using those specified plans.

Inferred Supplemental Plans

To rely on Picwell configured supplemental plan data, omit the plans key from the request body.

More Precise Recommendations

Specifying a health plan in the body with the health_plan_external_id key will take into account criteria of a health plan the household is eligible for. If a health plan cannot be supplied at the time of the recommendation, Picwell will make the recommendation using only criteria of household.

Body parameter

{
  "health_plan_external_id": "ppo_plan_1",
  "plans": [
    {
      "plan_type": "dental",
      "external_id": "dental1",
      "eligible_member_ids": ["external_id_1"]
    },
    {
      "plan_type": "dental",
      "external_id": "dental2",
      "eligible_member_ids": ["external_id_1"]
    },
    {
      "plan_type": "hospital",
      "external_id": "hospital1",
      "eligible_member_ids": ["external_id_1"]
    }
  ]
}

Parameters

Parameter In Type Description
household_id path string
Supplemental Recommendation Request body Supplemental Recommendation Request The request body.

Example responses

200 Response

{
  "plans": [
    {
      "external_id": "dental2",
      "plan_type": "dental",
      "reasons": [
        {
          "code": "dental_routine_care",
          "data": {},
          "description": "Everyone needs routine dental care, and this will help you cover those costs."
        }
      ],
      "score": 3,
      "score_type": "always_recommend"
    },
    {
      "external_id": "dental1",
      "plan_type": "dental",
      "reasons": [
        {
          "code": "dental_routine_care",
          "data": {},
          "description": "Everyone needs routine dental care, and this will help you cover those costs."
        }
      ],
      "score": 3,
      "score_type": "always_recommend"
    },
    {
      "external_id": "vision1",
      "plan_type": "vision",
      "reasons": [
        {
          "code": "eye_exam",
          "data": {},
          "description": "Even if you don’t wear glasses, it's a good idea to get routine eye exams."
        },
        {
          "code": "eye_glasses",
          "data": {},
          "description": "This coverage helps pay for glasses or contact lenses, if you need them."
        }
      ],
      "score": 3,
      "score_type": "always_recommend"
    },
    {
      "external_id": "dis2",
      "plan_type": "std",
      "reasons": [],
      "score": 1,
      "score_type": "qualitative"
    },
    {
      "external_id": "hi1",
      "plan_type": "hospital",
      "reasons": [
        {
          "code": "hospital_pregnancy",
          "data": {
            "applicable_members": ["DEF_456"]
          },
          "description": "You may receive benefits if you get bills for inpatient labor and delivery"
        }
      ],
      "score": 3,
      "score_type": "qualitative"
    },
    {
      "external_id": "life-123",
      "plan_type": "life",
      "reasons": [
        {
          "code": "life_dependent",
          "data": {
            "applicable_members": ["user1234"]
          },
          "description": "If you have dependents, life insurance will help ensure their financial future should you die."
        }
      ],
      "score": 1,
      "score_type": "qualitative"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK Supplemental Recommendation generated Supplemental Recommendation Response

List of All Potential Reasons Used in Supplemental Recommendation Response

Code Applicable Plan Types Available Data Fields
dental_orthodontia dental applicable_members
dental_routine_care dental None
eye_exam vision None
eye_glasses vision None
fsa_dependent_pregnancy fsa_dependent applicable_members
high_ded_low_cap accident, critical, hospital medical_deductible, capacity_to_pay
high_risk_aversion hospital, std None
hospital_pregnancy hospital applicable_members
hospitalization hospital applicable_members
life_dependent life applicable_members
low_capacity_to_pay std capacity_to_pay
middle_aged_illnesses critical applicable_members, min_age, max_age
moderate_high_risk_aversion accident, critical, hospital risk_aversion
physical_activity accident applicable_members
planned_procedure_inpatient hospital applicable_members
risk_averse_with_high_rx_count accident, critical, hospital applicable_members, risk_aversion
senior_aged_illnesses critical applicable_members, min_age
std_pregnancy std applicable_members
tobacco_usage critical applicable_members

Scoring Criteria

Discussion

HSA

Get HSA Recommendations

POST /comm/hsa/{household_id}/

This endpoint provides recommended contribution and benefit deciles for a plan based on the Household, or a subset of a Household's members.

With these deciles, you can compare expected out-of-pocket costs, recommended HSA contribution amounts, and corresponding tax benefits for a given Household and Plan.

For example, you can compare a range of expected out-of-pocket costs, say 20th percentile vs. 50th vs. 80th, to help describe to a user how an HSA may impact their healthcare spending.

The 11 numbers in the decile responses represent the approximate minimum, 10th, 20th, 30th, 40th, 50th, 60th, 70th, 80th, 90th, and approximate maximum. For example, the 20th percentile means that for all the estimated out-of-pocket costs for people like you, 20% of people will pay that amount or less. On the other hand, the 80th percentile represents that 20% of people like you will pay greater than that amount.

In addition to a decile representation, our calculated average (mean) out-of-pocket cost is provided with its associated recommended contribution amounts and benefits. This can be used as an alternative to deciles in order to provide a simple but meaningful recommendation.

Body parameter

{
  "external_id": "Aetna_3000",
  "spending_account_contribution": 25,
  "member_ids": ["policyholder-id", "spouse-id"]
}

Parameters

Parameter In Type Required Description
household_id path string true Household ID
HSAPlanData body HSA Plan Data true HSA Plan Data request.

Providing an unknown external_id will result in a Unknown Plan External IDs error.

Example responses

200 Response

{
  "employer_contribution": 300.0,
  "employer_contribution_deciles": [
    300.0, 300.0, 300.0, 300.0, 300.0, 300.0, 300.0, 300.0, 300.0, 300.0, 300.0
  ],
  "hsa_benefit": 713.1839176661636,
  "hsa_benefit_deciles": [
    300.0, 300.0, 300.0, 344.9306735753909, 416.50436396101725,
    509.2799262692803, 626.1487782167769, 800.3378432939336, 991.9353041375997,
    1186.6287342883284, 1774.0
  ],
  "oop": 2178.10871666438,
  "oop_deciles": [
    0, 66.08153092887338, 249.69340277216497, 504.2303344335952,
    829.5652907318965, 1251.2723921330924, 1782.4944464398948,
    2574.2629240633346, 3445.160473352726, 4330.130610401493, 9115.929340023968
  ],
  "recommended_contribution": 1878.1087166643802,
  "recommended_contribution_deciles": [
    0, 0, 0, 204.2303344335952, 529.5652907318965, 951.2723921330924,
    1482.4944464398948, 2274.2629240633346, 3145.160473352726,
    4030.130610401493, 6700.0
  ],
  "tax_benefit": 413.1839176661636,
  "tax_benefit_deciles": [
    0.0, 0.0, 0.0, 44.93067357539095, 116.50436396101723, 209.2799262692803,
    326.14877821677686, 500.3378432939336, 691.9353041375997, 886.6287342883285,
    1474.0
  ]
}

Responses

Status Meaning Description Schema
200 OK HSA Recommendation generated HSA Recommendation Response

Survey

Survey Questions

It is recommended the following questionnaire is provided to end-users to optimize their recommendations.

Question ID 3 is deprecated and marked for removal in v7. Please use the planning_for_child attribute on the Household Member to indicate pregnancy.

Question ID Question Possible Answers Answer Descriptor
1 How important is it that your (or your family's) current doctor(s) are in the network of the health plan that you choose?
  • very_important
  • important
  • not_very_important
  • not_important
  • Very Important
  • Important
  • Not Very Important
  • Not Important
2 Think about the physician who's most important to you (or your family). How long have you been with this physician?
  • lt_1
  • 2_3
  • 4_5
  • gt_5
  • 0
  • One year or less
  • 2 to 3 years
  • 4 to 5 years
  • More than 5 years
  • I do not have a current physician
3 (Deprecated) Are you or a covered family member planning to have a child in the next year?
  • yes
  • no
  • Yes
  • No
4 What was your total household income before taxes during the past 12 months?
  • lt_25
  • 25_35
  • 35_50
  • 50_75
  • 75_100
  • 100_150
  • 150_200
  • gt_200
  • Less than $25,000
  • $25,000 to $34,999
  • $35,000 to $49,999
  • $50,000 to $74,999
  • $75,000 to $99,999
  • $100,000 to $149,999
  • $150,000 to $199,999
  • $200,000 or more
5 Imagine that you have a 10% chance of being injured and needing surgery (which means you have a 90% chance you avoid injury and don't have unexpected surgery). Which plan would you choose?
  • plan_a
  • plan_b
  • Plan A: where your annual plan costs (premiums) are $3000 higher and you pay $0 out-of-pocket for the surgery.
  • Plan B: where your annual plan costs (premiums) are $3000 lower, but you have to pay $5000 out-of-pocket for the surgery.
6 Imagine that you have a 50% chance of being injured and needing surgery (which means you have a 50% chance you avoid injury and don't have unexpected surgery). Which plan would you choose?
  • plan_a
  • plan_b
  • Plan A: where your annual plan costs (premiums) are $3000 higher and you pay $0 out-of-pocket for the surgery.
  • Plan B: where your annual plan costs (premiums) are $3000 lower, but you have to pay $5000 out-of-pocket for the surgery.
7 Do you, or a covered family member, have any of the following medical conditions? Check all that apply. See Condition Answer
8 If you have a Health Savings Account (HSA), what is your current balance?
  • not_applicable
  • 1_1000
  • 1000_3000
  • 3000_5000
  • gt_5000
  • unknown
  • prefer_no_answer
  • I don't have one
  • $1 to $999
  • $1000 to $2999
  • $3000 to $4999
  • $5000 or more
  • I don't know my balance.
  • I prefer not to answer
9 If you needed to receive unexpected medical care, what is the largest bill that you could afford to pay?
  • lt_500
  • 500_1000
  • 1000_2000
  • 2000_3000
  • 3000_4000
  • 4000_6000
  • gt_6000
  • prefer_no_answer
  • Less than $500
  • $500 to $999
  • $1,000 to $1,999
  • $2,000 to $2,999
  • $3,000 to $3,999
  • $4,000 to $5,999
  • $6,000 or more
  • I prefer not to answer
10 If one of the doctors you care most about is out of network, would you be willing to find a new in-network doctor if it could save you money?
  • yes
  • no
  • Yes
  • No

Schemas

Auth Request

{
  "username": "picwell",
  "password": "abcabc123123"
}

Properties

Name Type Required Description
username string true The username
password string true The password
ttl_seconds integer false The number of seconds (300 - 14400) until the token expires

ttl_seconds semantics

The ttl_seconds field is optional and defaults to 14400. If specified, it must be between 300 seconds (5 minutes) and 14400 seconds (4 hours). We recommend using the default setting for optimal performance.

Auth Response

{
  "auth_token": "aab82ec6-320f-4fb7-88a8-00bd0d002be0"
}

Properties

Name Type Required Description
auth_token string false The authentication token

Health Provider Location

{
  "external_id": "12345",
  "type": "specialist" | "pcp" | "family",
  "specialty": "Provider Specialty",
  "name": "Doctor Name",
  "location": "Location Name"
}

Properties

Name Type Required Description
external_id string true Unique client-specific ID for this Health Provider Location
type string true The Health Provider Location's type (see Health Provider Location Types below)
specialty [string] true List of specialties
name string false Name of Health Provider Location
location string false Description of in-network health provider locations

Health Provider Location Types

The following are the health provider location types currently supported by the API:

Eligibility

{
  "members": ["policyholder_extid", "spouse_extid"],
  "plans": [
    {
      "external_id": "plan1",
      "external_coverage_tier_id": "external_coverage_tier",
      "monthly_premiums": {
        "post_tax": 15.12,
        "pre_tax": 43.14
      },
      "hsa_annual": {
        "employer_contribution_amount": 50.0
      }
    },
    {
      "external_id": "plan2",
      "external_coverage_tier_id": "external_coverage_tier",
      "monthly_premiums": {
        "post_tax": 0.0,
        "pre_tax": 97.17
      },
      "hsa_annual": {
        "employer_contribution_amount": 100.0
      }
    }
  ]
}

Properties

Name Type Required Description
members List[string] true A list of external IDs corresponding to members of the Household for which this eligibility is being created.
plans List[Eligibility Plans] true Description of the plans for which the household is eligible.

Eligibility Plans

{
  "external_id": "plan2",
  "external_coverage_tier_id": "external_coverage_tier_2",
  "monthly_premiums": {
    "post_tax": 0.0,
    "pre_tax": 97.17
  },
  "hsa_annual": {
    "employer_contribution_amount": 100.0
  }
}

Properties

Name Type Required Description
external_id string true The external ID of a plan for which this Household is eligible.
external_coverage_tier_id string false If desired, specify an external coverage tier to help associate member sets to the desired coverage tier.
monthly_premiums Eligibility Plan Premiums true Description of pre- and post-tax monthly premiums for this plan.
hsa_annual Eligibility Plan Hsa false The annual employer HSA contribution amount for this plan, if applicable. Ignored if plan is not eligible for an HSA.

Eligibility Plan Premiums

{
  "post_tax": 0.0,
  "pre_tax": 97.17
}

Properties

Name Type Required Description
post_tax float false The dollar amount of this plan's monthly premium that is deducted from the employee's pay after tax.
pre_tax float true The dollar amount of this plan's monthly premium that is deducted from the employee's pay before tax.

Eligibility Plan Hsa

{
  "employer_contribution_amount": 50.0
}

Properties

Name Type Required Description
employer_contribution_amount float false The dollar amount that the employer contributes to the employee's HSA per month. Can be 0.0 if the employer makes no contributions.

Plan Selection Resource Id

{
  "id": "863d3113-3fec-46b3-8a2a-b4e99f5ba3c2"
}

Properties

Name Type Required Description
id string true The ID of the Plan Selection resource

Plan Selection Enrollment

{
  "health_plan": {
    "members": ["policyholder_id", "spouse_id"],
    "external_id": "plan1",
    "external_coverage_tier_id": "external_coverage_tier_1",
    "waived": false
  },
  "accounts": [
    {
      "hsa_annual": {
        "employee_contribution_amount": 123.45
      }
    }
  ]
}

Properties

Name Type Required Description
health_plan Plan Selection Plan true Description of the health plan the user intends to enroll in.
accounts List[Plan Selection Account] false Description of contributions to be made to the user's accounts, like HSAs, if applicable and the user has selected contributions.

Plan Selection Plan

{
  "members": ["policyholder_id", "spouse_id"],
  "external_id": "plan-1",
  "external_coverage_tier_id": "external_coverage_tier_1",
  "waived": false
}

Properties

Name Type Required Description
members List[string] false References to the external_id field set individually on members in a household, indicating which members are to be enrolled in the given plan.

Omit if health coverage is waived.
external_id string false External ID of enrolled plan.

Omit if health coverage is waived.
external_coverage_tier_id string false The specified external coverage tier id for the enrolled plan. This assumes it was set at Eligibility Plan creation time.
waived boolean true Set to true if health coverage is waived.

Plan Selection Account

{
  "hsa_annual": {
    "employee_contribution_amount": 123.45
  }
}

Properties

Name Type Required Description
hsa_annual Plan Selection Hsa true Annual contributions made to an HSA by the employee.

Plan Selection Hsa

{
  "employee_contribution_amount": 123.45
}

Properties

Name Type Required Description
employee_contribution_amount float true Annual contribution from employee.

Household Reference

{
  "id": "863d3113-3fec-46b3-8a2a-b4e99f5ba3c2",
  "version": 2021
}

Properties

Name Type Required Description
id string true The ID of the Household
version integer true The client-provided temporal identifier of the Household. Typically the plan year (e.g. 2017)

Discussion

Household

A representation of a household enrolling for coverage. If only part of an actual household is seeking coverage on your platform (e.g. just one member of a household), then supply only those members.

{
  "members": [
    {
      "age": 32,
      "gender": "male",
      "prescriptions": [
        {
          "ndc": "00093738598",
          "quantity": 0,
          "frequency": 0
        }
      ],
      "uses_tobacco": false,
      "planning_for_child": false,
      "dependant": false,
      "policyholder": true,
      "external_id": "policyholder-id"
    },
    {
      "age": 29,
      "gender": "female",
      "prescriptions": [
        {
          "ndc": "00093738598",
          "quantity": 30,
          "frequency": 30
        }
      ],
      "external_id": "spouse-id",
      "dependant": false,
      "policyholder": false,
      "planning_for_child": false,
      "uses_tobacco": false
    }
  ],
  "survey": [
    {
      "question_id": "1",
      "answer": "very_important"
    },
    {
      "question_id": "2",
      "answer": "gt_5"
    },
    {
      "question_id": "4",
      "answer": "100_150"
    },
    {
      "question_id": "5",
      "answer": "plan_b"
    },
    {
      "question_id": "6",
      "answer": "plan_b"
    }
  ],
  "client_survey": {
    "is_j1_visa": "Yes",
    "is_full_time_or_part_time": "Full-Time"
  },
  "zip_code": "12345",
  "income": 75000,
  "spending_accounts": [
    {
      "employee_contribution": 234.0,
      "employer_contribution": 543.0,
      "type": "hsa"
    }
  ],
  "enrollment": {
    "plan_id": "123_345_9878",
    "network_id": "ABC_FGH"
  },
  "version": 2021,
  "external_id": "test",
  "group": "ABC-Employer-Group"
}

Properties

Name Type Required Description
members List[Household Member] true List of enrollees seeking coverage
survey List[Survey Answer] true Responses to Survey questions.

If a question is not provided or is not answered, omit it from this list.
client_survey Client Survey Answers false Responses to Client Survey questions.

If your organization does not use or has not provided any client-specific survey questions, omit the client_survey field.
zip_code_3 string false The first 3 digits of the household's ZIP code. Ex. "020" if zip is "02030".
zip_code string false The household's ZIP code or ZIP+4 code. Ex. "19103" or "19103-3513".
income float false Total household income. This field is preferred over the bucketed salary Survey question. If unanswered or set to 0 a default value of 85000 is used to determine tax rates.
spending_accounts List[Household Spending Account] false List of spending account information. Picwell also accepts contribution information via the recommendation post body or via client specific configuration.
enrollment Household Enrollment false Information regarding the user's intended plan selection.
version integer true Client-provided temporal identifier of the Household. Typically the plan year (e.g. 2017)
external_id string false Unique, client-specific ID for this Household.
group string false Employer group or entity this household belongs to. This is typically reserved for reporting purposes.
pay_periods_per_year int false How many pay periods this employee/household has in a year.

DEPRECATED This value will always default to 12. Any value passed in will be ignored.

Household Member

A representation of a household member.

{
  "age": 0,
  "dependant": false,
  "external_id": "household-id",
  "gender": "male",
  "policyholder": true,
  "prescriptions": [
    {
      "ndc": "string",
      "quantity": 0,
      "frequency": 0
    }
  ],
  "uses_tobacco": true,
  "planning_for_child": true,
  "utilization": {
    "inpatient_days": 1,
    "specialist_visits": 1,
    "pcp_visits": 2
  },
  "planned_procedures": {
    "inpatient_procedures": 1,
    "outpatient_procedures": 2,
    "therapy_visits": 3,
    "mental_visits": 4
  }
}

Properties

Name Type Required Description
age integer true The member's age.
dependant boolean true Member is a child in the household. Policyholder and spouse should have this value set to false.
external_id string true Unique identifier for the member. Picwell requires that this field does not contain PII.
gender string false The member's gender (male, female, or prefer_not_to_answer). If the gender is prefer_not_to_answer or null, the recommendation engine will assume you are female.
policyholder boolean true Set to true if the member is the policyholder. There can only be 1 policyholder per household.
prescriptions List[Prescription] true List of member's prescriptions. If they do not take any medications, represent as an empty list, [].
uses_tobacco boolean true Set to true if the member uses tobacco.
planning_for_child boolean false Set to true if the member is planning on having a child during the enrollment year. Currently optional until Survey Question ID 3 is removed. Passing in this value will override the value of Survey Question ID 3.
utilization Utilization false The previous year's utilization of medical services for this member.
planned_procedures Planned Procedures false Planned procedures in the upcoming year for this member.

Coverage Tier Determination

To ensure Picwell infers the appropriate coverage tier for a given request, ensure your household matches one of the forms below:

Coverage Tier Policy Holder Spouse Child 1 Child 2 Child N
individual dependant=false - - - -
individual_child(ren) dependant=false - dependant=true dependant=true dependant=true
individual_spouse dependant=false dependant=false - - -
family dependant=false dependant=false dependant=true dependant=true dependant=true

Household Spending Account

A representation of a health spending account.

{
  "type": "hsa",
  "employee_contribution": 234.0,
  "employer_contribution": 543.0
}

Properties

Name Type Required Description
type string true Options: 'hsa', 'hra', 'fsa'
employee_contribution float false monthly contribution from employee
employer_contribution float false monthly fixed contribution from employer
employer_percentage_contribution float false the employer's percentage match to an HSA given in decimal, defaults to null
employer_contribution_limit float false annual employer contribution limit to an HSA, defaults to null

Discussion

Household Enrollment

A representation of a household enrollment

{
  "plan_id": "123_345_9878",
  "network_id": "ABC_FGH"
}

Properties

A reference to a plan and network that a Household is enrolled in.

Name Type Required Description
plan_id string false Corresponds to plans external_id
network_id string false external identifier for a network

Detailed Health Plan Description

A detailed representation of a health plan.

{
  "benefits": {
    "generic_drugs": {
      "description": "Generic Drugs",
      "in_network": [
        {
          "coinsurance": null,
          "copay": 10,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ],
      "secondary_in_network": [
        {
          "coinsurance": null,
          "copay": 15,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ],
      "out_of_network": [
        {
          "coinsurance": 40,
          "copay": 10,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ]
    },
    "non_preferred_brand_drugs": {
      "description": "Non-Preferred Brand Drugs",
      "in_network": [
        {
          "coinsurance": null,
          "copay": 60,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ],
      "secondary_in_network": [
        {
          "coinsurance": null,
          "copay": 70,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ],
      "out_of_network": [
        {
          "coinsurance": 40,
          "copay": 60,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ]
    },
    "preferred_brand_drugs": {
      "description": "Preferred Brand Drugs",
      "in_network": [
        {
          "coinsurance": null,
          "copay": 35,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ],
      "out_of_network": [
        {
          "coinsurance": 40,
          "copay": 35,
          "covered": true,
          "days_supply": 30,
          "deductible_applies": false,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ]
    },
    "primary_care_visit": {
      "description": "Primary Care Visit to Treat an Injury or Illness",
      "in_network": {
        "coinsurance": 20,
        "copay": null,
        "copay_frequency": null,
        "copay_prior_to_deductible": null,
        "covered": true,
        "deductible_applies": true,
        "limit_quantity": null,
        "limit_unit": null,
        "max_oop_applies": true,
        "minimum_stay": null,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      },
      "out_of_network": {
        "coinsurance": 40,
        "copay": null,
        "copay_frequency": null,
        "copay_prior_to_deductible": null,
        "covered": true,
        "deductible_applies": true,
        "limit_quantity": null,
        "limit_unit": null,
        "max_oop_applies": true,
        "minimum_stay": null,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    },
    "specialist_visit": {
      "description": "Specialist Visit",
      "in_network": {
        "coinsurance": 20,
        "copay": null,
        "copay_frequency": null,
        "copay_prior_to_deductible": null,
        "covered": true,
        "deductible_applies": true,
        "limit_quantity": null,
        "limit_unit": null,
        "max_oop_applies": true,
        "minimum_stay": null,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      },
      "out_of_network": {
        "coinsurance": 40,
        "copay": null,
        "copay_frequency": null,
        "copay_prior_to_deductible": null,
        "covered": true,
        "deductible_applies": true,
        "limit_quantity": null,
        "limit_unit": null,
        "max_oop_applies": true,
        "minimum_stay": null,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    },
    "specialty_drugs": {
      "description": "Specialty Drugs",
      "in_network": [
        {
          "coinsurance": 20,
          "copay": null,
          "covered": true,
          "days_supply": null,
          "deductible_applies": true,
          "max_oop_applies": true,
          "min_cost_sharing": 1,
          "max_cost_sharing": 100
        }
      ]
    }
  },
  "carrier_name": "Aetna",
  "deductible": {
    "comprehensive": {
      "combined": null,
      "in_network": {
        "family": 7000,
        "individual": 3500,
        "individual_child": null,
        "individual_spouse": null
      },
      "secondary_in_network": null,
      "out_of_network": {
        "family": 14000,
        "individual": 7000,
        "individual_child": null,
        "individual_spouse": null
      }
    },
    "health_and_drug": null,
    "embedded": false
  },
  "external_id": "Aetna3500",
  "hsa_eligible": true,
  "hra_eligible": false,
  "max_oop": {
    "comprehensive": {
      "combined": null,
      "in_network": {
        "family": 11900,
        "individual": 5950,
        "individual_child": null,
        "individual_spouse": null
      },
      "secondary_in_network": null,
      "out_of_network": {
        "family": 20000,
        "individual": 10000,
        "individual_child": null,
        "individual_spouse": null
      }
    },
    "health_and_drug": null,
    "embedded": false
  },
  "name": "Aetna National 3500/80",
  "benefits_summary_url": "https://s3.amazonaws.com/picwellapppublicdata/picwell/supplemental/dental/example.pdf"
}

Properties

Name Type Required Description
external_id string true The unique identifier for this plan
health_plan_type string true The plan type provided during plan ingestion, e.g. 'HMO', 'PPO', 'HDHP'
name string true The provided display name of the plan
carrier_name string true The name of the insurance carrier for this plan
hsa_eligible boolean true Indicates whether this plan is eligible for a Health Savings Account
hra_eligible boolean true Indicates whether this plan is eligible for a Health Reimbursement Arrangement
max_oop Spending Limit Types true All maximum out-of-pocket limits for this plan, broken down by coverage type (health and drug, or combined) and then by network type (in-network, out-of-network, combined)
deductible Spending Limit Types true All deductible limits for this plan, broken down by coverage type (health and drug, or combined) and then by network type (in-network, out-of-network, combined)
benefits Benefits true Descriptions of cost-sharing and coverage for that type of coverage, for common types offered by this plan (e.g. Primary Care Visits, Specialist Visits, Prescription Drugs)
benefits_summary_url string false The link to the summary of benefits

Detailed Health Plan Response

{
  "plans": [
    {
      "benefits": {
        "generic_drugs": {
          "description": null,
          "in_network": [
            {
              "coinsurance": null,
              "copay": 10,
              "covered": true,
              "days_supply": 30,
              "deductible_applies": false,
              "max_oop_applies": true,
              "min_cost_sharing": 1,
              "max_cost_sharing": 100
            }
          ],
          "out_of_network": [
            {
              "coinsurance": 40,
              "copay": 10,
              "covered": true,
              "days_supply": 30,
              "deductible_applies": false,
              "max_oop_applies": true,
              "min_cost_sharing": 1,
              "max_cost_sharing": 100
            }
          ]
        },
        "non_preferred_brand_drugs": {
          "description": null,
          "in_network": [
            {
              "coinsurance": null,
              "copay": 60,
              "covered": true,
              "days_supply": 30,
              "deductible_applies": false,
              "max_oop_applies": true,
              "min_cost_sharing": 1,
              "max_cost_sharing": 100
            }
          ],
          "out_of_network": [
            {
              "coinsurance": 40,
              "copay": 60,
              "covered": true,
              "days_supply": 30,
              "deductible_applies": false,
              "max_oop_applies": true,
              "min_cost_sharing": 1,
              "max_cost_sharing": 100
            }
          ]
        },
        "preferred_brand_drugs": {
          "description": null,
          "in_network": [
            {
              "coinsurance": null,
              "copay": 35,
              "covered": true,
              "days_supply": 30,
              "deductible_applies": false,
              "max_oop_applies": true,
              "min_cost_sharing": 1,
              "max_cost_sharing": 100
            }
          ],
          "out_of_network": [
            {
              "coinsurance": 40,
              "copay": 35,
              "covered": true,
              "days_supply": 30,
              "deductible_applies": false,
              "max_oop_applies": true,
              "min_cost_sharing": 1,
              "max_cost_sharing": 100
            }
          ]
        },
        "primary_care_visit": {
          "description": "Primary Care Visit to Treat an Injury or Illness",
          "in_network": {
            "coinsurance": 20,
            "copay": null,
            "copay_frequency": null,
            "copay_prior_to_deductible": null,
            "covered": true,
            "deductible_applies": true,
            "limit_quantity": null,
            "limit_unit": null,
            "max_oop_applies": true,
            "minimum_stay": null,
            "min_cost_sharing": 1,
            "max_cost_sharing": 100
          },
          "out_of_network": {
            "coinsurance": 40,
            "copay": null,
            "copay_frequency": null,
            "copay_prior_to_deductible": null,
            "covered": true,
            "deductible_applies": true,
            "limit_quantity": null,
            "limit_unit": null,
            "max_oop_applies": true,
            "minimum_stay": null,
            "min_cost_sharing": 1,
            "max_cost_sharing": 100
          }
        },
        "specialist_visit": {
          "description": "Specialist Visit",
          "in_network": {
            "coinsurance": 20,
            "copay": null,
            "copay_frequency": null,
            "copay_prior_to_deductible": null,
            "covered": true,
            "deductible_applies": true,
            "limit_quantity": null,
            "limit_unit": null,
            "max_oop_applies": true,
            "minimum_stay": null,
            "min_cost_sharing": 1,
            "max_cost_sharing": 100
          },
          "out_of_network": {
            "coinsurance": 40,
            "copay": null,
            "copay_frequency": null,
            "copay_prior_to_deductible": null,
            "covered": true,
            "deductible_applies": true,
            "limit_quantity": null,
            "limit_unit": null,
            "max_oop_applies": true,
            "minimum_stay": null,
            "min_cost_sharing": 1,
            "max_cost_sharing": 100
          }
        },
        "specialty_drugs": {
          "description": null,
          "in_network": [
            {
              "coinsurance": 20,
              "copay": null,
              "covered": true,
              "days_supply": null,
              "deductible_applies": true,
              "max_oop_applies": true,
              "min_cost_sharing": 1,
              "max_cost_sharing": 100
            }
          ]
        }
      },
      "carrier_name": "Aetna",
      "deductible": {
        "comprehensive": {
          "combined": null,
          "in_network": {
            "family": 7000,
            "individual": 3500,
            "individual_child": null,
            "individual_spouse": null
          },
          "secondary_in_network": null,
          "out_of_network": {
            "family": 14000,
            "individual": 7000,
            "individual_child": null,
            "individual_spouse": null
          }
        },
        "health_and_drug": null,
        "embedded": false
      },
      "external_id": "Aetna3500",
      "health_plan_type": "HDHP",
      "hsa_eligible": true,
      "hra_eligible": false,
      "max_oop": {
        "comprehensive": {
          "combined": null,
          "in_network": {
            "family": 11900,
            "individual": 5950,
            "individual_child": null,
            "individual_spouse": null
          },
          "secondary_in_network": null,
          "out_of_network": {
            "family": 20000,
            "individual": 10000,
            "individual_child": null,
            "individual_spouse": null
          }
        },
        "health_and_drug": null,
        "embedded": false
      },
      "name": "Aetna National 3500/80"
    }
  ]
}

Properties

Name Type Required Description
plans List[Detailed Health Plan Description] true The requested plan information

Spending Limit Types

A detailed representation of a health plan's spending limits.

With comprehensive deductible

{
  "comprehensive": {
    "combined": null,
    "in_network": {
      "family": 11900,
      "individual": 5950,
      "individual_child": null,
      "individual_spouse": null
    },
    "secondary_in_network": {
      "family": 15000,
      "individual": 8000,
      "individual_child": null,
      "individual_spouse": null
    },
    "out_of_network": {
      "family": 20000,
      "individual": 10000,
      "individual_child": null,
      "individual_spouse": null
    }
  },
  "health_and_drug": null,
  "embedded": false
}

With health and drug deductible

{
  "comprehensive": null,
  "health_and_drug": {
    "health": {
      "combined": {
        "family": 11900,
        "individual": 5950,
        "individual_child": null,
        "individual_spouse": null
      },
      "in_network": null,
      "secondary_in_network": null,
      "out_of_network": null
    },
    "drug": {
      "combined": {
        "family": 11900,
        "individual": 5950,
        "individual_child": null,
        "individual_spouse": null
      },
      "in_network": null,
      "secondary_in_network": null,
      "out_of_network": null
    }
  },
  "embedded": false
}

Properties

Name Type Required Description
comprehensive Spending Limits By Network Type false A breakdown of spending limits applicable to the plan, broken down by network type, if this plan shares limits for drug and health spending.
health_and_drug object false
» health Spending Limits By Network Type true A breakdown of health spending limits applicable to the plan, broken down by network type, if this plan has separate limits for drug and health spending.
» drug Spending Limits By Network Type true A breakdown of drug spending limits applicable to the plan, broken down by network type, if this plan has separate limits for drug and health spending.
embedded boolean true Describes whether the limit is embedded (See Embedded below).

Limit types

Limits can be "comprehensive", entailing that both drug and health cost apply towards reaching the limit, or for drug costs and health costs separately. Reflecting this, either the health_and_drug field will be non-null containing health and drug values while the comprehensive field is null, or the comprehensive field will be non-null while health_and_drug is null.

Embedded

When a limit is embedded, each family member covered by the policy has a lower, individual limit after which cost sharing begins or the out of pocket limit is reached. When not embedded, there are no individual limits and the the family limit must be reached before cost sharing begins or the out of pocket limit is reached.

Spending Limits By Network Type

A detailed representation of a health plan's spending limits by network type.

{
  "combined": null,
  "in_network": {
    "family": 11900,
    "individual": 5950,
    "individual_child": null,
    "individual_spouse": null
  },
  "secondary_in_network": {
    "family": 15000,
    "individual": 8000,
    "individual_child": null,
    "individual_spouse": null
  },
  "out_of_network": {
    "family": 20000,
    "individual": 10000,
    "individual_child": null,
    "individual_spouse": null
  }
}

Properties

Name Type Required Description
combined Spending Limits By Coverage Tier false A breakdown of spending limits for combined costs applicable to the plan, broken down by coverage tier.
in_network Spending Limits By Coverage Tier false A breakdown of spending limits for in-network costs applicable to the plan, broken down by coverage tier.
secondary_in_network Spending Limits By Coverage Tier false A breakdown of spending limits for secondary in-network costs applicable to the plan, broken down by coverage tier.
out_of_network Spending Limits By Coverage Tier false A breakdown of out-of-network costs applicable to the plan, broken down by coverage tier.

Spending Limits By Coverage Tier

A detailed representation of a health plan's spending limits by coverage tier.

{
  "family": 11900,
  "individual": 5950,
  "individual_child": null,
  "individual_spouse": null
}

Properties

Name Type Required Description
family integer false The amount, in dollars, that a family would have to spend in a year before the next level of cost sharing applies or the out-of-pocket limit is reached, if the limit is embedded.
individual integer false The amount, in dollars, that an individual in this household would have to spend in a year before the next level of cost sharing applies or the out-of-pocket limit is reached, if the limit is embedded.
individual_child integer false The amount, in dollars, that a family consisting of an individual and a child (or children) in this household would have to spend in a year before the next level of cost sharing applies or the out-of-pocket limit is reached, if the limit is embedded.
individual_spouse integer false The amount, in dollars, that a family consisting of an individual and their spouse in this household would have to spend in a year before the next level of cost sharing applies or the out-of-pocket limit is reached, if the limit is embedded.

Null values

A value of null implies that the spending limit does not exist. This is meaningful only in the case of maxium out-of-pocket limits, where a null values implies that there is no out-of-pocket limit and so spending is not capped at any point.

Embedded

See Embedded for more information.

Benefits

A detailed representation of a health plan's cost-sharing and coverage for each type of coverage offered by this plan.

{
  "generic_drugs": {
    "description": "Generic Drugs",
    "in_network": [
      {
        "coinsurance": null,
        "copay": 10,
        "covered": true,
        "days_supply": 30,
        "deductible_applies": false,
        "max_oop_applies": true,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    ],
    "secondary_in_network": [
      {
        "coinsurance": null,
        "copay": 15,
        "covered": true,
        "days_supply": 30,
        "deductible_applies": false,
        "max_oop_applies": true,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    ],
    "out_of_network": [
      {
        "coinsurance": 40,
        "copay": 10,
        "covered": true,
        "days_supply": 30,
        "deductible_applies": false,
        "max_oop_applies": true,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    ]
  },
  "non_preferred_brand_drugs": {
    "description": "Non-Preferred Brand Drugs",
    "in_network": [
      {
        "coinsurance": null,
        "copay": 60,
        "covered": true,
        "days_supply": 30,
        "deductible_applies": false,
        "max_oop_applies": true,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    ],
    "secondary_in_network": [
      {
        "coinsurance": null,
        "copay": 15,
        "covered": true,
        "days_supply": 30,
        "deductible_applies": false,
        "max_oop_applies": true,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    ],
    "out_of_network": [
      {
        "coinsurance": 40,
        "copay": 60,
        "covered": true,
        "days_supply": 30,
        "deductible_applies": false,
        "max_oop_applies": true,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    ]
  },
  "preferred_brand_drugs": {
    "description": "Preferred Brand Drugs",
    "in_network": [
      {
        "coinsurance": null,
        "copay": 35,
        "covered": true,
        "days_supply": 30,
        "deductible_applies": false,
        "max_oop_applies": true,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    ],
    "secondary_in_network": [
      {
        "coinsurance": null,
        "copay": 15,
        "covered": true,
        "days_supply": 30,
        "deductible_applies": false,
        "max_oop_applies": true,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    ],
    "out_of_network": [
      {
        "coinsurance": 40,
        "copay": 35,
        "covered": true,
        "days_supply": 30,
        "deductible_applies": false,
        "max_oop_applies": true,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    ]
  },
  "primary_care_visit": {
    "description": "Primary Care Visit to Treat an Injury or Illness",
    "in_network": {
      "coinsurance": 20,
      "copay": null,
      "copay_frequency": null,
      "copay_prior_to_deductible": null,
      "covered": true,
      "deductible_applies": true,
      "limit_quantity": null,
      "limit_unit": null,
      "max_oop_applies": true,
      "minimum_stay": null,
      "min_cost_sharing": 1,
      "max_cost_sharing": 100
    },
    "secondary_in_network": [
      {
        "coinsurance": null,
        "copay": 15,
        "covered": true,
        "days_supply": 30,
        "deductible_applies": false,
        "max_oop_applies": true,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    ],
    "out_of_network": {
      "coinsurance": 40,
      "copay": null,
      "copay_frequency": null,
      "copay_prior_to_deductible": null,
      "covered": true,
      "deductible_applies": true,
      "limit_quantity": null,
      "limit_unit": null,
      "max_oop_applies": true,
      "minimum_stay": null,
      "min_cost_sharing": 1,
      "max_cost_sharing": 100
    }
  },
  "specialist_visit": {
    "description": "Specialist Visit",
    "in_network": {
      "coinsurance": 20,
      "copay": null,
      "copay_frequency": null,
      "copay_prior_to_deductible": null,
      "covered": true,
      "deductible_applies": true,
      "limit_quantity": null,
      "limit_unit": null,
      "max_oop_applies": true,
      "minimum_stay": null,
      "min_cost_sharing": 1,
      "max_cost_sharing": 100
    },
    "secondary_in_network": [
      {
        "coinsurance": null,
        "copay": 15,
        "covered": true,
        "days_supply": 30,
        "deductible_applies": false,
        "max_oop_applies": true,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    ],
    "out_of_network": {
      "coinsurance": 40,
      "copay": null,
      "copay_frequency": null,
      "copay_prior_to_deductible": null,
      "covered": true,
      "deductible_applies": true,
      "limit_quantity": null,
      "limit_unit": null,
      "max_oop_applies": true,
      "minimum_stay": null,
      "min_cost_sharing": 1,
      "max_cost_sharing": 100
    }
  },
  "specialty_drugs": {
    "description": "Specialty Drugs",
    "in_network": [
      {
        "coinsurance": 20,
        "copay": null,
        "covered": true,
        "days_supply": null,
        "deductible_applies": true,
        "max_oop_applies": true,
        "min_cost_sharing": 1,
        "max_cost_sharing": 100
      }
    ]
  }
}

Properties

Name Type Required Description
primary_care_visit Health Cost Sharing By Network true Cost-sharing details for Primary Care visits under this plan
specialist_visit Health Cost Sharing By Network true Cost-sharing details for Specialist visits under this plan
generic_drugs Drug Cost Sharing By Network true Cost-sharing details for generic drugs under this plan
preferred_brand_drugs Drug Cost Sharing By Network true Cost-sharing details for preferred brand-name drugs under this plan
non_preferred_brand_drugs Drug Cost Sharing By Network true Cost-sharing details for non-preferred brand-name drugs under this plan
specialty_drugs Drug Cost Sharing By Network true Cost-sharing details for specialty drugs under this plan

Health Cost Sharing By Network

A detailed representation of a health plan's cost sharing for one of its offered health benefits, broken down by network.

{
  "description": "Specialist Visit",
  "in_network": {
    "coinsurance": 20,
    "copay": null,
    "copay_frequency": null,
    "copay_prior_to_deductible": null,
    "covered": true,
    "deductible_applies": true,
    "limit_quantity": null,
    "limit_unit": null,
    "max_oop_applies": true,
    "minimum_stay": null,
    "min_cost_sharing": 1,
    "max_cost_sharing": 100
  },
  "secondary_in_network": {
    "coinsurance": 30,
    "copay": null,
    "copay_frequency": null,
    "copay_prior_to_deductible": null,
    "covered": true,
    "deductible_applies": true,
    "limit_quantity": null,
    "limit_unit": null,
    "max_oop_applies": true,
    "minimum_stay": null,
    "min_cost_sharing": 1,
    "max_cost_sharing": 100
  },
  "out_of_network": {
    "coinsurance": 40,
    "copay": null,
    "copay_frequency": null,
    "copay_prior_to_deductible": null,
    "covered": true,
    "deductible_applies": true,
    "limit_quantity": null,
    "limit_unit": null,
    "max_oop_applies": true,
    "minimum_stay": null,
    "min_cost_sharing": 1,
    "max_cost_sharing": 100
  }
}

Properties

Name Type Required Description
description string true A description of the type of coverage to which these cost-sharing values apply.
in_network Health Cost Sharing true Details of in-network health benefit cost sharing for this plan.
secondary_in_network Health Cost Sharing false Details of secondary in-network health benefit cost sharing for this plan.
out_of_network Health Cost Sharing false Details of out-of-network health benefit cost sharing for this plan.

Health Cost Sharing

The details of this plan's cost-sharing, such as co-insurance, copays, and any applicable limits or constraints.

{
  "coinsurance": 20,
  "copay": null,
  "copay_frequency": null,
  "copay_prior_to_deductible": null,
  "covered": true,
  "deductible_applies": true,
  "limit_quantity": null,
  "limit_unit": null,
  "max_oop_applies": true,
  "minimum_stay": null,
  "min_cost_sharing": 1,
  "max_cost_sharing": 100
}

Properties

Name Type Required Description
covered boolean true Describes whether this benefit is covered for this type of network coverage.
coinsurance integer false The percentage of a medical claim's costs that a household member pays after meeting the plan's deductible. Will be null if this plan does not use coinsurance for this type of network coverage.
copay integer false The dollar amount that a household member pays, depending on copay_frequency, after meeting the plan's deductible. Will be null if this plan does not use copays for this type of network coverage.
copay_frequency string false One of per_admission, per_visit, per_day, per_year
copay_prior_to_deductible boolean false Describes whether the copay is applied before the deductible is met.
deductible_applies boolean false Describes whether the deductible applies to this benefit.
limit_quantity integer false If present, describes the quantity of any limit that may apply to this benefit
limit_unit string false If present, describes the type of any limit that may apply to this benefit, e.g. "per day", "dollars", "claims".
max_oop_applies boolean false Describes whether spending for this benefit applies towards the maximum out-of-pocket limit for this plan.
minimum_stay integer false If present, describes the minimum inpatient stay for cost sharing to apply to claims for this benefit.
min_cost_sharing integer false Minimum cost sharing to apply to claims for this benefit. If present, this value is the minimum a user will pay for claim that has a coinsurance.
max_cost_sharing integer false Maximum cost sharing to apply to claims for this benefit. If present, this value is the maximum a user will pay for claim that has a coinsurance.

Drug Cost Sharing By Network

A detailed representation of a health plan's cost sharing for one of its offered drug benefits, broken down by network.

{
  "description": "Generic Drugs",
  "in_network": [
    {
      "coinsurance": null,
      "copay": 10,
      "covered": true,
      "days_supply": 30,
      "deductible_applies": false,
      "max_oop_applies": true,
      "min_cost_sharing": 1,
      "max_cost_sharing": 100
    }
  ],
  "secondary_in_network": [
    {
      "coinsurance": null,
      "copay": 10,
      "covered": true,
      "days_supply": 30,
      "deductible_applies": false,
      "max_oop_applies": true,
      "min_cost_sharing": 1,
      "max_cost_sharing": 100
    }
  ],
  "out_of_network": [
    {
      "coinsurance": 40,
      "copay": 10,
      "covered": true,
      "days_supply": 30,
      "deductible_applies": false,
      "max_oop_applies": true,
      "min_cost_sharing": 1,
      "max_cost_sharing": 100
    }
  ]
}

Properties

Name Type Required Description
description string true A description of the type of coverage to which these cost-sharing values apply.
in_network List[Drug Cost Sharing] true Details of in-network drug benefit cost sharing for this plan.
secondary_in_network List[Drug Cost Sharing] true Details of secondary in-network drug benefit cost sharing for this plan.
out_of_network List[Drug Cost Sharing] false Details of out-of-network drug benefit cost sharing for this plan.

Drug Cost Sharing

The details of this plan's cost-sharing for a drug benefit, such as co-insurance, copays, and any applicable limits or constraints.

{
  "coinsurance": 20,
  "copay": 25,
  "covered": true,
  "days_supply": 30,
  "deductible_applies": true,
  "max_oop_applies": true,
  "min_cost_sharing": 1,
  "max_cost_sharing": 100
}

Properties

Name Type Required Description
covered boolean true Describes whether this benefit is covered for this type of network coverage.
coinsurance integer false The percentage of a medical claim's costs that a household member pays after meeting the plan's deductible. Will be null if this plan does not use coinsurance for this type of network coverage.
copay integer false The dollar amount that a household member pays after meeting the plan's deductible. Will be null if this plan does not use copays for this type of network coverage.
days_supply boolean false The number of days a filled drug is supplied for.
deductible_applies boolean false Describes whether the deductible applies to this benefit.
max_oop_applies boolean false Describes whether spending for this benefit applies towards the maximum out-of-pocket limit for this plan.
min_cost_sharing integer false Minimum cost sharing to apply to claims for this benefit. If present, this value is the minimum a user will pay for claim that has a coinsurance.
max_cost_sharing integer false Maximum cost sharing to apply to claims for this benefit. If present, this value is the maximum a user will pay for claim that has a coinsurance.

Prescription

{
  "ndc": "string",
  "quantity": 0,
  "frequency": 0
}

Properties

Name Type Required Restrictions Description
ndc string true Must be numeric 11 digit NDC, with leading zeroes if applicable.
quantity integer false none Numeric quantity of drug. Currently unused. If not specified, defaults to 0.
frequency integer false none Days between refills. Currently unused. If not specified, defaults to 0.

Utilization

The previous year's utilization of medical services.

{
  "inpatient_days": 1,
  "specialist_visits": 1,
  "pcp_visits": 2
}

Properties

Name Type Required Description
inpatient_days integer true The previous year's number of days spent in inpatient hospital visits
specialist_visits integer true The previous year's number of visits to a specialist
pcp_visits integer true The previous year's number of visits to a primary care physician

Planned Procedures

Planned procedures in the upcoming year.

{
  "inpatient_procedures": 1,
  "outpatient_procedures": 2,
  "therapy_visits": 3,
  "mental_health_visits": 4
}

Properties

Name Type Required Description
inpatient_procedures integer true Next year's planned number of days spent in inpatient hospital visits
outpatient_procedures integer true Next year's planned number of days spent in outpatient hospital visits
therapy_visits integer true Next year's planned number of days spent in therapy hospital visits
mental_health_visits integer true Next year's planned number of days spent in mental health hospital
visits

Survey Answer

A single response to a survey question.

{
  "question_id": "1",
  "answer": "very_important"
}

Properties

Name Type Required Description
question_id string true A question identifier
answer string true Answer selection
condition_answer Condition Answer false Selected responses to the medical condition question

Discussion

Client Survey Answers

An object representing responses to some or all client survey questions.

{
  "is_j1_visa": "Yes",
  "is_full_time_or_part_time": "Full-Time"
}

Properties

The Client Survey Answers object is a dictionary whose keys and values are dynamic based on the list of questions and answers as described in the Client Survey.

Name Type Required Description
<question_property_name> string true The name of the client survey question, corresponding to a property in the Client Survey
<answer> varies, depending on type of question true The answer to the client survey question

Client Survey Response

A JSON Schema document describing questions and potential answers to client-specific surveys, used for implementing organization-specific business rules when making Recommendations.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "properties": {
    "is_full_time_or_part_time": {
      "description": "Are you full-time or part-time?",
      "enum": ["Full-Time", "Part-Time"],
      "type": "string"
    },
    "is_j1_visa": {
      "description": "Are you here on a J-1 Visa?",
      "enum": ["No", "Yes"],
      "type": "string"
    }
  },
  "type": "object"
}

Discussion

Condition Answer

An object containing the collection of answers to the medical conditions question for you, your spouse, and your children (when applicable).

{
  "you": {
    "id": "you_external_id",
    "back_pain": true,
    "sinusitis": true
  },
  "spouse": {
    "id": "spouse_external_id",
    "prefer_no_answer": true
  },
  "child": {
    "id": "child_external_id",
    "allergies": true
  }
}

Properties

Name Type Required
you User Condition true
spouse User Condition false
child User Condition false

User Condition

An object containing answers to the medical conditions question for a given user

{
  "id": "user_external_id",
  "back_pain": true,
  "sinusitis": true
}

Properties

Name Type Required Default Description
id string true n/a ID of the individual
allergies boolean false false Whether the user has allergies
arthritis boolean false false Whether the user has arthritis
back_pain boolean false false Whether the user has back pain
cancer boolean false false Whether the user has cancer
congestive_heart_failure boolean false false Whether the user has congestive heart failure
coronary_artery_disease boolean false false Whether the user has coronary artery disease
depression boolean false false Whether the user has depression
diabetes boolean false false Whether the user has diabetes
high_cholesterol boolean false false Whether the user has high cholesterol
hypertension boolean false false Whether the user has hypertension
kidney_disease boolean false false Whether the user has kidney disease
lung_disease boolean false false Whether the user has lung disease
obesity boolean false false Whether the user has obesity
sinusitis boolean false false Whether the user has sinusitis
not_applicable boolean false false Indicates that the user has no applicable conditions
prefer_no_answer boolean false false Indicates that the user has preferred not to answer

Health Recommendation Request

A payload sent for requesting health recommendations for a set of plans. Note: plans and plan_selection_id are mutually exclusive, additional_plans are used in addition to plans or plan_selection_id.

{
  "plans": [
    {
      "external_id": "health_plan_1",
      "premiums": {
        "employee_contribution": 50,
        "employer_contribution": 50
      }
    },
    {
      "external_id": "health_plan_2",
      "premiums": {
        "employee_contribution": 50,
        "employer_contribution": 50
      }
    }
  ],
  "plan_selection_id": "my_plan_selection",
  "member_ids": ["policyholder-id", "spouse-id"]
}

Properties

Name Type Required Description
plans List[Health Recommendations Request Health Plan] false Plans to consider.

Omitting this field requires static or household driven eligibility. See Premiums and Eligibility for more details.

Providing multiple plans with the same external ID will result in a 400 Bad Request error.

Cannot be used if plan_selection_id is provided.
additional_plans List[Health Recommendations Request Health Plan] false Custom plans to consider.

Providing multiple plans with the same external ID will result in a 400 Bad Request error.

Providing plans here will override any plans with the same external_id.
plan_selection_id string false The ID of the Eligibility Set to use for premiums, eligibility, and HSA contributions for this recommendation, if desired.

Cannot be used if plans is provided.

This property is mainly intended for use in the BenAdmin Integration
member_ids List[string] false List of external_ids denoting which Household members you wish to include in the recommendation. Can be used in conjunction with plans or plan_selection_id.

If not provided, the recommendation will consider the entire household.

If member_ids are provided, the external_id of the Household's policyholder must be included in the list.

This property is mainly intended for use in the BenAdmin Integration

Health Recommendation Response

{
  "recommendations": [
    {
      "costs": {
        "annual_fsa_dollars_used": 0,
        "annual_hra_dollars_used": 0,
        "annual_hra_employer_dollars_used": 0,
        "annual_hsa_dollars_used": 0,
        "annual_hsa_employer_dollars_used": 0,
        "annual_hsa_tax_savings": 0,
        "annual_sihra_dollars_used": 0,
        "annual_tax_benefit": 0,
        "drugs": 0,
        "effective_premium": 50,
        "real_cost": 1050.0,
        "worst_case_scenario_cost": 9600.0,
        "services": {
          "in_network": 1000.0
        },
        "spending_account_balance_increase": 0,
        "spending_account_benefit": 0
      },
      "tax_rates": {
        "federal": 0.37
      },
      "plan_details": {
        "deductible": {
          "comprehensive": null,
          "health_and_drug": {
            "drug": {
              "combined": null,
              "in_network": {
                "embedded_per_person": null,
                "total": 150.0
              },
              "out_of_network": {
                "embedded_per_person": null,
                "total": 150.0
              },
              "secondary_in_network": null
            },
            "health": {
              "combined": null,
              "in_network": {
                "embedded_per_person": null,
                "total": 1250.0
              },
              "secondary_in_network": null,
              "out_of_network": {
                "embedded_per_person": null,
                "total": 4500.0
              }
            }
          }
        },
        "max_oop": {
          "comprehensive": {
            "combined": null,
            "in_network": {
              "embedded_per_person": null,
              "total": 3500.0
            },
            "secondary_in_network": null,
            "out_of_network": {
              "embedded_per_person": null,
              "total": 31500.0
            }
          },
          "health_and_drug": null
        }
      },
      "health_provider_locations": [],
      "plan": {
        "external_id": "health_plan_1",
        "id": "health_plan_1"
      },
      "score": 95,
      "tier": "green"
    },
    {
      "costs": {
        "annual_fsa_dollars_used": 0,
        "annual_hra_dollars_used": 0,
        "annual_hra_employer_dollars_used": 0,
        "annual_hsa_dollars_used": 0,
        "annual_hsa_employer_dollars_used": 0,
        "annual_hsa_tax_savings": 0,
        "annual_sihra_dollars_used": 0,
        "annual_tax_benefit": 0,
        "drugs": 0,
        "effective_premium": 100,
        "real_cost": 2100.0,
        "worst_case_scenario_cost": 9600.0,
        "services": {
          "in_network": 2000.0
        },
        "spending_account_balance_increase": 0,
        "spending_account_benefit": 0
      },
      "tax_rates": {
        "federal": 0.37
      },
      "plan_details": {
        "deductible": {
          "comprehensive": null,
          "health_and_drug": {
            "drug": {
              "combined": null,
              "in_network": {
                "embedded_per_person": null,
                "total": 150.0
              },
              "out_of_network": {
                "embedded_per_person": null,
                "total": 150.0
              },
              "secondary_in_network": null
            },
            "health": {
              "combined": null,
              "in_network": {
                "embedded_per_person": null,
                "total": 1250.0
              },
              "secondary_in_network": null,
              "out_of_network": {
                "embedded_per_person": null,
                "total": 4500.0
              }
            }
          }
        },
        "max_oop": {
          "comprehensive": {
            "combined": null,
            "in_network": {
              "embedded_per_person": null,
              "total": 3500.0
            },
            "secondary_in_network": null,
            "out_of_network": {
              "embedded_per_person": null,
              "total": 31500.0
            }
          },
          "health_and_drug": null
        }
      },
      "health_provider_locations": [],
      "plan": {
        "external_id": "health_plan_2",
        "id": "health_plan_2"
      },
      "score": 55,
      "tier": "red"
    }
  ]
}

Properties

Name Type Required Description
recommendations List[Recommendation] true
errors List[Error] false Optional list of any request errors committed

Discussion

The costs.spending_account_benefit and costs.spending_account_balance_increase fields currently provide an aggregate of a variety of spending account benefits, not just HSAs. If you are interested in strictly recommended HSA contribution amounts and their associated tax benefits, please refer to the HSA endpoint.

With /hsa/ you can retrieve these values on a per-plan, per-household basis.

Unrecognized external IDs

In situations where Picwell is unable to map to a plan.external_id field, the API will return the unknown external IDs in the error section and omit the unknown plans from the recommendation response.

A&V Recommendation Request

A payload sent for requesting recommendations for a given set of health and A&V plans.

{
  "packages": [["health", "hi"], ["health"]],
  "plans": [
    {
      "plan_type": "health",
      "external_id": "health_plan_1",
      "premiums": {}
    },
    {
      "plan_type": "hi",
      "external_id": "hospital_indemnity_plan_1",
      "premiums": {}
    },
    {
      "plan_type": "hi",
      "external_id": "hospital_indemnity_plan_2",
      "premiums": {}
    }
  ]
}

Properties

Name Type Required Description
packages List[List[string]] true A list of lists, where each contain the set of applicable plan_types for a given package.
plans object true Plans to consider
» health List[A&V Recommendation Request A&V Plan] false Health plans
» hi List[A&V Recommendation Request A&V Plan] false Hospital Indemnity plans
» ci List[A&V Recommendation Request A&V Plan] false Critical Illness plans
» acc List[A&V Recommendation Request A&V Plan] false Accident plans

A&V Recommendation Response

{
  "packages": [
    {
      "ceq": 1000.33,
      "plan_types": ["health", "hi"],
      "plans": {
        "health": {
          "external_id": "health_plan_1"
        },
        "hi": {
          "external_id": "hospital_indemnity_plan_1"
        }
      },
      "premium": 0,
      "real_cost": 2154.966273333334
    },
    {
      "ceq": 1200.86,
      "plan_types": ["health", "hi"],
      "plans": {
        "health": {
          "external_id": "health_plan_1"
        },
        "hi": {
          "external_id": "hospital_indemnity_plan_2"
        }
      },
      "premium": 0,
      "real_cost": 2155.0162733333336
    },
    {
      "ceq": 800.56,
      "plan_types": ["health"],
      "plans": {
        "health": {
          "external_id": "health_plan_1"
        }
      },
      "premium": 0,
      "real_cost": 1191.966273333335
    }
  ]
}

Properties

Name Type Required Description
packages List[Package] true Packages of the requested types containing all valid plan combinations thereof, ranked by CEQ
errors [object] false Contains descriptions of errors that occurred while processing the request, if any.

Discussion

Unrecognized external IDs

In situations where Picwell is unable to map to a plan.external_id field, the API will return the unknown external IDs in the error section and omit the unknown plans from the recommendation response.

HSA Plan Data

{
  "external_id": "0123_12431_2021",
  "spending_account_contribution": 100.0,
  "member_ids": ["policyholder-id", "spouse-id"]
}

Plan data for HSA-related requests.

Name Type Required Description
external_id string true The unique identifier for the plan
spending_account_contribution float false The monthly employer contribution to a spending account from the plan. This is combined with the contribution defined on the household if the contribution defined on the household is fixed. If the contribution defined on the household is a percentage match, this field is ignored.
member_ids List[string] false List of external_ids denoting which Household members you wish to include in the HSA recommendation.

If not provided, the HSA recommendation will consider the entire household.

If member_ids are provided, the external_id of the Household's policyholder must be included in the list.

HSA Recommendation Response

{
  "employer_contribution": 300.0,
  "employer_contribution_deciles": [
    300.0, 300.0, 300.0, 300.0, 300.0, 300.0, 300.0, 300.0, 300.0, 300.0, 300.0
  ],
  "hsa_benefit": 713.1839176661636,
  "hsa_benefit_deciles": [
    300.0, 300.0, 300.0, 344.9306735753909, 416.50436396101725,
    509.2799262692803, 626.1487782167769, 800.3378432939336, 991.9353041375997,
    1186.6287342883284, 1774.0
  ],
  "oop": 2178.10871666438,
  "oop_deciles": [
    0, 66.08153092887338, 249.69340277216497, 504.2303344335952,
    829.5652907318965, 1251.2723921330924, 1782.4944464398948,
    2574.2629240633346, 3445.160473352726, 4330.130610401493, 9115.929340023968
  ],
  "recommended_contribution": 1878.1087166643802,
  "recommended_contribution_deciles": [
    0, 0, 0, 204.2303344335952, 529.5652907318965, 951.2723921330924,
    1482.4944464398948, 2274.2629240633346, 3145.160473352726,
    4030.130610401493, 6700.0
  ],
  "tax_benefit": 413.1839176661636,
  "tax_benefit_deciles": [
    0.0, 0.0, 0.0, 44.93067357539095, 116.50436396101723, 209.2799262692803,
    326.14877821677686, 500.3378432939336, 691.9353041375997, 886.6287342883285,
    1474.0
  ]
}

A set of recommendations for HSA.

Name Type Description
oop float The mean annual expected out-of-pocket cost before tax benefits or employer contributions are accounted for.
employer_contribution float The annual employer contribution. This is 12 * the spending_account_contribution derived from the household and the request.
hsa_benefit float The annual financial benefit to the user for the mean oop. This is the tax amount saved due to the user's contribution to the HSA combined with either the flat employer contribution amount or the out-of-pocket cost (whichever is lower).
recommended_contribution float The annual recommended user contribution for the mean oop.
tax_benefit float The annual tax benefits to the user for the mean oop.
oop_deciles List[float] The annual expected out-of-pocket costs before tax benefits or employer contributions are accounted for.
employer_contribution_deciles List[float] The annual employer contributions. This is 12 * the spending_account_contribution derived from the household and the request corresponding to each cost in oop_deciles.
hsa_benefit_deciles List[float] The annual financial benefits to the user corresponding to each cost in oop_deciles. This is the tax amount saved due to the user's contribution to the HSA combined with either the flat employer contribution amount or the out-of-pocket cost (whichever is lower).
recommended_contribution_deciles List[float] The annual recommended contribution amount corresponding to each cost in oop_deciles.
tax_benefit_deciles List[float] The annual tax benefits to the user corresponding to each cost in oop_deciles.

Package

A recommended package of plans.

{
  "ceq": 0,
  "plan_types": ["hi", "health"],
  "plans": [
    {
      "hi": {
        "external_id": "12345"
      },
      "health": {
        "external_id": "23456"
      }
    }
  ],
  "premium": 0,
  "real_cost": 0
}

Properties

Name Type Required Description
ceq float true Certainty Equivalent for this plan
plan_types List[object] true List of plan types included in this package
plans List[object] true Map from plan_type to plan external_id for each plan_type in plan_types above
premium float true Premium for this plan
real_cost float true Picwell's best estimate of the user's expected annual out-of-pocket costs under this plan package

Health Recommendations Request Health Plan

HSA Contributions

{
  "premiums": {
    "employee_contribution": 100,
    "employer_contribution": 100
  },
  "hsa_contributions": {
    "monthly_employee_contribution": 50,
    "monthly_employer_contribution": 50
  },
  "external_id": "12345"
}

HRA Contributions

{
  "premiums": {
    "employee_contribution": 100,
    "employer_contribution": 100
  },
  "hra_contributions": {
    "monthly_employer_contribution": 50
  },
  "external_id": "12345"
}

FSA Contributions

{
  "premiums": {
    "employee_contribution": 100,
    "employer_contribution": 100
  },
  "fsa_contributions": {
    "monthly_employee_contribution": 50,
    "monthly_employer_contribution": 50
  },
  "external_id": "12345"
}

Properties

Name Type Required Description
health_provider_locations object false
» in_network List[Health Provider Location] false
» out_of_network List[Health Provider Location] false
external_id string true Unique identifier for the plan
premiums object false See Premiums below
» employee_contribution float true Monthly premium contributed by employer
» employer_contribution float true Monthly premium contributed by employee
hsa_contributions object false
» monthly_employee_contribution float false Monthly amount contributed by employee to an HSA plan to override Picwell's determination of the recommended contribution. Ignored if set on a non-HSA eligible plan.
» monthly_employer_contribution float false Monthly amount contributed by employer to an HSA plan. Ignored if set on a non-HSA eligible plan.
hra_contributions object false
» monthly_employer_contribution float false Monthly amount contributed by employer to an HRA plan. Ignored if set on a non-HRA eligible plan.
fsa_contributions object false
» monthly_employee_contribution float false Monthly amount contributed by employee to an FSA plan. Ignored if set on a non-FSA eligible plan.
» monthly_employer_contribution float false Monthly amount contributed by employer to an FSA plan. Ignored if set on a non-FSA eligible plan.
spending_account_contribution float false Deprecated in favor of specifying hsa_contributions, hra_contributions, or fsa_contributions. Monthly employer contribution to a spending account from the plan.

Health Savings/Expense Accounts

Specifying multiple savings/expense accounts are not supported. A 400 response will be returned if more than one of hsa_contributions, hra_contributions or fsa_contributions contain non-zero contribution amounts.

Premiums

Premiums may be provided to Picwell during the plan intake process or specified in the request. If premiums are not specified in the request, i.e. premiums=null, Picwell will use the values provided during plan intake. Premiums provided in the request will override premiums provided during plan intake.

If specifying premiums in the request, both employee and employer premium contributions must be specified.

If premiums were not given during plan intake, premiums must be sent in the request. Otherwise, a 400 response will be returned.

See Premiums and Eligibility for more details.

A&V Recommendation Request A&V Plan

{
  "premiums": {
    "employee_contribution": 25,
    "employer_contribution": 100
  },
  "external_id": "12345",
  "plan_type": "hi"
}

Properties

Name Type Required Restrictions Description
premiums object true none Description of employee/employer contributions to the costs of this plan
» employee_contribution integer true none Dollar amount contributed by the employee
» employer_contribution integer false none Dollar amount contributed by the employer
external_id List[Health Provider Location] true none Description of in-network Health Provider Location.
plan_type string true none The plan type for this plan (see below)

Plan Types

The following are the plan types currently supported by the API:

Recommendation

{
  "costs": {
    "annual_fsa_dollars_used": 0,
    "annual_hra_dollars_used": 0,
    "annual_hra_employer_dollars_used": 0,
    "annual_hsa_dollars_used": 0,
    "annual_hsa_employer_dollars_used": 0,
    "annual_hsa_tax_savings": 0,
    "annual_sihra_dollars_used": 0,
    "annual_tax_benefit": 0,
    "drugs": 0,
    "effective_premium": 50,
    "real_cost": 1050.0,
    "worst_case_scenario_cost": 9600.0,
    "services": {
      "in_network": 1000.0
    },
    "spending_account_balance_increase": 0,
    "spending_account_benefit": 0
  },
  "health_provider_locations": [],
  "plan": {
    "external_id": "health_plan_1",
    "id": "health_plan_1"
  },
  "score": 95,
  "tier": "green"
}

Properties

Name Type Required Description
costs Recommendation Costs true Costs of drugs, effective premium, real cost, services (in- and out-of-network), and spending account data
health_provider_locations List[object] false
» in_network List[Health Provider Location] true The providers in-network for this plan
» out_of_network List[Health Provider Location] true The providers out-of-network for this plan
plan List[object] true
» external_id string true Unique client-specific ID for this plan
» id string true Unique ID for this plan
score integer true The relative Picwell Score value when comparing this plan against other plans
tier string true Picwell color tier, one of “red”, “green”, “yellow”
tax_rates Tax Rates true Picwell color tier, one of “red”, “green”, “yellow”
plan_details Plan Details true Subset of plan details for extra recommendation context

Recommendation Costs

{
  "annual_fsa_dollars_used": 254.4,
  "annual_hra_dollars_used": 0,
  "annual_hra_employer_dollars_used": 0,
  "annual_hsa_dollars_used": 0,
  "annual_hsa_employer_dollars_used": 0,
  "annual_hsa_tax_savings": 0,
  "annual_sihra_dollars_used": 0,
  "annual_tax_benefit": 14.4,
  "drugs": 221.71,
  "effective_premium": 50.0,
  "real_cost": 4226.57,
  "worst_case_scenario_cost": 9600.0,
  "services": {
    "in_network": 3659.26
  },
  "spending_account_balance_increase": 0,
  "spending_account_benefit": 254.4
}

Properties

Name Type Description
real_cost float Expected cost to the consumer including plan premiums and any spending account benefits.
worst_case_scenario_cost float Maximum cost to the consumer including plan premiums, employer spending account contributions, and hitting the plans OOP max.
effective_premium float The employee's contribution to health premiums.
services object -
» in_network object Expected out-of-pocket costs for in_network health services.
drugs float Expected out-of-pocket costs for drugs.
annual_hsa_dollars_used float Dollars you gained by specifying employee and/or employer contributions. Or more strictly, the taxable benefit of employee contributions plus dollars contributed by your employer.
annual_hsa_tax_savings float Taxable benefit of employee contributions.
annual_hsa_employer_dollars_used float Dollars contributed by your employer up to the annual HSA limit.
annual_hra_dollars_used float Dollars used by your available HRA funds, capped by out-of-pocket costs.
annual_hra_employer_dollars_used float Same as annual_hra_dollars_used.
annual_fsa_dollars_used float For employee contributions, this is the taxable benefit of contributed and used dollars.

If there are employer contributions, this is dollars contributed to the FSA, capped by out-of-pocket, in addition to any taxable benefit from employee contributions.

Dollars exceeding out-of-pocket are not considered a benefit due to the "use it or lose it" nature of FSAs.
annual_fsa_tax_savings float Taxable benefit of employee contributions.
annual_sihra_dollars_used float Your out-of-pocket costs or the SIHRA max, whichever is lower.
annual_tax_benefit float Same as either annual_hsa_tax_savings or annual_fsa_tax_savings, depending on plan eligibility.
spending_account_benefit float The "free money" you receive for your specified employee and employer contributions, taking into account your expenses and taxable benefits.
spending_account_balance_increase float Excess dollars in your HSA after taking this year's out-of-pocket costs.

Tax Rates

{
  "federal": 0.37
}

Properties

Name Type Required Description
federal float true Federal tax rate

Plan Details

{
  "deductible": {
    "comprehensive": null,
    "health_and_drug": {
      "drug": {
        "combined": null,
        "in_network": {
          "embedded_per_person": null,
          "total": 150.0
        },
        "out_of_network": {
          "embedded_per_person": null,
          "total": 150.0
        },
        "secondary_in_network": null
      },
      "health": {
        "combined": null,
        "in_network": {
          "embedded_per_person": null,
          "total": 1250.0
        },
        "secondary_in_network": null,
        "out_of_network": {
          "embedded_per_person": null,
          "total": 4500.0
        }
      }
    }
  },
  "max_oop": {
    "comprehensive": {
      "combined": null,
      "in_network": {
        "embedded_per_person": null,
        "total": 3500.0
      },
      "secondary_in_network": null,
      "out_of_network": {
        "embedded_per_person": null,
        "total": 31500.0
      }
    },
    "health_and_drug": null
  }
}

Properties

Name Type Required Description
max_oop Effective Spending Limit Types true Effective max_oop value for household
deductible Effective Spending Limit Types true Effective deductible value for household

Effective Spending Limit Types

{
  "comprehensive": {
    "combined": null,
    "in_network": {
      "embedded_per_person": null,
      "total": 3500.0
    },
    "secondary_in_network": null,
    "out_of_network": {
      "embedded_per_person": null,
      "total": 31500.0
    }
  },
  "health_and_drug": {
    "health": {
      "combined": null,
      "in_network": {
        "embedded_per_person": null,
        "total": 3500.0
      },
      "secondary_in_network": null,
      "out_of_network": {
        "embedded_per_person": null,
        "total": 31500.0
      }
    },
    "drug": {
      "combined": null,
      "in_network": {
        "embedded_per_person": null,
        "total": 3500.0
      },
      "secondary_in_network": null,
      "out_of_network": {
        "embedded_per_person": null,
        "total": 31500.0
      }
    }
  }
}

Properties

Name Type Required Description
comprehensive Effective Spending Limits By Network false Effective comprehensive spending limits by network
health_and_drug Effective Health And Drug Spending Limit Types false Effective health and drug spending limits

Effective Health And Drug Spending Limit Types

{
  "health": {
    "combined": null,
    "in_network": {
      "embedded_per_person": null,
      "total": 3500.0
    },
    "secondary_in_network": null,
    "out_of_network": {
      "embedded_per_person": null,
      "total": 31500.0
    }
  },
  "drug": {
    "combined": null,
    "in_network": {
      "embedded_per_person": null,
      "total": 3500.0
    },
    "secondary_in_network": null,
    "out_of_network": {
      "embedded_per_person": null,
      "total": 31500.0
    }
  }
}

Properties

Name Type Required Description
health Effective Spending Limits By Network false Effective health spending limits by network
drug Effective Spending Limits By Network false Effective drug spending limits by network

Effective Spending Limits By Network

{
  "combined": null,
  "in_network": {
    "embedded_per_person": null,
    "total": 3500.0
  },
  "secondary_in_network": null,
  "out_of_network": {
    "embedded_per_person": null,
    "total": 31500.0
  }
}

Properties

Name Type Required Description
combined Effective Spending Limit false Effective spending limit for the combined network (if network is configured)
in_network Effective Spending Limit false Effective spending limit for the in_network network (if network is configured)
secondary_in_network Effective Spending Limit false Effective spending limit for the secondary_in_network network (if network is configured)
out_of_network Effective Spending Limit false Effective spending limit for the out_of_network network (if network is configured)

Effective Spending Limit

{
  "embedded_per_person": null,
  "total": 31500.0
}

Properties

Name Type Required Description
embedded_per_person float false Embedded per-person effective threshold value (if configured)
total float true Total effective threshold value

Drug Search Response

{
  "drugs": [
    {
      "form": "Oral Tablet",
      "name": "LIPITOR",
      "strengths": [
        {
          "full_name": "atorvastatin 10 MG Oral Tablet [Lipitor]",
          "generic_name": "atorvastatin 10 MG Oral Tablet",
          "generic_rxcui": "617312",
          "ndc": "00071015510",
          "rxcui": "617314",
          "rxnorm_prescribable_name": "Lipitor 10 MG Oral Tablet",
          "strength": "10 mg"
        },
        {
          "full_name": "atorvastatin 20 MG Oral Tablet [Lipitor]",
          "generic_name": "atorvastatin 20 MG Oral Tablet",
          "generic_rxcui": "617310",
          "ndc": "00071015610",
          "rxcui": "617318",
          "rxnorm_prescribable_name": "Lipitor 20 MG Oral Tablet",
          "strength": "20 mg"
        },
        {
          "full_name": "atorvastatin 40 MG Oral Tablet [Lipitor]",
          "generic_name": "atorvastatin 40 MG Oral Tablet",
          "generic_rxcui": "617311",
          "ndc": "00071015723",
          "rxcui": "617320",
          "rxnorm_prescribable_name": "Lipitor 40 MG Oral Tablet",
          "strength": "40 mg"
        },
        {
          "full_name": "atorvastatin 80 MG Oral Tablet [Lipitor]",
          "generic_name": "atorvastatin 80 MG Oral Tablet",
          "generic_rxcui": "259255",
          "ndc": "00071015823",
          "rxcui": "262095",
          "rxnorm_prescribable_name": "Lipitor 80 MG Oral Tablet",
          "strength": "80 mg"
        }
      ]
    }
  ],
  "search_term": "lipitor",
  "version": "comm"
}

Properties

Name Type Required Description
drugs List[Drug Search Result] false A list of matching drugs
search_term string true The original search term
version string true Data set version

Drug Search Result

A drug object inside a drug set.

{
  "form": "Oral Tablet",
  "name": "LIPITOR",
  "strengths": [
    {
      "full_name": "atorvastatin 40 MG Oral Tablet [Lipitor]",
      "generic_name": "atorvastatin 40 MG Oral Tablet",
      "generic_rxcui": "617311",
      "ndc": "00071015723",
      "rxcui": "617320",
      "rxnorm_prescribable_name": "Lipitor 40 MG Oral Tablet",
      "strength": "40 mg"
    },
    ...
  ]
}

Properties

Name Type Required Description
brand string false The brand name of the drug. Only set for generic variants.
form string true Drug form
name string true The marketed name of the drug.
strengths List[object] true Available strengths of this given form.
» full_name string true Full name of drug including strength and form
» generic_name string false Generic of a branded drug
» generic_rxcui string false RxNorm Concept Unique Identifier for generic version of a drug
» ndc string true National Drug Code
» rxcui string true RxNorm Concept Unique Identifier
» rxnorm_prescribable_name string true RxNorm prescribable name
» strength string true Drug strength

Discussion

Drug Details Response

Complete details for a specific drug.

Branded Drug

{
  "brands": null,
  "form": "Topical Lotion",
  "full_name": "sulfacetamide sodium 98 MG/ML / sulfur 48 MG/ML Topical Lotion [Plexion]",
  "generic_name": "sulfacetamide sodium 98 MG/ML / sulfur 48 MG/ML Topical Lotion",
  "generic_rxcui": "1494174",
  "name": "PLEXION",
  "ndc": "57883040504",
  "rxcui": "1494824",
  "rxnorm_prescribable_name": "PLEXION 9.8 % / 4.8 % Topical Lotion",
  "strength": "9.8-4.8%"
}

Generic Drug

{
  "brands": ["PLEXION"],
  "form": "Topical Lotion",
  "full_name": "sulfacetamide sodium 100 MG/ML / sulfur 50 MG/ML Topical Lotion",
  "generic_name": null,
  "generic_rxcui": null,
  "name": "Sulfacetamide/Sulfur",
  "ndc": "42792010702",
  "rxcui": "1005856",
  "rxnorm_prescribable_name": "sulfacetamide sodium 10 % / sulfur 5 % Topical Lotion",
  "strength": "10-5%"
}

Properties

Name Type Required Description
brands List[string] false The brand names of the drug. Only set for generic variants.
form string true The form of the drug.
name string true The marketed name of the drug.
full_name string true Full name of drug including strength and form
generic_name string false Full name of the drug including ingredient, strength, and form. Will not be set for generic forms.
generic_rxcui string false The RxNorm Concept Unique Identifier of the corresponding generic, if it exists. Will not be set for generic forms.
ndc string true A (representative) National Drug Code corresponding to the RxCUI.
rxcui string true The RxNorm Concept Unique Identifier
rxnorm_prescribable_name string true The RxNorm suggested full name of the drug for writing prescriptions.
strength string true The strength of the drug.

Discussion

PLY Claim Cost Category

{
  "emergency_urgent_care": {
    "mean": 1045.06,
    "p25": 190.23,
    "p50": 427.0,
    "p75": 1377.81
  },
  "inpatient": {
    "mean": 8098.72,
    "p25": 1375.46,
    "p50": 7430.38,
    "p75": 12147.42
  },
  "labs_diagnostics": {
    "mean": 478.53,
    "p25": 90.03,
    "p50": 209.03,
    "p75": 537.97
  },
  "office_visits": {
    "mean": 638.67,
    "p25": 264.97,
    "p50": 499.34,
    "p75": 847.905
  }
}

Properties

Name Type Required Description
emergency_urgent_care object true Summary of the annual cost of emergency/urgent care expenses.
» mean float true Average annual cost of emergency/urgent care expenses.
» p25 float true 25th percentile of annual cost for emergency/urgent care expenses.
» p50 float true 50th percentile of annual cost for emergency/urgent care expenses.
» p75 float true 75th percentile of annual cost for emergency/urgent care expenses.
inpatient object true Summary of the annual cost of inpatient expenses.
» mean float true Average annual cost of inpatient expenses.
» p25 float true 25th percentile of annual cost for inpatient expenses.
» p50 float true 50th percentile of annual cost for inpatient expenses.
» p75 float true 75th percentile of annual cost for inpatient expenses.
labs_diagnostics object true Summary of the annual cost of labs diagnostics expenses.
» mean float true Average annual cost of labs diagnostics expenses.
» p25 float true 25th percentile of annual cost for labs diagnostics expenses.
» p50 float true 50th percentile of annual cost for labs diagnostics expenses.
» p75 float true 75th percentile of annual cost for labs diagnostics expenses.
office_visits object true Summary of the annual cost of office visits expenses.
» mean float true Average annual cost of office visits expenses.
» p25 float true 25th percentile of annual cost for office visits expenses.
» p50 float true 50th percentile of annual cost for office visits expenses.
» p75 float true 75th percentile of annual cost for office visits expenses.

PLY Claim Rate Category

{
  "emergency_urgent_care": 0.382,
  "inpatient": 0.056,
  "labs_diagnostics": 0.794,
  "office_visits": 0.862
}

Properties

Name Type Required Description
emergency_urgent_care float true Probably of incurring an emergency/urgent care claim.
inpatient float true Probably of incurring an inpatient claim.
labs_diagnostics float true Probably of incurring a labs diagnostics claim.
office_visits float true Probably of incurring an office visits claim.

PLY Response

{
  "claim_cost": {
    "emergency_urgent_care": {
      "mean": 1045.06,
      "p25": 190.23,
      "p50": 427.0,
      "p75": 1377.81
    },
    "inpatient": {
      "mean": 8098.72,
      "p25": 1375.46,
      "p50": 7430.38,
      "p75": 12147.42
    },
    "labs_diagnostics": {
      "mean": 478.53,
      "p25": 90.03,
      "p50": 209.03,
      "p75": 537.97
    },
    "office_visits": {
      "mean": 638.67,
      "p25": 264.97,
      "p50": 499.34,
      "p75": 847.905
    }
  },
  "claim_rate": {
    "emergency_urgent_care": 0.382,
    "inpatient": 0.056,
    "labs_diagnostics": 0.794,
    "office_visits": 0.862
  },
  "total_allowed_spending": 3381.16,
  "utilization_level_dist": {
    "high": 0.082,
    "low": 0.412,
    "moderate": 0.506
  }
}

Properties

Name Type Required Description
claim_cost PLY Claim Cost Category true This calculates the range of annual costs by service category, conditional on using any services over the year.
claim_rate PLY Claim Rate Category true This statistics reports the probability of incurring a claims in each spending category.
total_allowed_spending float true This is the average total medical bills that similar households incur over the course of a year.
utilization_level_dist object true This statistic reports the probability that you or your household will have “low”, “medium” or “high” levels of medical spending next year.
» low float true Probability that you or your household will have “low” levels of medical spending next year.
» moderate float true Probability that you or your household will have “medium” levels of medical spending next year.
» high float true Probability that you or your household will have “high” levels of medical spending next year.

Supplemental Recommendation Request

A payload sent for requesting supplemental plans recommendations for a set of plans.

{
  "health_plan_external_id": "ppo_plan_1",
  "plans": [
    {
      "plan_type": "dental",
      "external_id": "dental1",
      "eligible_member_ids": ["external_id_1"]
    }
  ]
}

Properties

Name Type Required Description
health_plan_external_id string false id of a health plan the household is eligible for.
plans List[object] false Plans to consider.
» plan_type string true A valid supplemental plan_type.
» external_id string true User provided identifier to find the recommendation in the response.
» eligible_member_ids List[string] true List of member external ids to consider for the plan.

Discussion

Supplemental Recommendation Response

{
  "plans": [
    {
      "external_id": "dental2",
      "plan_type": "dental",
      "reasons": [
        {
          "code": "dental_routine_care",
          "data": {},
          "description": "Everyone needs routine dental care, and this will help you cover those costs."
        }
      ],
      "score": 3,
      "score_type": "always_recommend"
    },
    {
      "external_id": "dental1",
      "plan_type": "dental",
      "reasons": [
        {
          "code": "dental_routine_care",
          "data": {},
          "description": "Everyone needs routine dental care, and this will help you cover those costs."
        }
      ],
      "score": 3,
      "score_type": "always_recommend"
    },
    {
      "external_id": "vision1",
      "plan_type": "vision",
      "reasons": [
        {
          "code": "eye_exam",
          "data": {},
          "description": "Even if you don’t wear glasses, it's a good idea to get routine eye exams."
        },
        {
          "code": "eye_glasses",
          "data": {},
          "description": "This coverage helps pay for glasses or contact lenses, if you need them."
        }
      ],
      "score": 3,
      "score_type": "always_recommend"
    },
    {
      "external_id": "dis2",
      "plan_type": "std",
      "reasons": [],
      "score": 1,
      "score_type": "qualitative"
    },
    {
      "external_id": "hi1",
      "plan_type": "hospital",
      "reasons": [
        {
          "code": "hospital_pregnancy",
          "data": {
            "applicable_members": ["DEF_456"]
          },
          "description": "You may receive benefits if you get bills for inpatient labor and delivery"
        }
      ],
      "score": 3,
      "score_type": "qualitative"
    }
  ]
}

Properties

Name Type Description
plans List[object] Plans that recommendations were made for.
» plan_type string A valid supplemental plan_type.
» external_id string Identifier for a given plan instance.
» score_type string Scoring methodology. One of qualitative, always_recommend.
» score string Plan score.
reasons List[object] List of reasons to support the recommendation.
» code string Reason code.
» description string Description of the reason, populated with variables (if any).
» data object Object containing useful data pertaining to the reason (i.e. - applicable_members)

Benefit Administration via Picwell DX (Unreleased)

Picwell provides Benefit Administration Platforms the ability to easily and securely integrate the Picwell DX experience into their benefit selection process. Benefit Administrators wishing to take advantage of the Picwell DX platform may go through the following steps:

  1. The benefit administration platform creates a household resource and an eligibility resource for an end user, as described in this documentation
  2. The benefit administration platform forwards the user to Picwell DX
  3. Picwell DX initiates SSO authentication of the end user with the benefit administration platform using the Open ID Connect protocol
  4. The platform returns the IDs of the household and eligibility resources related to the end user as part of the ID Token during the OIDC interaction
  5. After the end user completes the Picwell DX experience, the end user is directed back to the benefit administration platform
  6. If desired, the platform may make a request to Picwell's API to retrieve the elections and HSA contributions selected by the end user during the Picwell DX experience

See this diagram for more detail.

SSO via Open ID Connect

The ID Token returned to Picwell from the OIDC integration should contain the additional claims household_id, plan_selection_id, and redirect_url.

Claim Meaning
household_id ID of the household object created within Picwell. See Create a New Household for details
plan_selection_id ID of the Plan Selection object for the end user, created when sending an eligibility set to Picwell. See Create A User Eligibility Set for details
redirect_url The URL to direct the end user to upon completion of the Picwell DX experience

Plan Selection Resource

The Plan Selection resource allows the benefit administration platform to inform Picwell of the set of plans for which a household is eligible, and allows the platform to retrieve the plans that a household selected at the end of the Picwell DX experience.

To avoid situations where household or plan set changes invalidate the eligibility set, this resource is intended to be created shortly before forwarding the user to the DX experience.

Eligibility sets and enrollments in this resource expire after 1 week.

Create a User Eligibility Set

POST /plan_selection/

Example request

{
  "household_id": "household_extid",
  "eligibility": [
    {
      "members": [
        "policyholder_extid",
        "spouse_extid"
      ],
      "plans": [
        {
          "hsa_annual": {
            "employer_contribution_amount": 50.0
          },
          "monthly_premiums": {
            "post_tax": 15.12,
            "pre_tax": 43.14
          },
          "external_id": "plan1",
          "external_coverage_tier_id": "external_coverage_tier_1" 
        },
        {
          "hsa_annual": {
            "employer_contribution_amount": 100.0
          },
          "monthly_premiums": {
            "post_tax": 0.0,
            "pre_tax": 97.17
          },
          "external_id": "plan2", 
          "external_coverage_tier_id": "external_coverage_tier_1"
        }
      ]
    },
    {
      "members": [
        "policyholder_extid",
        "spouse_extid",
        "child_extid"
      ],
      "plans": [
        {
          "hsa_annual": {
            "employer_contribution_amount": 50.0
          },
          "monthly_premiums": {
            "post_tax": 15.12,
            "pre_tax": 43.14
          },
          "external_id": "plan1",
          "external_coverage_tier_id": "external_coverage_tier_2"
        },
        {
          "hsa_annual": {
            "employer_contribution_amount": 100.0
          },
          "monthly_premiums": {
            "post_tax": 0.0,
            "pre_tax": 97.17
          },
          "external_id": "plan2",
          "external_coverage_tier_id": "external_coverage_tier_2"
        }
      ]
    }
  ]
}

Example response

{
  "id": "863d3113-3fec-46b3-8a2a-b4e99f5ba3c2"
}

For each combination of household members, provide premiums and employer HSA contributions for each eligible plan.

Parameters

Parameter In Type Required Description
eligibility body List[Eligibility] true All member_id combinations of the Household must be present in the eligibility list.
Every combination must include existing Household members and the policyholder.
household_id body string true Household ID

Responses

Status Meaning Description Schema
200 OK Plan Selection Resource Id

Create Enrollment for Plan Selection

POST /plan_selection/<plan_selection_id>/enrollments/

Example request

{
    "health_plan": {
        "waived": false,
        "members": [
            "the-policyholder",
            "the-spouse"
        ],
        "external_id": "plan1"
    },
    "accounts": [
        {
            "hsa_annual": {
                "employee_contribution_amount": 123.45
            }
        }
    ]
}

Parameters

Parameter In Type Required
health_plan body Plan Selection Plan true
accounts body List[Plan Selection Account] false

Responses

Status Meaning Description Schema
204 No Content

Retrieve The User Enrollments

Example response

{
  "health_plan": {
      "waived": false,
      "external_id": "plan1",
      "external_coverage_tier_id": "external_coverage_tier_3",
      "members": ["policyholder_id", "spouse_id"]
  },
  "accounts": [
    {
      "hsa_annual": {
        "employee_contribution_amount": 123.45
      }
    }
  ]
}

GET /plan_selection/<plan_selection_id>/enrollments/

Get all enrollments for an eligibility set

Parameters

Parameter In Type Required Description
plan_selection_id path string true ID of the Plan Selection resource created for a household

Responses

Status Meaning Description Schema
200 OK Plan Selection Enrollment

Errors

Most errors encountered using the Picwell API will cause the request to fail and return a 400 level response. However, where possible, a request may succeed and return a 200 response with as much data as possible while providing information about portions of the request that could not be fulfilled in the errors field. For example, /recommendation/ requests that could not recognize all external IDs provided will return information on recognized plans with a 200 status code, and details of unrecognized plans in the errors property.

Status Code Summary

Picwell errors rely on conventional HTTP response codes to indicate success or failure of an API request.

These status codes should be planned for and handled in client code through exception handling.

HTTP status code Status code meaning Example scenario Exception handling
200 Success Successful request to Picwell API n/a
201 Successful creation Successfully created a new resource n/a
400 Bad request A request to Picwell that is missing a required field. For instance, a missing external_id parameter with /recommendation/ A 400 status code indicates user error with our APIs. Review the response body for a description of the error.
401 Unauthorized Authentication token has expired Recreate an authentication token using the /auth/ method, then retry the operation
404 Object Not Found A request for a resource which does not exist n/a
500, 503 Server Error Picwell encounters an internal server error while processing a request Retry the request to Picwell as the error may have been temporary. Persistent failures may indicate that Picwell is experiencing downtime.

Error Response Schema

All errors returned by the API will return a JSON response with a top-level field errors which contains a list of errors. An error is guaranteed to have the following fields:

Name Type Description
title string the title of the error
detail string, list, or object a human-readable description of the error
status int the HTTP status code returned with the error

200-level errors

Unknown Plan External IDs

{
  "errors": [
    {
      "detail": {
        "external_ids": ["invalid_plan_1", "invalid_plan_2"]
      },
      "status": 200,
      "title": "Unknown Plan External IDs"
    }
  ]
}

Sending unknown plan IDs to the /recommendation/ endpoint will result in a 200 OK response rather than a 400 response.

400-level Errors

Unknown Plan External IDs

{
  "errors": [
    {
      "detail": {
        "external_ids": ["invalid_plan_1", "invalid_plan_2"]
      },
      "status": 400,
      "title": "Unknown Plan External IDs"
    }
  ]
}

Sending unknown plan IDs to the /plans/ or /hsa/ endpoint will result in a 400 response.

Invalid JSON

{
  "errors": [
    {
      "detail": "Request payload could not be parsed as JSON",
      "status": 400,
      "title": "JSON Deserialization Error"
    }
  ]
}

Sending invalid JSON in the request body to any endpoint will result in a 400 response.

Missing Fields

{
  "errors": [
    {
      "detail": {
        "members": ["Please provide at least 1 item."],
        "zip_code_3": ["This field is required."]
      },
      "status": 400,
      "title": "Bad Request"
    }
  ]
}

Sending JSON to any endpoint which is missing required fields will result in a 400 response. This example shows that required field zip_code_3 is missing and also that members cannot be empty.

Wrong Type

{
  "errors": [
    {
      "detail": {
        "version": ["Value 'foo' is not int."]
      },
      "status": 400,
      "title": "Bad Request"
    }
  ]
}

Sending JSON to any endpoint which is given the wrong type for a field will result in a 400 response. This example shows that the version field must be an integer in the request body for the given endpoint.

Unknown Fields Selected

{
  "errors": [
    {
      "detail": {
        "fields": "Unknown fields selected: 'benefits.external_id'"
      },
      "status": 400,
      "title": "Field Select Error"
    }
  ]
}

Specifying a field selection for a field that does not exist will result in a 400 response. In this situation, check the API documentation for the schema you are selecting into.

Field Select Too Deep

{
  "errors": [
    {
      "detail": {
        "fields": "Only top-level field selection is allowed, except for 'benefits' where one-level is allowed. Invalid plan fields: 'max_oop.embedded'"
      },
      "status": 400,
      "title": "Field Select Error"
    }
  ]
}

Specifying a field select deeper than allowed will result in a 400 response. In this example, max_oop.embedded is too deep of a selection and max_oop should be requested instead.

Troubleshooting

Each request has a request ID that is returned in the X-Request-ID header. You can provide this to your Picwell representative along with your issue to assist in troubleshooting any difficulties.






















shell ruby python javascript