Ideon API

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

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.ideonapi.com/networks?search_term=Anthem"

Ideon's API is versioned by endpoint. The current default version for all endpoints is v6.

Some endpoints feature additional functionality with versions v7 or v8, which can be accessed using the Accept-Version header. For each endpoint, we will indicate in the documentation which version(s) are available.

The API specifications for the latest available version will always be shown. Specifications for prior versions are available via request through Ideon support.

curl -H 'Vericred-Api-Key: YOUR_KEY' -H 'Accept-Version: v7' "https://api.ideonapi.com/networks?search_term=Anthem"

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.

Ideon uses HTTP codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error given the request and/or credentials provided. Codes in the 5xx range indicate an error with Ideon's servers.

HTTP Code	Description
200	The request was successful.
201	The request was successful and a resource was created.
204	The request was successful and no content is returned.
400	The request body is malformed (invalid JSON) or a secondary validation check failed.
401	The API request requires user authentication. Refer to our Authentication section above.
403	The API key doesn't have permissions to perform the request.
404	The resource was not found.
405	The HTTP Method is not allowed. Are you doing a GET when it's a POST?
422	There is something invalid or missing in the request body.
429	Too many requests hit the API too quickly.
500	The Ideon server encountered an unexpected condition which prevented it from fulfilling the request.
503	The Ideon server timed out when processing the request.

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'
  }]
}

Ideon'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. Ideon provides the relevant data via this API and via our Bulk Format (documented below)

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
  • Ideon'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.
  • Ideon'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
  • Ideon'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                                         ::= (tier_prefix tier space slash space)* (tier_prefix tier) (space pipe space limit_condition_prefix limit)?

tier_prefix                                  ::= tier_name colon space
tier_name                                    ::= ("In-Network-Tier-" integer) | "Out-of-Network" | "In-Network"
integer                                      ::= /[0-9]/+ (comma_int | under_int)*
comma_int                                    ::= ("," /[0-9]/3*3) !"_"
under_int                                    ::= ("_" /[0-9]/3*3) !","
tier                                         ::= allowance_tier_coverage | tier_coverage | not_applicable | unlimited | included | unknown | not_covered
allowance_tier_coverage                      ::= allowance_coverage (space conjunction space allowance_coverage)* tier_limitation?
allowance_coverage                           ::= (pre_coverage_limitation space)? percentage_amount (space post_coverage_limitation)? (comma? space coverage_condition)? (space after_allowance)
pre_coverage_limitation                      ::= first space digits space time_unit plural
digits                                       ::= /[0-9]/+ ("_" /[0-9]/+)*
time_unit                                    ::= /hour/ | /minute/ | /year/ | /month/ | /day/ | /week/ | /visit/ | /lifetime/ | /benefit period/ | /pregnancy/
percentage_amount                            ::= single_percentage
single_percentage                            ::= number "%"
number                                       ::= float | integer
float                                        ::= digits "." digits
post_coverage_limitation                     ::= ((("then" space currency) | "per condition") space)? ("per" | "for") space (treatment_unit | ((integer space)? time_unit)) plural?
currency                                     ::= currency_range | single_currency
currency_range                               ::= single_currency "-" single_currency
single_currency                              ::= currency_number
treatment_unit                               ::= /person/ | /group/ | /condition/ | /script/ | /visit/ | /exam/ | /item/ | /treatment/ | /admission/ | /episode/ | /procedure/
coverage_condition                           ::= ("before deductible" | "after deductible" | "penalty" | allowance | "deductible applies") (space unit_amount)? (space allowance)?
allowance                                    ::= upto_allowance | after_allowance
upto_allowance                               ::= "up to" space (currency space)? "allowance"
after_allowance                              ::= "after" space (currency space)? "allowance"
unit_amount                                  ::= digits space (treatment_unit | (time_unit plural)) plural?
conjunction                                  ::= "then" | "and" | "or" | "plus"
tier_limitation                              ::= comma space "up to" space (currency | (integer space time_unit plural?)) (space post_coverage_limitation)?
tier_coverage                                ::= coverage (space conjunction space coverage)* tier_limitation*
coverage                                     ::= disallow_zero_percentage_on_after_deductible (pre_coverage_limitation space)? (currency_amount | percentage_amount | unit_amount) (space post_coverage_limitation)? (comma? space coverage_condition)?
disallow_zero_percentage_on_after_deductible ::= !/0% after deductible/
currency_amount                              ::= currency_range | single_currency
not_applicable                               ::= "Not Applicable" | "N/A" | "NA"
limit_condition_prefix                       ::= limit_condition colon space
limit_condition                              ::= "limit" | "condition"
limit                                        ::= (coverage (semicolon space see_carrier_documentation)?) | see_carrier_documentation | waived_if_admitted | shared_across_tiers | time_unit_per_duration
waived_if_admitted                           ::= ("copay" space)? "waived if admitted"
time_unit_per_duration                       ::= integer time_unit plural space "per" time_unit plural?
see_carrier_documentation                    ::= "see carrier documentation for more information"
currency_number                              ::= /[$]{1}[0-9]{1,3}(?:,[0-9]{3})*(?:\.[0-9]{2})?/
included                                     ::= /[iI]ncluded in [mM]edical/
shared_across_tiers                          ::= "shared across all tiers"
not_covered                                  ::= /[nN]ot [cC]overed/
unlimited                                    ::= /[uU]nlimited/
unknown                                      ::= "unknown"
first                                        ::= "first"
space                                        ::= /[ \t]/
plural                                       ::= "(s)"
semicolon                                    ::= ";"
pipe                                         ::= "|"
slash                                        ::= "/"
comma                                        ::= ","
colon                                        ::= ":"

