vericred_client

VericredClient - the Ruby gem for the Vericred API

Getting Started

Signing Up

Visit our Developer Portal to create an account.

Once you have created an account, you can create one Application for your Production environment and another for a Sandbox (select the appropriate Plan when you create the Application).

SDKs

Our API follows standard REST conventions, so you can use any HTTP client to integrate with us. You will likely find it easier to use one of our autogenerated SDKs, which we make available for several common programming languages.

Authentication

To authenticate, pass the API Key you created in the Developer Portal as a Vericred-Api-Key header.

curl -H 'Vericred-Api-Key: YOUR_KEY' "https://api.vericred.com/drugs?search_term=Lipitor"

Versioning

Vericred's API default to the latest version. However, if you need a specific version, you can request it with an Accept-Version header.

The current version is v6. We support prior versions. Our latest stable version is v7 and we will indicate in the documentation for an endpoint if it's required.

curl -H 'Vericred-Api-Key: YOUR_KEY' -H 'Accept-Version: v6' "https://api.vericred.com/drugs?search_term=Lipitor"

Pagination

Endpoints that accept page and per_page parameters are paginated. They expose four additional fields that contain data about your position in the response, namely Total, Per-Page, Link, and Page as described in RFC-5988.

For example, to display 5 results per page and view the second page of a GET to /networks, your final request would be GET /networks?....page=2&per_page=5.

Sideloading

