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, v8, or v9, which can be accessed using the Accept-Version header. For each endpoint, we will indicate in the documentation which version(s) are available.

v9 is the current version for Small Group Medical group quoting — Create a Quote, Show a Quote, and Display Rates. It introduces structured plan_filters and outputs on the quote request, per-carrier progress in carrier_results, and group- and member-level eligibility exceptions returned inline with rates (quote_exceptions and member_exceptions) in place of the standalone Limiting Factors endpoint.

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.

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

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.

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 the set of Benefits available to its purchaser. Plans are exposed across nine product lines — Major Medical (ACA), Medicare Advantage, Dental, Vision, Life, Disability, Accident, Critical Illness, and Hospital Indemnity — each accessible through dedicated search and show endpoints under the Plan Lookup tag group.

Major Medical

Major Medical plans are the ACA-compliant individual and small-group plans regulated by CMS. Benefits cover the full range of essential health benefits — primary care visits, specialist visits, hospitalization, pharmacy, mental health, preventive care, and so on. Each benefit can carry in-network and out-of-network cost shares (copays, coinsurance), and deductibles and out-of-pocket maximums are tracked at both the individual and family level. Plans are categorized by metal level (Bronze, Silver, Gold, Platinum, Catastrophic) and plan type (HMO, PPO, EPO, POS), and they're rated by CMS-defined Rating Areas.

Medicare Advantage

Medicare Advantage plans are private alternatives to Original Medicare, regulated by CMS. They typically include the same core hospital and medical coverage as Original Medicare, often bundle prescription drug coverage (MAPD plans), and frequently add supplemental benefits like dental, vision, hearing, fitness, and over-the-counter allowances. Plan types include HMO, PPO, PFFS, SNP (Special Needs Plans), and MSA. PDP (Prescription Drug Plans), which provide drug coverage standalone alongside Original Medicare, are also returned through the Medicare Advantage endpoints.

Benefit Grammar

Benefit field definitions, including how cost-share values are structured for each product line, are documented in the Benefit Grammar Guides on the Ideon integration guides site. The grammar guides are the authoritative reference for parsing benefit values returned from the API across all nine product lines.

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.

Individual Quotes return available plans for a household or single applicant in either the Individual ACA market or the Medicare Advantage market. Quotes are generated synchronously in a single API call — no group setup, no asynchronous job, no polling. Submit the request, receive plans, premiums, benefits, and (when applicable) subsidy calculations in the response.

ACA Major Medical. Search Major Medical Plans is the entry point. The required inputs are minimal — a zip_code, fips_code, market (individual or small_group), and an applicants array — and the response returns all available plans with their premiums and benefits for the household. When household_income and household_size are supplied, federal Premium Tax Credits and state-funded subsidies (currently Vermont Premium Assistance and New Jersey Health Plan Savings) are calculated automatically and reflected in each plan's premium_subsidized. CSR plan variants are included when applicants are eligible.

Medicare Advantage. Search Medicare Advantage Plans is the entry point for Medicare. Inputs are simpler than ACA — Medicare Advantage premiums aren't rated by household demographics, so only zip_code, fips_code, and enrollment_date are required. The response returns Medicare Advantage (MA), Medicare Advantage with Prescription Drug coverage (MAPD), and standalone Prescription Drug Plans (PDPs) available in the location.

Shop by Doc. Both ACA and Medicare Advantage quote endpoints support inline evaluation of provider participation. Pass a providers array — each entry an NPI optionally paired with an address_id from Provider Search — and each returned plan carries a providers array indicating in-network status and qualifying addresses for every provider. The two-step workflow (Provider Search → quote with providers) is documented in detail on each endpoint's Shop by Doc sub-section.

Shop by Drug (ACA only). The ACA Major Medical endpoint supports inline formulary coverage checks. Pass a drug_packages array — entries reference drugs by NDC Package Code (id) or Med ID (med_id) from Drug Search — and the response includes a coverages array with formulary tier, prior authorization, quantity limit, and step therapy details for each drug on each plan. Shop by Drug is not currently supported on Medicare Advantage.

For complete request and response references, see the individual endpoint documentation under Quote – Individuals. For the full integration narrative — recommended UX patterns, identifier selection, error-handling, and renewal flows — see the Quote and Select integration guide.

Group Quotes return available plans and rates for an employer group's full census in a single asynchronous workflow. Unlike Individual Quotes, group quoting is multi-step: the group and its members are persisted as first-class resources, the quote runs as a background job, and results are retrieved through dedicated rate endpoints once processing is complete. This pattern scales to groups of thousands of members where running synchronous per-applicant quotes wouldn't be practical.

The current version of group quoting is v9 for Small Group Medical and ICHRA. Earlier versions (v6, v7, v8) remain accessible for backward compatibility.

The v9 Small Group Medical workflow.

1. Create the group. Create a Group registers the group with its situs (zip_code, fips_code), effective_date, sic_code, broker identifiers, and other census metadata. Returns a group id used downstream. For v9, company_tax_id and at least one of broker_npn or agency_npn are required.

2. Add the members. Create Members submits the census — each member with their age, gender, tobacco status, location, dependents, and any fields required by optional calculations (e.g. household_income for PTC subsidies, safe_harbor_income for ICHRA affordability).

3. (Optional) Attach supplemental data. Create Supplemental Data lets clients attach structured group-level context that influences carrier-specific quoting logic — for example, prior plan history, group size segmentation, or industry-specific attributes.