Major Medical

Ideon'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

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.

Dental

Dental benefits are less standardized than Major Medical. Because of this, we have captured benefits in two ways. As a high-level plan summary, the coverage tier fields - preventive, basic, and major - show the amount the plan pays for a benefit.

Additionally, we include the most commonly specified services and procedures and their associated cost to the customer, limitations, and which coverage tier they are included in. If a plan only specifies cost-share for preventive, basic, major, etc, we determine the appropriate category and value for each of the benefits that we support.

To view the technical documentation, click here.

The following are the supported Benefit Fields for Dental:

• adult_individual_deductible
• adult_individual_annual_max
• child_individual_annual_max
• child_individual_deductible
• child_individual_moop
• family_deductible
• coverage_tiers
  • preventive
  • basic
  • major
• benefits
  • bridges
  • crowns
  • denture_relines_rebases
  • denture_repair_and_adjustments
  • dentures
  • emergency_treatment
  • endodontics
  • fluoride_treatment
  • implants
  • 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
• copay_schedule
• out_of_network_reimbursement_type
• usual_customary_reasonable_percentile

Vision

Vision benefits are similar in structure to Dental. We display high-level plan summary data such as copays and service frequencies as well as detailed benefit information. Again, where benefits are broken out by category, we display the appropriate value for each service or procedure.

To view the technical documentation, click here.

The following are the supported Benefit Fields for Dental:

• exam_copay
• materials_copay
• service_frequency
  • exams
  • lenses
  • frames
  • contacts
• benefits
  • 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

Life

Group Life insurance is supported. The following are the supported Benefit Fields for Life plans:

• Benefits
  • Employee
    • Minimum
    • Maximum
    • Increment
  • Spouse
    • Minimum
    • Maximum
    • Increment
  • Child
    • Minimum
    • Maximum
    • Increment
• Guaranteed Issue Bands
  • Minimum Age
  • Maximum Age
  • Employee
  • Spouse
  • Child
• Benefit Reduction Schedules
  • Age
  • Reduction Amount
• Convertible After Termination
• Disabled Premium Waiver
• Premium Increase
• Accidental Death & Dismemberment Included
• Accidental Death & Dismemberment Covered Members
  • Employee
  • Spouse
  • Child

Disability

Group Disability insurance is supported. The following are the supported Benefit Fields for Disability plans:

• Benefit
  • Amount
  • Maximum Amount
  • Maximum Duration
• Disabled Premium Waiver
• Own Occupation Disability Definition
• Waiting Period Accident
• Waiting Period Illness

Accident

Group Accident insurance is supported. Accident plans are structured to include high-level plan data as well as a standardized set of the most common benefits.

To view the technical documentation, click here.

The following are the supported Benefit Fields for Accident plans:

• Portability
• 24 Hour
• Rate Guarantee
• Accidental Death & Dismemberment Included
• Accidental Death Benefit
  • Employee
  • Spouse
  • Child
• Common Carrier Death Benefit
  • Employee
  • Spouse
  • Child
• Benefits
  • Ambulance
  • Burns
  • Diagnostic Exam
  • Dislocations
  • Emergency Room Treatment
  • Eye Injury
  • Fractures
  • Hospital Admission
  • Hospital Admission ICU
  • Hospital Confinement
  • Hospital Confinement ICU
  • Outpatient Therapy
  • Treatment Follow Up
  • Treatment Doctor's Office Initial
  • Treatment Urgent Care Initial
  • Wellness

Critical Illness

Group Critical Illness insurance is supported. Critical Illness plans are structured to include high-level plan data as well as a standardized set of the most common covered conditions.

To view the technical documentation, click here.

The following are the supported Benefit Fields for Critical Illness plans:

• Portability
• Premium Increase
• Exclusion Period
• Look Back Period
• Treatment Free Period
• Second Occurrence Suspension Period
• Rate Guarantee
• Insured Benefits
  • Employee
    • Minimum
    • Maximum
    • Increment
  • Spouse
    • Minimum
    • Maximum
    • Increment
  • Child
    • Minimum
    • Maximum
    • Increment
• Guaranteed Issue Bands
  • Minimum Group Size
  • Maximum Group Size
  • Employee
  • Spouse
  • Child
• Benefit Reduction Schedules
  • Age
  • Reduction Amount
• Benefits (Covered Conditions)
  • Invasive Cancer
  • Non Invasive Cancer
  • Heart Attack
  • Stroke
  • Kidney Failure
  • Organ Failure
  • Major Organ Transplant
  • Coronary Artery Disease
  • Coronary Artery Bypass Surgery
  • Coma
  • Loss of Sight
  • Loss of Hearing
  • Paralysis
  • ALS (Lou Gehrig's Disease)
  • Alzheimer's Disease
  • Addison's Disease

Hospital Indemnity

Group Hospital Indemnity insurance is supported. To view the technical documentation, click here.

The following are the supported Benefit Fields for Hospital Indemnity plans:

• Portability
• Premium Increase
• Exclusion Period
• Look Back Period
• Treatment Free Period
• Rate Guarantee
• ICU Admission Paid in Addition to Hospital
• ICU Confinement Paid in Addition to Hospital
• Benefits
  • Hospital Admission
  • Hospital Admission ICU
  • Hospital Confinement
  • Hospital Confinement ICU
  • Wellness

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

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

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.

One of the primary use-cases for the Ideon 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.

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

Premiums by Applicant

For markets other than small group, premiums are also returned at the level of individual applicants. If no Applicants are provided, the premiums_by_applicant field will be an empty array.

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. Additional state-funded subsidies are also applied if available and supported by Ideon's quoting engine.

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 total amount of the federal subsidy is returned in the premium_tax_credit field. This amount, along with any state-funded subsidies applied, is subtracted from the premium to calculate the premium_subsidized field for each plan.

Subsidy Calculation

Subsidy calculations are fully handled by the Ideon 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)

State-Funded Subsidy Programs

Ideon calculates additional state-funded subsidies for a selection of states. Currently, the Vermont Premium Assistance and New Jersey Health Plan Savings programs are supported. The amount of the state-funded subsidy is returned along with eligibility and the program name in the state_subsidy field. When applicable, this amount is applied to the premium_subsidized for each plan.

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 Ideon 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 Ideon 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 following example contains the required 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 following example contains the required 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": "2026-01-01"
}

To view the technical documentation, click here.

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.

At a very high level, here are the steps to getting set up to quote Groups using the Group Rating API:

1. Create the Group - a representation of the Employer and its office locations
2. Add the Census - add the members or employees, and their dependents. These are the members that will be quoted.
3. Create a Quote - let Ideon know what product line and effective date you want to quote the Group for.
4. View Group Rates - normalized for all product lines, Ideon returns the available rates for all quoted plans in one paginated endpoint.
5. View Member Rates - look into the details for a particular group rate to see what each Member in the Group costs.

• Loading Plan Data - The plan benefit schema varies by product line. We recommend using the Bulk Plans endpoint to cache plan benefit information in your system in order to provide a seamless experience for your users.

Create the Group

Creating a group is the first step in the Group Rating API. The endpoint 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

When creating a Group, you must 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
      ...
    }
  ]
}

Add 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. Additionally, Dependents with a type of child, adopted_child, sibling, foster_child, or step_child will be checked against the maximum dependent age for plans; other Dependent types will not.

Valid Dependent Relationships:

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

While all of the above dependent relationships are valid, some will filter out all or most plans for a quote since they are not allowed based on the business rules for the underlying insurance plans. Therefore, we recommend sticking to the following set:

• adopted_child
• child
• court_appointed_guardian
• disabled_child
• foster_child
• life_partner
• spouse
• step_child
• ward

POST

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

Create a Quote

At this stage, you've accomplished the following:

1. Create a Group
2. Add Members to the Group

Now you're ready to Create a Quote for the Group! The Group Rating API has support for:

• Medical (ACA)
• Medical (Level Funded)
• Dental
• Vision
• Life
• Long Term Disability
• Short Term Disability
• Accident
• Critical Illness
• Hospital Indemnity

Quoting different product lines is as simple as providing the appropriate product_line value in the request body. See the endpoint detail page for more details: Create a Quote.