When we return multiple levels of an object graph (e.g. Providers and their States we typically the associated data. In this example, we would provide an Array of States and a state_id for each provider. This is done primarily to reduce the payload size since many of the Providers will share a State

Simplified Example

{
  providers: [{ id: 1, state_id: 1}, { id: 2, state_id: 1 }],
  states: [{ id: 1, code: 'NY' }]
}

If you need the second level of the object graph, you can just match the corresponding id.

Selecting specific data

All endpoints allow you to specify which fields you would like to return. This allows you to limit the response to contain only the data you need.

For example, let's take a request that returns the following JSON by default

{
  provider: {
    id: 1,
    name: 'John',
    phone: '1234567890',
    field_we_dont_care_about: 'value_we_dont_care_about'
  },
  states: [{
    id: 1,
    name: 'New York',
    code: 'NY',
    field_we_dont_care_about: 'value_we_dont_care_about'
  }]
}

To limit our results to only return the fields we care about, we specify the select in the query string for a GET or the body for a POST.

In this case, we want to select name and phone from the provider key, so we would add the parameters select=provider.name,provider.phone. We also want the name and code from the states key, so we would add the parameters select=states.name,states.code. The id field of each document is always returned whether or not it is requested.

Our final request would be GET /providers/1234567898?select=provider.name,provider.phone,states.name,states.code

The response would be

{
  provider: {
    id: 1234567898,
    name: 'John',
    phone: '1234567890'
  },
  states: [{
    id: 1,
    name: 'New York',
    code: 'NY'
  }]
}

Plan and Rate Data

Vericred's Plan and Rate Data let you search and quote Major Medical and Ancillary Insurance Plans in a given area for a particular family in the Individual Market or a group of families in the Small Group Market. Vericred provides the relevant data via this API and via our Bulk Format (documented below)

Plans

A Plan defines a set of Benefits available to its purchaser. For example, a Major Medical Plan would specify cost-share Benefits for services like a Primary Care Provider visit, a Specialist visit or an Emergency Room visit. A Dental Plan might specify Benefits for Periodontics and Fluroride Treatments. The Benefits for each Product type (Major Medical, Dental, and Vision) are documented below.

Benefits Format

Benefits for Plans can be quite complex. With the goals of capturing and standardizing the complexity while retaining a human-readable format, we have developed a Bakus-Naur Form(BNF) context-free grammar, with which we present Benefits.

Benefit cost-share strings are formatted to capture:

  • Network tiers
  • Compound or conditional cost-share
  • Limits on the cost-share
  • Benefit-specific maximum out-of-pocket costs

Example #1 As an example, we would represent this Summary of Benefits & Coverage as:

  • Hospital stay facility fees:

    • Network Provider: $400 copay/admit plus 20% coinsurance
    • Out-of-Network Provider: $1,500 copay/admit plus 50% coinsurance
    • Vericred's format for this benefit: In-Network: $400 before deductible then 20% after deductible / Out-of-Network: $1,500 before deductible then 50% after deductible

  • Rehabilitation services:

    • Network Provider: 20% coinsurance
    • Out-of-Network Provider: 50% coinsurance
    • Limitations & Exceptions: 35 visit maximum per benefit period combined with Chiropractic care.
    • Vericred's format for this benefit: In-Network: 20% after deductible / Out-of-Network: 50% after deductible | limit: 35 visit(s) per Benefit Period

Example #2 In this other Summary of Benefits & Coverage, the specialty_drugs cost-share has a maximum out-of-pocket for in-network pharmacies.

  • Specialty drugs:
    • Network Provider: 40% coinsurance up to a $500 maximum for up to a 30 day supply
    • Out-of-Network Provider Not covered
    • Vericred's format for this benefit: In-Network: 40% after deductible, up to $500 per script / Out-of-Network: 100%

BNF

Here's a description of the benefits summary string, represented as a context-free grammar:

root                      ::= coverage

coverage                  ::= (simple_coverage | tiered_coverage) (space pipe space coverage_modifier)?
tiered_coverage           ::= tier (space slash space tier)*
tier                      ::= tier_name colon space (tier_coverage | not_applicable)
tier_coverage             ::= simple_coverage (space (then | or | and) space simple_coverage)* tier_limitation?
simple_coverage           ::= (pre_coverage_limitation space)? coverage_amount (space post_coverage_limitation)? (comma? space coverage_condition)?
coverage_modifier         ::= limit_condition colon space (((simple_coverage | simple_limitation) (semicolon space see_carrier_documentation)?) | see_carrier_documentation | waived_if_admitted | shared_across_tiers)
waived_if_admitted        ::= ("copay" space)? "waived if admitted"
simple_limitation         ::= pre_coverage_limitation space "copay applies"
tier_name                 ::= "In-Network-Tier-2" | "Out-of-Network" | "In-Network"
limit_condition           ::= "limit" | "condition"
tier_limitation           ::= comma space "up to" space (currency | (integer space time_unit plural?)) (space post_coverage_limitation)?
coverage_amount           ::= currency | unlimited | included | unknown | percentage | (digits space (treatment_unit | time_unit) plural?)
pre_coverage_limitation   ::= first space digits space time_unit plural?
post_coverage_limitation  ::= (((then space currency) | "per condition") space)? "per" space (treatment_unit | (integer space time_unit) | time_unit) plural?
coverage_condition        ::= ("before deductible" | "after deductible" | "penalty" | allowance | "in-state" | "out-of-state") (space allowance)?
allowance                 ::= upto_allowance | after_allowance
upto_allowance            ::= "up to" space (currency space)? "allowance"
after_allowance           ::= "after" space (currency space)? "allowance"
see_carrier_documentation ::= "see carrier documentation for more information"
shared_across_tiers       ::= "shared across all tiers"
unknown                   ::= "unknown"
unlimited                 ::= /[uU]nlimited/
included                  ::= /[iI]ncluded in [mM]edical/
time_unit                 ::= /[hH]our/ | (((/[cC]alendar/ | /[cC]ontract/) space)? /[yY]ear/) | /[mM]onth/ | /[dD]ay/ | /[wW]eek/ | /[vV]isit/ | /[lL]ifetime/ | ((((/[bB]enefit/ plural?) | /[eE]ligibility/) space)? /[pP]eriod/)
treatment_unit            ::= /[pP]erson/ | /[gG]roup/ | /[cC]ondition/ | /[sS]cript/ | /[vV]isit/ | /[eE]xam/ | /[iI]tem/ | /[sS]tay/ | /[tT]reatment/ | /[aA]dmission/ | /[eE]pisode/
comma                     ::= ","
colon                     ::= ":"
semicolon                 ::= ";"
pipe                      ::= "|"
slash                     ::= "/"
plural                    ::= "(s)" | "s"
then                      ::= "then" | ("," space) | space
or                        ::= "or"
and                       ::= "and"
not_applicable            ::= "Not Applicable" | "N/A" | "NA"
first                     ::= "first"
currency                  ::= "$" number
percentage                ::= number "%"
number                    ::= float | integer
float                     ::= digits "." digits
integer                   ::= /[0-9]/+ (comma_int | under_int)*
comma_int                 ::= ("," /[0-9]/*3) !"_"
under_int                 ::= ("_" /[0-9]/*3) !","
digits                    ::= /[0-9]/+ ("_" /[0-9]/+)*
space                     ::= /[ \t]/+

Major Medical

Vericred's data covers all Major Medical Plans available in the Individual and Small Groups (2-50 or 2-100) Markets in the US. These Plans are governed by CMS and are ACA-compliant. We do not include certain Plans that fall outside of the ACA, for example, Faith-Based Plans or Short-Term Medical Plans

We support the following Benefits Fields for Major Medical Plans. These represent the vast majority of fields available on a Summary of Benefits and Coverage

The following are the appropriate Benefit Fields for Major Medical:

  • ambulance
  • child_eye_exam
  • child_eyewear
  • chiropractic_services
  • diagnostic_test
  • durable_medical_equipment
  • emergency_room
  • family_drug_deductible
  • family_drug_moop
  • family_medical_deductible
  • family_medical_moop
  • generic_drugs
  • habilitation_services
  • home_health_care
  • hospice_service
  • imaging_center
  • imaging_physician
  • individual_drug_deductible
  • individual_drug_moop
  • individual_medical_deductible
  • individual_medical_moop
  • inpatient_birth
  • inpatient_birth_physician
  • inpatient_facility
  • inpatient_mental_health
  • inpatient_physician
  • inpatient_substance
  • lab_test
  • non_preferred_brand_drugs
  • nonpreferred_generic_drug_share
  • nonpreferred_specialty_drug_share
  • outpatient_ambulatory_care_center
  • outpatient_facility
  • outpatient_mental_health
  • outpatient_physician
  • outpatient_substance
  • plan_coinsurance
  • postnatal_care
  • preferred_brand_drugs
  • prenatal_care
  • preventative_care
  • primary_care_physician
  • rehabilitation_services
  • skilled_nursing
  • specialist
  • specialty_drugs
  • telemedicine
  • urgent_care

Dental

Dental benefits are less standardized than Major Medical. Because of this, we have captured benefits for the most commonly specified services and procedures. If a Plan only specifies cost-share for "Major", "Minor", "Elective", etc, we determine the category for each of the benefits that we support and display the appropriate value for its category.

To view the technical documentation, click here.

The following are the supported Benefit Fields for Dental:

  • bridges
  • crowns
  • denture_relines_rebases
  • denture_repair_and_adjustments
  • dentures
  • emergency_treatment
  • endodontics
  • family_annual_max
  • family_deductible
  • fluoride_treatment
  • implants
  • individual_annual_max
  • individual_deductible
  • inlays
  • onlays
  • oral_exam
  • oral_surgery
  • orthodontics_adult
  • orthodontics_child
  • periodontal_maintenance
  • periodontics
  • prophylaxis_cleaning
  • radiograph_bitewings
  • radiograph_other
  • restoration_fillings
  • sealant
  • simple_extraction
  • space_maintainers

Vision

Vision benefits are similar in structure to Dental. Again, when benefits are broken out by category, we determine the appropriate category for each service or procedure and display the approprate value for its category.

To view the technical documentation, click here.

The following are the supported Benefit Fields for Vision:

  • eye_exam
  • retinal_imaging
  • frame
  • eyeglass_lenses_single_vision
  • eyeglass_lenses_bifocal
  • eyeglass_lenses_trifocal
  • eyeglass_lenses_lenticular
  • uv_coating
  • tint
  • standard_antireflective_coating
  • premium_antireflective_coating
  • standard_polycarbonate_lenses_child
  • standard_polycarbonate_lenses_adult
  • standard_progressive_lenses
  • premium_progressive_lenses
  • standard_scratch_resistance
  • polarized_lenses
  • photochromatic_lenses
  • standard_contact_lens_fit_and_follow_up
  • premium_contact_lens_fit_and_follow_up
  • contact_lenses_conventional
  • contact_lenses_disposable
  • contact_lenses_medically_necessary
  • laser_vision_correction
  • additional_pairs_of_eyeglasses

Medicare Advantage

Medicare Advantage endpoints support MA (Medicare Advantage plans without prescription drug benefits), MAPD (Medicare Advantage plans with prescription drug benefits), and PDP (prescription drug benefits only) plans.

Medical and hospital benefits - we support over 4000 individual plans through our API nationwide. At this time, we do not support EGHP (employer group health plans).

Prescription drug benefits - drug benefits are categorized into initial coverage phase, coverage gap phase, and catastrophic phase. Each phase is broken down by drug tiers, pharmacy tiers, and length of supply.

Click here to learn more about quoting Medicare Advantage plans.

Rates

Rates are returned from the API as a part of Quoting. We calculate Rates in one of two ways.

Sheet Rates

When a Carrier supplies us with Sheet Rates, we display exactly the value provided to us. For example, in the Major Medical market, most Carriers provide a single rate for each combination of Applicant age and tobacco status in a given Rating Area. For example, in Austin, TX, a 21-year-old non-tobacco-user may be $312.41 per month while a 22-year-old tobacco-user may be $401.75 per month. Certain Vision and Dental Carriers supply Sheet Rates as well, though it is less common.

Rate Factors

Certain Major Medical Carriers and most Vision and Dental Carriers supply Rate Factors. The attributes on which the factors are based are the same as Sheet Rates for the Major Medical market (due to restrictions on what factors may be used in ACA Plans, which limit the possible factors to age and tobacco status).

In Dental and Vision, the types of Rate Factors are more varied. For example, SIC Code and Group size in the Group market and Gender in the Individual Market are commonly used Rate Factors

Other common Rate Factors for Dental and Vision products are Geographic and "Trend" (enrollment date) Factors. In Major Medical, these types of variance are handled by CMS-defined Rating Areas.

In order to calculate a Rate using Rate Factors, the following methodology is applied:

B = Base Rate
f = Rate Factor Function 1
f' = Rate Factor Function 2

B * f(x) * f'(y) [* f''(z)] ... = n

Rating Areas

For Major Medical products, CMS defines Rating Areas. Under the ACA, all Rate Factors in a Rating Area must be identical for a given time period. E.g. in Arizona, the rate for a 21-year-old non-tobacco user must be identical in all counties contained in Rating Area 1 (Mohave, Coconino, Apache, and Navajo), but may be different than the rate for a 21-year-old non-tobacco user in all counties Rating Area 2 (Yavapai county only) for a given year in the Individual Market and a given quartern in the Small Group market.

Rating Areas are defined either by County, Zip Code or both, depending on the State. Because of this variance, all API endpoints that require a Location require both zip_code and fips_code (a county code). Bulk Data for Rating Areas and Service Areas also specifies locations using both zip_code and fips_code.

Rating Areas do not apply to products other than Major Medical

Service Areas

CMS mandates that Major Medical Rates be defined by Rating Areas, which themselves define a geography in which Plans are offered. Carriers often choose not to offer a Plan in and entire Rating Area due to network coverage or other factors. Instead, the Carrier would define a Service Area that specifies where a given Plan is offered.

Each Plan is available in a single Service Area and each Service Area is defined by either County, Zip Code, or both, depending on the Carrier. Because of this variance, all API endpoints that require a Location require both zip_code and fips_code (a county code). Bulk Data for Rating Areas and Service Areas also specifies locations using both zip_code and fips_code.

In Dental and Vision plans, we use a Service Area to define availability as well, although it typically mirrors a Geographic Rate Factor.

Quoting

One of the primary use-cases for the Vericred API is to run Quotes to determine the Rate for a given family (in the Individual Market) or group (in the Small Group Market). We support quoting across Major Medical, Vision, and Dental. In both cases, the process of generating a Quote is broken out into several steps:

  1. Find all available Plans in the relevent Service Areas for the family or group.
  2. Using Business Rules for each Plan, determine if the family or group is eligible for that Plan.
  3. Using Business Rules for each Plan, determine which members of the family or which members of each family in the group should be considered for Rating.
  4. Using the Sheet Rates or Rate Factors for each Plan, determine the Rate the family, or for each family in the group.
  5. If running a Composite quote, determine the portion of the total Rate that each family will pay.

Individual Quotes

An Individual Quote is one for Plans that are available to a particular family, outside the context of their Employer. In the Major Medical market, many of these Plans are available on Healthcare.gov or the State-Based Exchange for non-Healthcare.gov states. The API supports both on-market and off-market Plans.

For details on Major Medical Quoting API calls see below

Specifying the Location

In order to determine which plans are available and the rate for each Plan, you must specify a location. When creating a Quote for the Individual Market, that information is contained in the POST body of the request:

POST /plans/medical/search
{
  ...
  "zip_code": "11201",
  "fips_code": "36047"
  ...
}

Specifying Applicants

Applicants are the members of the family being quoted and are specified in the POST body of the request.

POST /plans/medical/search
{
  ...
  "applicants": [
    {
      "age": 34,
      "smoker": true,
      "child": false
    },
    {
      "age": 32,
      "smoker": false,
      "child": false
    },
    {
      "age": 4,
      "smoker": false,
      "child": true
    }
  ]
  ...
}

Specifying Enrollment Date

The enrollment_date determines which Plans and Rates are returned. Specifying an enrollment_date in the past allows you to calculate historical data as far back as 2014.

Plan Benefits

Plan Benefits are returned in the response for Individual Quotes

POST /plans/medical/search
{
  ...
}

Response:
{
  "plans": [
    {
      ...
      "individual_medical_deductible": "$5,000",
      "family_medical_deductible": "$10,000"
      ...
    }

  ]
}

Premiums

The value for the family being quoted is returned in the premium field. If no Applicants are provided, the premium field will be 0

Major Medical Quotes

In order to Quote Major Medical Plans, send a POST to /plans/medical/search. In addition, the age, smoker and child attributes of each Applicant must be present.

Subsidies

On-market (Healthcare.gov and State-Based Exchange) Major Medical Plans are eligible for government subsidies. The subsidy calculation is based on the percentage of the family's income that the IRS has designated as "affordable" for that family and the Second Lowest-Cost Silver Plan available to that family.

In order to calculate subsidies for a family the following parameters must be supplied:

POST /plans/medical/search
{
  ...
  "household_size": 4,
  "household_income": 40000
  ...
}

The amount that the family will pay after subsidy is returned in the premium_subsidized field for each plan.

Subsidy Calculation

Here is how subsidies are calculated. This is fully handled by the Vericred API, but the steps are enumerated below for clarity.

  1. Determine the percentage of the Federal Poverty Level for the family based on the household size and income.
  2. Reference the CMS table to determine the appropriate percentage of income for the family to spend on healthcare.
  3. Multiply that value by the family's income. This is the total amount that the family can spend on healthcare for the year, after the subsidy.
  4. Find the cost of the Second Least-Expensive Silver Plan available to the family, accounting for the percentage of premium that goes to Essential Health Benefits
  5. Calculate the difference in price between the amount the family should spend on healthcare and the Second Least-Expensive Silver Plan's premium. This is the subsidy.
  6. Apply the subsidy to all on-market Plans available to the family. The subsidized premium can never be below $0 (for example, a low-cost Bronze Plan may be less expensive than the subsidy)

Cost Sharing Reduction Plans

Cost Sharing Reduction (CSR) Plans are available to lower income families and offer enhanced benefits for certain Silver Plans at the same cost as the non-CSR Plans available to higher-income families.

If a family is eligible for CSR Plans, the Vericred API will return the relevant Plan in place of the non-CSR version.

In order to include CSR Plans where applicable, the following parameters must be supplied:

POST /plans/medical/search
{
  ...
  "household_size": 4,
  "household_income": 40000
  ...
}

The Children's Health Insurance Program (CHIP)

The Children's Health Insurance Program (CHIP) provides low-cost health coverage to children in families that earn too much money to qualify for Medicaid.

If a family is eligible for CHIP, the Vericred API will include the subsidy in the returned premiums. In order to include CHIP subsidies in premium calculations, the following parameters must be supplied:

POST /plans/medical/search
{
  ...
  "applicants": [
    {
      "age": 34,
      "smoker": true,
      "child": false
    },
    {
      "age": 32,
      "smoker": false,
      "child": false
    },
    {
      "age": 4,
      "smoker": false,
      "child": true
    },
    {
      "age": 4,
      "smoker": false,
      "child": true
    }
  ],
  "household_size": 4,
  "household_income": 40000
  ...
}

CHIP eligibility is displayed within the meta-tag in the response as eligible_for_chip_medicaid:

{
  "meta": {
      "total": 150,
      "eligible_for_chip_medicaid": true,
      "premium_tax_credit": 500.20
    },
  "coverages": [],
  "plans": [...]
}

If you do not want CHIP subsidies to be included in the premiums, simply do not include the household_income parameter in the request.

Dental Quotes

Quoting Dental Plans for a family requires slightly different parameters for Applicants, due to the method with which Plans are rated. The folloiwng example contains the require parameters:

POST /plans/dental/search
{
  ...
  "applicants": [
    {
      "age": 34,
      "gender": "M",
      "child": false
    },
    {
      "age": 32,
      "gender": "F",
      "child": false
    },
    {
      "age": 4,
      "gender": "M",
      "child": true
    }
  ]
  ...
}

Note that in contrast to Major Medical Quotes, Dental Quotes require gender, but do not require smoker.

Also note that Subsidies and Cost Sharing Reduction are not relevant for Dental Quotes.

Vision Quotes

Quoting Vision Plans for a family requires slightly different parameters for Applicants, due to the method with which Plans are rated. The folloiwng example contains the require parameters:

POST /plans/vision/search
{
  ...
  "applicants": [
    {
      "age": 34,
      "gender": "M",
      "child": false
    },
    {
      "age": 32,
      "gender": "F",
      "child": false
    },
    {
      "age": 4,
      "gender": "M",
      "child": true
    }
  ]
  ...
}

Note that in contrast to Major Medical Quotes, Vision Quotes require gender, but do not require smoker.

Also note that Subsidies and Cost Sharing Reduction are not relevant for Vision Quotes.

Medicare Advantage quotes

Given an enrollment date and location, you can search all plans available at this location using /plans/medadv/search; you can also search a specific plan using its plan ID with /plans/medadv/plan_id if the plan ID is already known. The following example contains the required parameters:

{
"zip_code": "02880",
"fips_code": "44009",
"enrollment_date": "2019-01-01"
}

To view the technical documentation, click here.

Quotes for Groups

A Group Quote finds Plans and Rates for a group of employees for a small business. Different Plans are available to small groups than are available in Individual Quoting. In addition, Business Rules that apply across multiple families or based upon employer attributes such as SIC code factor into rates and availability.

In addition, due to performance requirements and for enhanced auditing, Group Quotes are persisted across requests. This means that a given Quote can be retrieved after it has been created.

Identifiers

In order to make it easier to cross-reference local copies of data with Quotes and other data in the Vericred API, most entities allow for the specification of an external_id field. You can use this to store a primary or natural key from your system in order to easily match records returned from the API with records in your system.

Specifying the Group

Creating a group is the first step in Group Quoting. The API requires that certain information such as sic_code, and chamber_association be provided and returns a the attributes and id for the newly created Group

Full documentation is available below

Specifying the Locations

When creating a Group, you must also specify one or more Locations. Of those Locations specified, one must be primary. That Location is used to calculate Plan eligibility using the relevant Service Areas. Some Carriers use secondary Locations to determine eligibility as well, which is why those must be specified as well.

POST /groups
{
  "group": {
    ...
  },
  "locations": [
    {
      ...
      "zip_code": "11201",
      "fips_code": "36047",
      "primary": true
      ...
    }
  ]
}

Specifying the Census

A Census is the collection of Members contained in the Group. The attributes of each Member and his or her Dependents determine the Rate for the Group as a whole. Certain attributes of the Member are important for calculating Rates and applying Business Rules. For example, the Member's home address and in which office he or she works are relevant for certain Business Rules.

Dependent Relationships

The Dependents for a given Member also factor into the Rates and application of Business Rules. For example, certain Plans cover only Dependents of particular types and/or only Dependents of a particular type who live in the same household as the primary Member

Valid Dependent Relationships:

  • adopted_child
  • child
  • court_appointed_guardian
  • dependent_of_dependent
  • ex_spouse
  • foster_child
  • grand_child
  • guardian
  • life_partner
  • other
  • sibling
  • sponsored_dependent
  • spouse
  • step_child
  • ward
POST

/groups/{id}/members
{
  "members": [
    ...
    {
      "cobra": false,
      "date_of_birth": "1980-01-01",
      "fips_code": "36047"
      "gender": "M",
      "last_used_tobacco": "2017-01-01",
      "location_id": :location_id
      "retiree": false,
      "zip_code": "11201",
      "dependents": [
        ...
        {
          "relationship": "child",
          "same_household": true
        }
        ...
      ]
    }
    ...
  ]
}

Creating a Quote

Once the Census has been created, we can generate a Quote for the Group.

Major Medical Quotes

To generate a Major Medical Quote, specify the product_line of Quote as medical

POST /groups/{id}/quotes
{
  ...
  "product_line": "medical"
  ...
}

Dental Quotes

To generate a Dental Quote, specify the product_line of Quote as dental

POST /groups/{id}/quotes
{
  ...
  "product_line": "dental"
  ...
}

Vision Quotes

To generate a Vision Quote, specify the product_line of Quote as vision

POST /groups/{id}/quotes
{
  ...
  "product_line": "vision"
  ...
}

Retrieving Aggregate Rates

Once you have created a Quote, you can retrieve its aggregate Rates. Rates are broken down by Member and Dependent, so that you can show the final cost in different scenarios where an employer might cover a different percentage of Member and Dependent costs.

GET /quotes/{id}/rates

Response
{
  "rates": [
    ...
    {
      "id": "123abc",
      "plan_id": "12345NY6789012",
      "total_premium": "2800.00",
      "member_premium": "1000.00",
      "dependent_premium": "1800.00",
      "premiums": {
        "age_banded": {
          "total_member": "1000.00",
          "total_dependent": "1800.00",
          "total": "2800.00"
        },
        "2_tier_composite": {
        "employee_only": "200.00",
        "employee_plus_family": "400.00",
        "total": "2800.00"
        },
        "3_tier_composite": {
          "employee_only": "200.00",
          "employee_plus_one": "250.00",
          "employee_plus_family": "330.00",
          "total": "2800.00"
        },
        "4_tier_composite": {
          "employee_only": "200.00",
          "employee_plus_child": "220.00",
          "employee_plus_spouse": "250.00",
          "employee_plus_family": "330.00",
          "total": "2800.00"
        }
      }
    }
    ...
  ]
}

Loading Plan Data

Aggregate Rates responses do not include Plan details in order to keep the payload small. Plan data can be retrieved in one of two ways:

Loading the Plan from the API:

GET /plans/{id}

Response:
{
  "plans": [
    ...
    {
      ...
      "individual_medical_deductible": "$5,000",
      "family_medical_deductible": "$10,000",
      ...
    }
    ...

  ]
}

Pulling in Bulk Plan Data and matching up Plans by their id.

Retrieving Member-Level Rates

In order to retrieve the exact Rate for each Member and their Dependents for given Plan, you can load Member-Level Rates.

GET /rates/{id}/member_rates

Response
{
  "member_rates": [
  ...
  {
    "id": "123abc",
    "member_id": "234def",
    "member_external_id": "externally-supplied-id",
    "member_premium": 500.0,
    "dependent_premium": 600.0,
    "total_premium": 1100.0
  }
  ...
  ]
}

Note that all MemberRates are for one particular Plan - the one referenced by the parent Rate.

Business Rules

Vericred works with our Carrier partners to acquire and apply Business Rules that can affect either Plan availability or the way in which Members and Dependents are rated. For example, one Carrier's Business Rules might specify that Members and Dependents who have used tobacco in the past 4 months are considered "tobacco-users", while another's may specify that period to be 1 year.

These rules are applied transparently during the Quoting process and do not require any additional action or input on your part.

For a full accounting of Business Rules and a list of Carriers whose Business Rules are applied, please contact [email protected]

Composite Rates

Composite Rates are commonly used in Major Medical, Dental, and Vision Plans to simplify operations by charging each family the weighted average of the Group's total premium. The most common methodology is as follows:

  1. Calculate the Rates for the entire Group using Sheet Rates or Rate Factors as appropriate
  2. Categorize each Family within the Group. The categorization differs depending on whether the Composite Rate is 2, 3, or 4-tier
  3. Multiply the number of Families in each category by the constant for that category. These constants are provided to Vericred by the Carrier. This determines the total number of "Rating Units"
  4. Divide the total premium calculated in Step 1 by the total number of Rating Units to get the price per Rating Unit
  5. The Rate each Family pays is the constant for that Family's category multiplied by the price per Rating Unit.

You can request that a Quote be calculated using Composite Rates when creating it:

POST /quotes
{
  ...
  "rating_method": "4_tier_composite"
  ...
}

If no Composite Rates methodology is available, the Vericred API will return standard age-banded Rates.

Network and Provider Data

A Provider is an individual or organization in the medical profession. For example, an individual doctor is a Provider as are certain clinics and hospitals.

Providers are related to Networks. A Network is a collection of Providers that are under a particular contract with a given Carrier. A given Carrier will often have multiple Networks. For example, there may be a large national Network as well as several smaller regional Networks.

Each Plan has a Network. A consumer who visits a Provider typically incurs fewer costs when visiting a Provider in the Network covered by his or her Plan. The premium for a Plan is often proportional to the size of its Network

Finding Providers

In order to determine if a particular Plan covers a given Provider, you must first identify the Provider. To do so, use the Provider Search API endpoint and specify some search criteria:

POST /providers/search
{
  "search_term": "foo",
  "zip_code": "11201"
}

The API will return an ordered list of Providers who match the query along with their names, addresses, and other demographic data. The id field returned refers to the Provider's NPI number. This is the key that is used to identify the Provider across different API endpoints.

Finding Networks

A Network is a collection of Providers that are under a particular contract with a given Carrier. A given Carrier will often have multiple Networks. For example, there may be a large national Network as well as several smaller regional Networks.

The API supports searching for Networks by Carrier, market and state. For more details view the endpoint documentation

Matching Providers to Networks

In order to determine if a Provider is covered by a user's Plan, you will need to map the Provider to a Network. There are several methods to do this using the API

You can specify one or more npi values in the plan search. To do so, include a list of providers in the request

POST /plans/medical/search
{
  ...
  "providers": [
    { "npi": 1234567890 },
    { "npi": 2345678901 }
  ]
  ...
}

The response will then return a list of `in_network_ids` and `out_of_network_ids` for each `Plan`

{ "plans": [ ... { ... "id": "12345NY1234567", "in_network_ids": [1234567890], "out_of_network_ids": [1234567890] ... }, { ... "id": "12345NY2345678", "in_network_ids": [1234567890, 1234567890], "out_of_network_ids": [] ... } ... ] }

Simply reference the Provider in question by its id for each Plan to see if that Provider is in-network for the Plan.

Matching by Plan ID

Given a Provider's id, you can retrieve all of his or her hios_ids

For more details see the endpoint documentation

GET /providers/1234567890
{
  "provider": {
    ...
    "hios_ids": [
      ...
      "12345NY1234567"
      ...
    ]
    ...
  }
}

The returned hios_ids can be used to cross-reference a Plan

Matching by Network

Once you have an ID returned from the Network search endpoint, you can cross-reference it with the network_ids returned from both the Provider search and Provider details endpoints.

This is useful for large group data or when you are not dealing with Plans directly, but rather at the Network level.

This SDK is automatically generated by the Swagger Codegen project:

  • API version: 1.0.0
  • Package version: 0.0.40
  • Build package: class io.swagger.codegen.languages.RubyClientCodegen

Installation

Build a gem

To build the Ruby code into a gem:

gem build vericred_client.gemspec

Then either install the gem locally:

gem install ./vericred_client-0.0.40.gem

(for development, run gem install --dev ./vericred_client-0.0.40.gem to install the development dependencies)

or publish the gem to a gem hosting service, e.g. RubyGems.

Finally add this to the Gemfile:

gem 'vericred_client', '~> 0.0.40'

Install from Git

If the Ruby gem is hosted at a git repository: https://github.com/GIT_USER_ID/GIT_REPO_ID, then add the following in the Gemfile:

gem 'vericred_client', :git => 'https://github.com/GIT_USER_ID/GIT_REPO_ID.git'

Include the Ruby code directly

Include the Ruby code directly using -I as follows:

ruby -Ilib script.rb

Getting Started

Please follow the installation procedure and then run the following code:

# Load the gem
require 'vericred_client'

# Setup authorization
VericredClient.configure do |config|
  # Configure API key authorization: Vericred-Api-Key
  config.api_key['Vericred-Api-Key'] = 'YOUR API KEY'
  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
  #config.api_key_prefix['Vericred-Api-Key'] = 'Bearer'
end

api_instance = VericredClient::BulkPlansApi.new

body = VericredClient::PlansBulkSearchRequest.new # PlansBulkSearchRequest | 


begin
  #Plans in Bulk
  result = api_instance.find_bulk_plans(body)
  p result
rescue VericredClient::ApiError => e
  puts "Exception when calling BulkPlansApi->find_bulk_plans: #{e}"
end

Documentation for API Endpoints

All URIs are relative to https://api.vericred.com/

Class Method HTTP request Description
VericredClient::BulkPlansApi find_bulk_plans POST /plans/bulk Plans in Bulk
VericredClient::CarrierGroupsApi delete_carrier_group DELETE /carrier_groups/vericred_id Delete a CarrierGroup.
VericredClient::CarrierGroupsApi put_carrier_group PUT /carrier_groups/vericred_id Create/update a CarrierGroup
VericredClient::CarrierSubsidiaryDisclaimersApi delete_carrier_subsidiary_disclaimer DELETE /carrier_subsidiary_disclaimers/vericred_id Delete a Carrier Subsidiary Disclaimer
VericredClient::CarrierSubsidiaryDisclaimersApi put_carrier_subsidiary_disclaimer PUT /carrier_subsidiary_disclaimers/vericred_id Create/update a Carrier Subsidiary Disclaimer
VericredClient::CarriersApi delete_carrier DELETE /carriers/vericred_id Delete a Carrier.
VericredClient::CarriersApi put_carrier PUT /carriers/vericred_id Create/update a Carrier
VericredClient::DentalPlansApi delete_dental_plan DELETE /plans/dental/vericred_id Delete a Dental Plan.
VericredClient::DentalPlansApi find_dental_plans POST /plans/dental/search Search Plans
VericredClient::DentalPlansApi put_dental_plan PUT /plans/dental/vericred_id Create/update a Dental Plan
VericredClient::DentalPlansApi show_dental_plan GET /plans/dental/id Show Plan
VericredClient::DentalPlansApi show_dental_plan_0 GET /plans/dental/vericred_id Show Plan
VericredClient::DrugsApi get_drug_coverages GET /drugs/id/coverages Drug Coverage Search
VericredClient::DrugsApi list_drugs GET /drugs Drug Search
VericredClient::EmbargoesApi delete_embargo DELETE /embargoes/vericred_id Delete an Embargo.
VericredClient::EmbargoesApi put_embargo PUT /embargoes/vericred_id Create/update an Embargo
VericredClient::FormulariesApi list_formularies GET /formularies Formulary Search
VericredClient::FormulariesApi show_formulary_drug_package_coverage GET /formularies/formulary_id/drug_packages/ndc_package_code Formulary Drug Package Search
VericredClient::IssuersApi delete_issuer DELETE /issuers/vericred_id Delete an Issuer.
VericredClient::IssuersApi put_issuer PUT /issuers/vericred_id Create/update an Issuer
VericredClient::MajorMedicalPlansApi find_major_medical_plans POST /plans/medical/search Search Plans
VericredClient::MajorMedicalPlansApi show_medical_plan GET /plans/medical/id Show Plan
VericredClient::MedicalPlansApi find_major_medical_plans POST /plans/medical/search Search Plans
VericredClient::MedicalPlansApi put_medical_plan PUT /plans/medical/vericred_id Create/update a Medical Plan
VericredClient::MedicalPlansApi show_medical_plan GET /plans/medical/id Show Plan
VericredClient::MedicareAdvantagePlansApi find_medicare_advantage_plans POST /plans/medadv/search Search Plans
VericredClient::MedicareAdvantagePlansApi put_medicare_advantage_plan PUT /plans/medadv/vericred_id Create/update a Medicare Advantage Plan
VericredClient::MedicareAdvantagePlansApi show_med_adv_plan GET /plans/medadv/id Show Plan
VericredClient::NetworkSizesApi list_state_network_sizes GET /states/state_id/network_sizes State Network Sizes
VericredClient::NetworkSizesApi search_network_sizes POST /network_sizes/search Network Sizes
VericredClient::NetworksApi create_disruption_analysis POST /networks/disruption_analysis Disruption Analysis
VericredClient::NetworksApi create_network_comparisons POST /networks/id/network_comparisons Compare Multiple Networks
VericredClient::NetworksApi list_networks GET /networks Network Search
VericredClient::NetworksApi show_network GET /networks/id Display a Network
VericredClient::PlansApi delete_plan DELETE /plans/hios/year Delete a plan
VericredClient::ProvidersApi delete_provider DELETE /providers/npi Delete an NPI from a provider.
VericredClient::ProvidersApi get_provider_plans GET /providers/npi/plans Provider Plans
VericredClient::ProvidersApi get_providers POST /providers/search Find Providers
VericredClient::ProvidersApi put_provider PUT /providers/npi Find a Provider
VericredClient::QuotingApi create_group POST /groups Create a Group
VericredClient::QuotingApi create_group_quote POST /groups/id/quotes Create a Quote
VericredClient::QuotingApi show_group GET /groups/id Display a Group
VericredClient::QuotingApi show_group_rates GET /quotes/id/rates Display Rates
VericredClient::QuotingApi show_rate_member_rates GET /rates/id/member_rates Display Member Rates
VericredClient::QuotingApi update_group_members PUT /groups/id/members Create or Update Members
VericredClient::RatesApi delete_rate DELETE /rates/vericred_id Delete a Rate.
VericredClient::RatesApi put_rate PUT /rates/vericred_id Create/update a Rate
VericredClient::ServiceAreasApi put_service_area PUT /service_areas/vericred_id Create/update a ServiceArea
VericredClient::SpecialtiesApi get_specialties GET /specialties Specialty Search
VericredClient::VisionPlansApi delete_vision_plan DELETE /plans/vision/vericred_id Delete a Vision Plan.
VericredClient::VisionPlansApi find_vision_plans POST /plans/vision/search Search Plans
VericredClient::VisionPlansApi put_vision_plan PUT /plans/vision/vericred_id Create/update a Vision Plan
VericredClient::VisionPlansApi show_medical_plan GET /plans/vision/id Show Plan
VericredClient::VisionPlansApi show_vision_plan GET /plans/vision/vericred_id Show Plan
VericredClient::ZipCountiesApi get_zip_counties GET /zip_counties Search for Zip Counties
VericredClient::ZipCountiesApi show_zip_county GET /zip_counties/id Show an individual ZipCounty

Documentation for Models

Documentation for Authorization

Vericred-Api-Key

  • Type: API key
  • API key parameter name: Vericred-Api-Key
  • Location: HTTP header