NAV

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-commercial-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://commercial-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:

To this end, Picwell will require from its clients:

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

Authentication is required for all but the /auth/ endpoint and is handled using session tokens. To reach an authenticated endpoint, provide a Picwell-Auth-Token header in your request.

Once a session token is created, it should be used for every subsequent request until it expires when the ttl_seconds limit is reached.

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

To create a session, log in using the following route:

POST /auth/

Body parameter

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

Parameters

Parameter In Type Required Description
body body AuthRequest true Authentication body

Example responses

201 Response

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

Responses

Status Meaning Description Schema
200 OK Session created AuthResponse
400 Bad Request Bad request None
401 Unauthorized Bad auth None

API Versions

Version 6 (latest)

The latest version, introduced April 2019.

Version 5 and below

API v1-v5 documentation

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)

Media Types and 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.

$ curl https://uat-commercial-api.picwell.net/healthcheck/ -I \
  -H "Accept: application/vnd.picwell.v6+json"
HTTP/1.1 200 OK

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

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 /household/.

See Households for more information.

Example POST to /household/

HOUSEHOLD=$( cat <<DONE
    {
    "version": 2017,
    "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": "3", "answer": "no" },
        { "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,
        "age": 45,
        "dependant": false,
        "prescriptions": [
            { "ndc": "12345678901", "frequency": 30, "quantity": 60 }
        ]
        }
    ],
    "zip_code_3": "123"
    }
DONE
)

curl -v -L -X POST \
    ${URL}/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": 2017
}

Get available plans

curl -X GET \
  http://${URL}/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 /recommendation/${HOUSEHOLD_ID}.

As the request body, supply a HealthRecommendationRequest 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 /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}/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 /recommendation/<household_id> using all eligible plans

curl -s -L -X POST \
    ${URL}/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_2017",
        "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 eligbility 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 /client_survey/ HTTP/1.1
Host: commercial-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 /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 /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

GET /drugs/?q={drug_name}

Search for Prescription Drugs.

Example request

GET /drugs?q=lipitor HTTP/1.1
Host: commercial-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

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 DrugSearchResponse

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 /household/

Establish a household for use in a recommendation request.

Body parameter

{
    "members": [
        {
            "age": 32,
            "gender": "male",
            "prescriptions": [
                {
                    "ndc": "00093738598",
                    "quantity": 0,
                    "frequency": 0
                }
            ],
            "uses_tobacco": false,
            "dependant": false,
            "policyholder": true,
            "external_id": "ABC_123"
        },
        {
            "age": 29,
            "gender": "female",
            "prescriptions": [
                {
                    "ndc": "00093738598",
                    "quantity": 30,
                    "frequency": 30
                }
            ],
            "external_id": "DEF_456",
            "dependant": false,
            "policyholder": false,
            "uses_tobacco": false
        }
    ],
    "survey": [
        {
            "question_id": "1",
            "answer": "very_important"
        },
        {
            "question_id": "2",
            "answer": "gt_5"
        },
        {
            "question_id": "3",
            "answer": "no"
        },
        {
            "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_3": "123",
    "version": 2018,
    "external_id": "test"
}

Parameters

Parameter In Type Required Description
body body Household true Household definition

Example responses

201 Response

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

Responses

Status Meaning Description Schema
201 Created Household created HouseholdReference

Discussion

Query household versions

GET /household/

Get all versions of a Household by external_id

Parameters

Parameter In Type Required Description
external_id query string true Household ID

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK Household versions [HouseholdReference]

Discussion

Create household version

POST /household/{household_id}/

Create a new version of a previously created household.

Body parameter

{
  "members": [
    {
      "age": 32,
      "gender": "male",
      "prescriptions": [
        {
          "ndc": "00093738598",
          "quantity": 0,
          "frequency": 0
        }
      ],
      "uses_tobacco": true,
      "dependant": false,
      "policyholder": true,
      "external_id": "ABC_123"
    }
  ],
  "survey": [
    {
      "question_id": "1",
      "answer": "very_important"
    }
  ],
  "zip_code_3": "123",
  "version": 2018,
  "external_id": "test"
}

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": 2018
}

Responses

Status Meaning Description Schema
200 OK Version created HouseholdReference

Discussion

Update household

PUT /household/{household_id}/

Update an existing Household.

Body parameter

{
  "members": [
    {
      "age": 32,
      "gender": "male",
      "prescriptions": [
        {
          "ndc": "00093738598",
          "quantity": 0,
          "frequency": 0
        }
      ],
      "uses_tobacco": true,
      "dependant": false,
      "policyholder": true,
      "external_id": "ABC_123"
    }
  ],
  "survey": [
    {
      "question_id": "1",
      "answer": "very_important"
    }
  ],
  "zip_code_3": "123",
  "version": 2018,
  "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": 2018
}

Responses

Status Meaning Description Schema
200 OK Household updated HouseholdReference

Discussion

Get household

GET /household/{household_id}/

Retrieve a specific version of a Household.

Parameters

Parameter In Type Required Description
household_id path string true Household ID
version query string false 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",
  "version": 2018,
  "survey": [
    {
      "question_id": "1",
      "answer": "very_important"
    }
  ],
  "members": [
    {
      "age": 32,
      "gender": "male",
      "prescriptions": [
        {
          "ndc": "00093738598",
          "quantity": 0,
          "frequency": 0
        }
      ],
      "uses_tobacco": true,
      "dependant": false,
      "policyholder": true,
      "external_id": "ABC_123"
    }
  ],
  "income": 75000,
  "external_id": "test"
}