The Group Rating API returns rates back in a standard format across all of the product lines listed above. However, the plan benefit schema varies by product line. We recommend using the Bulk Plans endpoint to cache plan benefit information in your system in order to provide a seamless experience for your users.

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

When there is a business rule that prevents one or more plan from being quoted, Ideon returned the information in the Limiting Factors endpoint for your system to easily deliver that information to users.

Retrieve Quote Attributes

Once you have created a Quote, you can retrieve the quote and its attributes.

The Quoting API is asynchronous for Level Funded Quotes. You can use the status field to poll until it is complete. Results are typically returned promptly. Speeds vary based on group size and plan availability.

GET /quotes/{id}

Response
{
  "quote": {
    "carrier_ids": [
      "12345"
    ],
    "commission_amount": 125,
    "contribution_percentage": 90,
    "created_at": "2026-01-01T12:00:00.000Z",
    "effective_date": "2026-01-01",
    "id": "5db8ce543d",
    "include_member_limited_plans": true,
    "market": "small_group",
    "npn": "123456789",
    "participation_percentage": 75,
    "product_line": "medical",
    "rating_method": "age_banded",
    "status": "complete",
    "voluntary": true
  }
}

Retrieve Aggregate Rates

Once a Quote has been run, 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",
      "claims_surplus_fraction": "1/3",
      "plan_id": "12345NY6789012",
      "stop_loss_amount": "25000.00",
      "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",
          "claims_fund": "1800.00",
          "fixed_costs": "1000.00",
          "total": "2800.00"
        },
        "disability": {
          "elimination_period": "8/8",
          "premium_bands": [
            {
              "employee": "0.95",
              "maximum_age": 20,
              "minimum_age": 0
            }
          ],
          "term": "long_term"
        },
        "life": {
          "child_rate": "0.10",
          "premium_bands": [
            {
              "employee": "0.05",
              "employee_tobacco": "0.05",
              "maximum_age": 20,
              "minimum_age": 0,
              "spouse": "0.05"
            }
          ]
        },
        "accidental_death_dismemberment": {
          "child": "0.03",
          "employee": "0.03",
          "spouse": "0.03"
        }
      }
    }
    ...
  ]
}

Level Funded rates are illustrative and will contain a claims_surplus_fraction, indicating the amount of surplus claims fund the employer could get back, a stop_loss_amount, and total monthly cost breakdown, where available, for 4_tier_composite rates. The total monthly cost breakdown includes a claims_fund amount, the amount of monthly premium that goes towards the claims fund, and fixed_costs, the amount of monthly premium that goes towards administrative fees, stop loss premiums, and other fixed costs.

Life plans display the monthly rate per $1,000 of benefit coverage selected by the member. If applicable, the accompanying accidental_death_dismemberment rates will be displayed also on a per $1,000 basis. If the plan requires that Accidental Death & Dismemberment coverage be attached to the plan, the final rate will be the sum of the two for each member.

Short Term Disability plans display the monthly rate per $10 of benefit coverage selected by the member. Long Term Disability plans display the monthly rate per $100 of benefit coverage selected by the member.

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

Composite Rate Methodology

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 Ideon 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 Ideon API will return standard age-banded Rates.

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

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

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

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

Using Plan Search

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

In Version 7 (Header: "Accept-Version": "v7"), the response will include the providers along with the particular addresses where they are in-network for each plan.

{
  "plans": [
    ...
    {
      ...
      "id": "12345NY1234567",
      "providers": [
        {
          "npi": 1234567890,
          "in_network": true,
          "addresses": [
            {
              "city": "New York",
              "id": "589c907f-28c2-3d14-8916-1144a5191ba2",
              "latitude": 45.55,
              "longitude": 14.55,
              "phone_numbers": [
                "2122223333",
                "9172223334"
              ],
              "state": "NY",
              "street_line_1": "123 Fake Street",
              "street_line_2": "Apt 10",
              "zip_code": "11215"
            }
          ]
        }
      ]
      ...
    }
}

In previous versions, the response will 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.

All endpoints are rate-limited per API key. The default limit is 150 requests per minute for most endpoints. Bulk and search endpoints may have lower per-minute limits.

When the limit is exceeded the API returns 429 Too Many Requests with a Retry-After header indicating seconds to wait before retrying. Every successful response includes X-RateLimit-Limit (your ceiling) and X-RateLimit-Remaining (requests left in the current window).

All API responses support gzip compression. Send Accept-Encoding: gzip to receive compressed responses — strongly recommended for large datasets such as Bulk Plans exports.

This API supports Cross-Origin Resource Sharing (CORS). The Access-Control-Allow-Origin: * header is returned on all responses, enabling browser-based clients to call the API directly.

Create and manage employer groups, their locations, and member census data. Groups are the starting point for all quoting workflows.