4. Create the quote. Create a Quote initiates the asynchronous quoting job. The request body controls the scope of the quote — calculations enables optional outputs like PTC subsidies and CSR eligibility, plan_filters narrows the carriers/networks/metal levels considered, and outputs enables ancillary deliverables like applicant-level premium breakdowns and bulk export files. The response returns a quote id and an initial pending status.

5. Poll for completion. Show a Quote reports current job status. Poll until status reaches a terminal state — complete, complete_with_errors, or failed.

6. Retrieve results. Three retrieval shapes:

   • Display Rates returns paginated rates for every member in the group (best for groups up to ~1,000 members).
   • Display Member Rates returns rates for a single member by id (best for selective retrieval).
   • The bulk export file (if outputs.bulk_export_file.enabled was set at quote creation) delivers a JSONL file of all member results (best for groups above ~1,000 members).

Show Limiting Factors returns plan-level and member-level exception codes explaining why specific carriers, plans, or members didn't appear in results — used to diagnose unexpectedly thin quote results. Exception code reference is documented in the Quote and Member Exception Codes section of the integration guide.

ICHRA quoting has its own dedicated workflow under Quote – ICHRA. The structure mirrors Small Group Medical (group → members → asynchronous quote → poll → retrieve), but the quote runs against the individual market on a member-by-member basis and supports ICHRA-specific calculations (minimum employer contribution, affordability against safe harbor and FPL). See the Quote – ICHRA section for the full ICHRA workflow.

Quote proposals. Create Quote Proposal generates a branded, customer-facing PDF proposal from a completed quote. Useful for broker-driven workflows where the deliverable to the end client is a document rather than a UI.

For complete request and response references, see the individual endpoints under Quote – Groups. For the integration narrative — recommended workflows for Small Group Medical, Level Funded, and ICHRA — see the Quote and Select integration guide.

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

Ideon's provider-network dataset powers two primary workflows: Shop by Doc (provider-driven quote shopping) and Care Navigation (in-network provider lookup against a known plan or network). Both are served by a single endpoint, Provider Search — the distinction is whether the request includes network_ids or plan_ids to scope results to in-network providers.

Shop by Doc is the workflow where an end user names the doctors they want to keep, and the system surfaces plans those doctors participate in. The two-step pattern: use Provider Search (without network filters, with a provider_name_search and geography) to identify the user's providers and capture their NPIs and address IDs, then pass those identifiers in the providers array on a quote endpoint (Search Major Medical Plans for individuals, Create a Quote for groups). Each returned plan carries a per-provider in-network indicator and the qualifying addresses where they're in-network.

Care Navigation is the inverse — the plan or network is already known, and the user is searching for in-network providers they could see. Submit Provider Search with network_ids (from Network Search) or plan_ids (HIOS IDs, Medicare contract codes, or Ideon plan IDs), plus geography (zip_code, center_point, or polygon) and any clinical filters (specialty_ids, type, accepts_insurance). The response carries a networks array on each provider detailing in-network status per network and a nested addresses array for each network containing only the addresses where the provider is in-network.

Optional analytical layers. Provider Search supports two entitlement-gated premium fields that add signal to results:

• Address Confidence Scores — ML-derived classifications (high, medium, low) indicating how likely a provider is actually practicing at a given address. Available for individual providers only (not organizations or hospitals). Recommended for filtering low-confidence addresses out of user-facing lists.
• HealthCorum Quality Scores — claims-based provider quality metrics (Appropriateness, Cost, Effectiveness, Overall, each on a 1.0–5.0 scale).

See the Provider Search endpoint documentation for the full request/response reference, including the Shop by Doc, Address Confidence Scores, HealthCorum Quality Scores, and Ranking and Sorting sub-sections.

A network is the carrier-side construct that defines which providers a plan covers in-network. Networks are referenced indirectly through plans most of the time — a quoted plan's network ID is what feeds Provider Search for Care Navigation — but for Large Group Medical, Medicaid, and other markets where plans aren't pre-mapped to networks in the Ideon dataset, networks are resolved directly through Network Search.

A network's metadata describes both its applicability and its coverage: lines_of_coverage (medical, medicare_advantage, medicaid) and markets (individual, small_group, large_group) define the product lines and segments the network serves, and state_codes lists the states where the network has either a plan mapping or sufficient provider data. A single network can serve multiple product lines and markets.

For directed network discovery, combine line_of_coverage, market, carrier_id, and search_term. Carrier IDs are obtained from Carrier Search. If a known network isn't surfacing with all four filters in play, drop search_term first — it's the most restrictive filter and often over-narrows when carrier and product context are already specified.

Display a Network returns the full record for a single network by id, useful when a network identifier is already known and full metadata is needed.

Three additional Networks endpoints support analytical workflows on top of network identification:

• Compare Multiple Networks — measures provider overlap between two or more networks. Used in network selection workflows to evaluate the disruption impact of switching between carriers.
• Disruption Analysis — the inverse of network comparison. Given a list of providers, returns network-level statistics on how many of those providers participate in each network. Used to evaluate which networks best cover a group's existing providers.
• Network Sizes and State Network Sizes — return provider counts for one or more networks, optionally filtered by geography or specialty. Used for adequacy comparisons and multi-state coverage summaries.

For the complete field-level reference on provider records and network data, see the Provider Data Dictionary on the integration guides site.

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

Create asynchronous group quotes and retrieve rates and plan availability for small group and level-funded markets.