Responses

Status Meaning Description Schema
200 OK Household retrieved Household

Plans

Get Health Plans

GET /plans/health/

Get all available health plans.

Example request

GET /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: commercial-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
          }
        ],
        "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
          }
        ],
        "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 DetailedHealthPlanResponse

Discussion

Get Health Plan Details

GET /plans/health/{external_id}/

Get full plan details available for a given health plan.

Example request

GET /plans/health/Aetna3500/ HTTP/1.1
Host: commercial-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
        }
      ],
      "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
        }
      ],
      "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
      },
      "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
      },
      "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 DetailedHealthPlanDescription

Recommendations

Generate Health-Only Recommendations

POST /recommendation/{household_id}/

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

Body parameter

{
  "plans": [
      {
        "health_provider_locations": {
          "in_network": [],
          "out_of_network": []
        },
        "external_id": "health_plan_1",
        "premiums": {
          "employee_contribution": 50,
          "employer_contribution": 50
        }
      },
      {
        "health_provider_locations": {
          "in_network": [],
          "out_of_network": []
        },
        "external_id": "health_plan_2",
        "premiums": {
          "employee_contribution": 50,
          "employer_contribution": 50
      }
    },
  ]
}

Parameters

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

Example responses

200 Response

{
  "recommendations": [
    {
      "costs": {
        "drugs": 0,
        "effective_premium": 50,
        "real_cost": 800.50,
        "services": {
          "in_network": 600.50
        },
        "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"
    },
    {
      "costs": {
        "drugs": 0,
        "effective_premium": 100,
        "real_cost": 1200.47,
        "services": {
          "in_network": 1000.00
        },
        "spending_account_balance_increase": 0,
        "spending_account_benefit": 0
      },
      "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 HealthRecommendationResponse

Generate A&V Recommendations

POST /recommendation/{household_id}/

Make a recommendation for the provided set of Ancillary & Voluntary plans and packages for the latest version of a 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&VRecommendationRequest true Recommendation request

Example responses

200 Response

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

Responses

Status Meaning Description Schema
200 OK A&V Recommendations generated A&VRecommendationResponse

Discussion

HSA

Get HSA Recommendations

POST /hsa/{household_id}/

This endpoint provides recommended contribution and benefit deciles for a plan based on the latest version of a given Household. 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
}

Parameters

Parameter In Type Required Description
household_id path string true Household ID
HSAPlanData body HSAPlanData 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 HSARecommendationResponse

Survey

Survey Questions

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

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 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 ConditionAnswer
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

AuthRequest

{
  "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.

AuthResponse

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

Properties

Name Type Required Description
auth_token string false The authentication token

HealthProviderLocation

{
  "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 true Description of in-network health provider locations

Health Provider Location Types

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

HouseholdReference

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

Properties

Name Type Required Description
id string true The ID of the Household
version integer true The client-provided temporal identifier of the Household

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,
            "dependant": false,
            "policyholder": true,
            "external_id": "ABC_123"
        },
        {
            "age": 29,
            "gender": "female",
            "prescriptions": [
                {
                    "ndc": "00093738598",
                    "quantity": 30,
                    "frequency": 30
                }
            ],
            "external_id": "DEF_456",
            "dependant": false,
            "policyholder": false,
            "uses_tobacco": false
        }
    ],
    "survey": [
        {
            "question_id": "1",
            "answer": "very_important"
        },
        {
            "question_id": "2",
            "answer": "gt_5"
        },
        {
            "question_id": "3",
            "answer": "no"
        },
        {
            "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_3": "123",
    "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": 2018,
    "external_id": "test"
}

Properties

Name Type Required Description
members [HouseholdMember] true List of enrollees seeking coverage
survey [SurveyAnswer] true Responses to Survey questions
client_survey ClientSurveyAnswers false Responses to ClientSurvey questions
zip_code_3 string true The household 3-digit zip-code. Ex. 191 if zip is 19146
income float false Household income
spending_accounts [HouseholdSpendingAccount] false List of spending account information
enrollment HouseholdEnrollment false Enrollment information
version integer true Household version
external_id string false Unique client-specific ID for this Household

Discussion

HouseholdMember

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,
  "utilization": {
    "inpatient_days": 1,
    "specialist_visits": 1,
    "pcp_visits": 2
  }
}

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 true The member's gender (male or female)
policyholder boolean true Set to true if the member is the policyholder. There can only be 1 policyholder per household.
prescriptions [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.
utilization Utilization false The previous year's utilization of medical services 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

HouseholdSpendingAccount

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

HouseholdEnrollment

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

DetailedHealthPlanDescription

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
      }],
      "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
      }],
      "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
      },
      "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
      },
      "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
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 SpendingLimitTypes 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 SpendingLimitTypes 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)

DetailedHealthPlanResponse

{
  "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
        },
        "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
        },
        "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 [DetailedHealthPlanDescription] true The requested plan information

SpendingLimitTypes

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
    },
    "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,
      "out_of_network": null
    },
    "drug": {
      "combined": {
        "family": 11900,
        "individual": 5950,
        "individual_child": null,
        "individual_spouse": null
      },
      "in_network": null,
      "out_of_network": null
    }
  },
  "embedded": false
}

Properties

Name Type Required Description
comprehensive SpendingLimitsByNetworkType 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 SpendingLimitsByNetworkType 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 SpendingLimitsByNetworkType 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.

SpendingLimitsByNetworkType

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
  },
  "out_of_network": {
      "family": 20000,
      "individual": 10000,
      "individual_child": null,
      "individual_spouse": null
  }
}

Properties

Name Type Required Description
combined SpendingLimitsByCoverageTier false A breakdown of spending limits for combined costs applicable to the plan, broken down by coverage tier.
in_network SpendingLimitsByCoverageTier false A breakdown of spending limits for in-network costs applicable to the plan, broken down by coverage tier.
out_of_network SpendingLimitsByCoverageTier false A breakdown of out-of-network costs applicable to the plan, broken down by coverage tier.

SpendingLimitsByCoverageTier

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
            }
        ],
        "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
            }
        ],
        "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
            }
        ]
    }
}

Properties

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

HealthCostSharingByNetwork

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
  },
  "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 HealthCostSharing true Details of in-network health benefit cost sharing for this plan.
out_of_network HealthCostSharing false Details of out-of-network health benefit cost sharing for this plan.

HealthCostSharing

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.

DrugCostSharingByNetwork

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
    }
  ],
  "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 [DrugCostSharing] true Details of in-network drug benefit cost sharing for this plan.
out_of_network [DrugCostSharing] false Details of out-of-network drug benefit cost sharing for this plan.

DrugCostSharing

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 true none Numeric quantity of drug
frequency integer true none Days between refills

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

SurveyAnswer

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 ConditionAnswer false Selected responses to the medical condition question

Discussion

ClientSurveyAnswers

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

ClientSurveyResponse

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

ConditionAnswer

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 UserCondition true
spouse UserCondition false
child UserCondition false

UserCondition

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

HealthRecommendationRequest

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

{
  "plans": [
      {
        "health_provider_locations": {
          "in_network": [],
          "out_of_network": []
        },
        "external_id": "health_plan_1",
        "premiums": {
          "employee_contribution": 50,
          "employer_contribution": 50
        }
      },
      {
        "health_provider_locations": {
          "in_network": [],
          "out_of_network": []
        },
        "external_id": "health_plan_2",
        "premiums": {
          "employee_contribution": 50,
          "employer_contribution": 50
      }
    }
  ]
}

Properties

Name Type Required Description
plans [HealthRecommendationsRequestHealthPlan] false Plans to consider.

Omiting 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.

HealthRecommendationResponse

{
  "recommendations": [
    {
      "costs": {
        "drugs": 0,
        "effective_premium": 50,
        "real_cost": 1050.00,
        "services": {
          "in_network": 1000.00
        },
        "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"
    },
    {
      "costs": {
        "drugs": 0,
        "effective_premium": 100,
        "real_cost": 2100.00,
        "services": {
          "in_network": 2000.00
        },
        "spending_account_balance_increase": 0,
        "spending_account_benefit": 0
      },
      "health_provider_locations": [],
      "plan": {
        "external_id": "health_plan_2",
        "id": "health_plan_2"
      },
      "score": 55,
      "tier": "red"
    },
  ]
}

Properties

Name Type Required Description
recommendations [Recommendation] true
errors [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&VRecommendationRequest

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 [[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 [A&VRecommendationRequestA&VPlan] false Health plans
» hi [A&VRecommendationRequestA&VPlan] false Hospital Indemnity plans
» ci [A&VRecommendationRequestA&VPlan] false Critical Illness plans
» acc [A&VRecommendationRequestA&VPlan] false Accident plans

A&VRecommendationResponse

{
  "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 [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.

HSAPlanData

{
    "external_id": "0123_12431_2018",
    "spending_account_contribution": 100.0
}

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.

HSARecommendationResponse

{
  "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 [float] The annual expected out-of-pocket costs before tax benefits or employer contributions are accounted for.
employer_contribution_deciles [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 [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 [float] The annual recommended contribution amount corresponding to each cost in oop_deciles.
tax_benefit_deciles [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 [object] true List of plan types included in this package
plans [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

HealthRecommendationsRequestHealthPlan

{
  "health_provider_locations": {
    "in_network": [],
    "out_of_network": []
  },
  "premiums": {
    "employee_contribution": 100,
    "employer_contribution": 100
  },
  "hsa_contributions": {
    "monthly_employer_contribution": 50
  }
  "external_id": "12345"
}

Properties

Name Type Required Description
health_provider_locations object true If there are no Health Provider Locations in-network or out-of-network, set the appropriate field to an empty list, [].
» in_network [HealthProviderLocation] true Description of in-network Health Provider Location.
» out_of_network [HealthProviderLocation] true Description of out-of-network Health Provider Location.
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.
spending_account_contribution float false Deprecated in favor of specifying hsa_contributions. Monthly employer contribution to a spending account from the plan.

Premiums

Premiums may by 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 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&VRecommendationRequestA&VPlan

{
  "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 [HealthProviderLocation] 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": {
    "drugs": 0,
    "effective_premium": 50,
    "real_cost": 1050.00,
    "services": {
      "in_network": 1000.00
    },
    "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 Restrictions Description
costs object true none Costs of drugs, effective premium, real cost, services (in- and out-of-network), and spending account data
health_provider_locations [object] false none
» in_network [HealthProviderLocation] true none The providers in-network for this plan
» out_of_network [HealthProviderLocation] true none The providers out-of-network for this plan
plan [object] true none
» external_id string true none Unique client-specific ID for this plan
» id string true none Unique ID for this plan
score integer true The relative Picwell Score value when comparing this plan against other plans
tier string true none Picwell color tier, one of “red”, “green”, “yellow”

DrugSearchResponse

{
  "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 [DrugSearchResult] false A list of matching drugs
search_term string true The original search term
version string true Data set version

DrugSearchResult

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
form string true Drug form
name string true Drug name
strengths [object] true
» 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

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."
        ],
        "version": [
            "This field is required."
        ],
        "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 fields version and zip_code_3 are 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.