> For the complete documentation index, see [llms.txt](https://ideonapi.gitbook.io/quote-and-select/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ideonapi.gitbook.io/quote-and-select/quote-groups/small-group-medical/retrieve-premium-and-eligibility-results.md).

# Retrieve Premium and Eligibility Results

The Display Rates endpoint ([API docs](https://docs.ideonapi.com/#tag/Group-Quoting/operation/showGroupRates)) can be used to retrieve premiums and eligibility exceptions for quoted plans. The latest version of this endpoint is v9, which is documented on this page. Polling for quote completion is documented in the [Monitor Quote Progress section](/quote-and-select/quote-groups/small-group-medical/monitor-quote-progress.md).

In v9, all plans for which the group is within the service area are returned in this response. Plans with group- or member-level eligibility issues are returned alongside premiums as `quote_exceptions` and `member_exceptions` on each plan, rather than being separated into a standalone limiting factors endpoint. The endpoint provides all information available for each plan; plan results may include premiums and/or exceptions.

{% hint style="info" %}
**Quote Retention Policy**\
For any created quote (regardless of effective date), data associated with that quote is retained for a set time period. In other words, rates associated with a quote created on a given day can be accessed via the following endpoints for the specified amount of time.

\>> Group Rates (GET /quotes/:quote\_id/rates): 18 months after quote creation date.

\>> Member Rates (GET /rates/:rate\_id/member\_rates): 6 months after quote creation date.
{% endhint %}

## Retrieving Quote Results

Premiums and exceptions for applicable plans are returned in the `rates` array of the Display Rates response. Each object in the array represents a single plan and will always include plan identifiers. Premiums for all available rating methodologies and/or quote or member exceptions flagged for the plan will also be included. In v9, it's possible for plans to be included in the `rates` array without any premiums — this indicates that the group was in the plan's service area, but Ideon was unable to quote premiums due to a quote exception.

The `meta.status` field in the response indicates the overall status of the quote at the time of the request, consistent with the `job.status` returned by the Show Quote endpoint. The `meta.total` field indicates the total number of plans currently available in the response.

The response supports the following query parameters for filtering the returned plans. These can be combined to narrow results for a given request.

* **Carrier ID** `carrier_id` - filters results to plans for the specified carrier brand ID.
* **Issuer ID** `issuer_id` - filters results to plans for the specified issuer ID.
* **Plan ID** `plan_id` - filters results to a specific plan, as returned in the `rates` array.
* **Quote Exception** `quote_exception` - boolean. Setting to *true* returns only plans with one or more objects in the `quote_exceptions` array. Setting to *false* returns only plans with no quote exceptions.
* **Member Exception** `member_exception` - boolean. Setting to *true* returns only plans with one or more objects in the `member_exceptions` array. Setting to *false* returns only plans with no member exceptions.

Setting both `quote_exception` and `member_exception` to *true* returns all plans with one or more quote exceptions and/or one or more member exceptions.

### Plan Identifiers

Each quoted plan object in the `rates` array will include a `plan_id`. For medical quoting, this identifier will be the plan's HIOS ID, and can be used to tie the plan rates back to the benefits package cached in the Cache Plan Benefits step. Further identifiers are included in the `identifiers` array, although these will be consistent with the same identifiers in the benefits package, documented in the [Plan Identifiers section](/quote-and-select/additional-information-and-workflows/benefit-grammar-guides/medical.md#plan-identifiers) of the benefits grammar guides.

### Carrier Quote IDs

If a plan is quoted by a carrier's API, as is the case for UHC plans for group medical quoting, a `carrier_quote_id` will be returned. This is the identifier returned from the carrier's API to reference the specific quote. For UHC, this can be referenced in the Create Quote Proposal endpoint ([API docs](https://docs.ideonapi.com/#quote-proposals-quote-proposals-post)) to create a SAMx import link for efficient progression of the sold case and group application processes.

## Quote Premiums

By default, all available rating methodologies are included in the response. The `premium_types_quoted` array on each plan indicates which methodologies were quoted for that plan. For each rating methodology included in the `premium_types_quoted` array, a corresponding object with the same name will be included in the `premiums` object. If premiums are unable to be quoted for the plan due to a quote exception, both the `premium_types_quoted` array and `premiums` object will be empty.

Supported rating methodologies for medical group quoting are *age\_banded*, *2\_tier\_composite*, *3\_tier\_composite*, *4\_tier\_composite*, and *adult\_child\_tier\_composite*. Each methodology returns its premiums in a consistent structure.

* **Age Banded** `premiums.age_banded` - returns the total premium for members, the total premium for dependents, and a sum total across both. If the `complete_age_bands` output was enabled in the quote request, the full 0–65 age banded premiums for the plan are included here.
* **Tier Composite** `premiums.2_tier_composite`, `premiums.3_tier_composite`, `premiums.4_tier_composite` - return premiums for each of the plan's composite tiers as well as a total premium based on the group's census. Tier structures vary by rating methodology.
* **Adult/Child Tier Composite** `premiums.adult_child_tier_composite` - returns a per-adult premium, a per-child premium, and a total premium based on the group's census.

The relevant portion of the Display Rates response for a quoted plan that supports age-banded and 4-tier composite premiums is included below as a sample:

{% code title="GET /quotes/\<quote.id>/rates" %}

```json
{
  "rates": [
    {
      // Plan identifiers,
      "premium_types_quoted": [
        "age_banded",
        "4_tier_composite"
      ],
      "premiums": {
        "age_banded": {
          "total_member": "100.00",
          "total_dependent": "100.00",
          "total": "100.00",
          "complete_age_bands": null
        },
        "4_tier_composite": {
          "employee_only": "100.00",
          "employee_plus_spouse": "100.00",
          "employee_plus_children": "100.00",
          "employee_plus_family": "100.00",
          "total": "100.00"
        }
      }
      // quote_exceptions array (if applicable), 
      // member_exceptions array (if applicable)
    }
  ]
}
```

{% endcode %}

### Member and Dependent Rates

The Display Member Rates endpoint ([API docs](https://docs.ideonapi.com/#group-quoting-group-quoting-get-3)) can be used to look up quoted premiums for each member and their dependents. This endpoint requires a rate ID, which is available for each quoted plan returned in the `rates` array in the `id` field. This identifier is unique to the premiums quoted for the associated plan for the given quote. Premiums for each member and their dependents are returned in separate objects in the `member_rates` array.&#x20;

### Level Funded Premiums

Level Funded plans follow the same response structure documented above, with additional carrier-specific details returned in `premiums.level_funded`. See the [Level Funded section](/quote-and-select/quote-groups/level-funded.md) for details.

## Quote Exceptions

The `quote_exceptions` array contains an object for each group-level eligibility issue or quoting error flagged for the plan. Quote exceptions are validations that impact the group as a whole and not specific members. Each plan can have multiple quote exceptions flagged simultaneously — for example, both a group size restriction and a SIC code ineligibility.

{% hint style="info" %}
A complete summary of valid quote exceptions and their associated error messages can be found in the [Quote and Member Exception Codes section](/quote-and-select/quote-groups/quote-and-member-exception-codes.md).
{% endhint %}

Each object in the `quote_exceptions` array includes the following fields:

* **Code** `code` - the standardized exception code. A complete catalogue of quote exception codes can be found in the API documentation.
* **Source** `source` - an enum indicating the system that flagged the exception.
  * *carrier\_api* - the exception was flagged based on an error or code returned by the carrier's API.
  * *ideon\_business\_rules* - the exception was flagged by Ideon's business rule logic.
  * *ideon\_rating\_engine* - the exception was flagged because the group or census data did not match the rating algorithm in the carrier's source documentation, preventing premiums from being evaluated.
* **Quote Impacted** `quote_impacted` - boolean indicating whether the exception prevented premiums from being quoted for the plan.
  * *false* - the plan still has one or more premium types quoted. The exception did not limit the ability to quote premiums for the group.
  * *true* - the plan does not have any premiums quoted. The exception prevented premiums from being retrieved for the group. The `premium_types_quoted` array and `premiums` object will both be empty.
* **Message** `message` - a plain-language message describing the exception, constructed based on the code, business rule data, and quote data.
* **Carrier API Error Messages** `carrier_api_error_messages` - an array of all error messages returned by the carrier's API. Only included for quote exceptions with a `code` of *carrier\_api\_error*.&#x20;

The relevant portion of the Display Rates response for a quoted plan with quote exceptions:

{% code title="GET /quotes/\<quote.id>/rates" %}

```json
{
  "rates": [
    {
      // Plan identifiers,
      // rates array,
      "quote_exceptions": [
        {
          "code": "in_state_percentage_minimum",
          "source": "ideon_business_rules",
          "quote_impacted": false,
          "message": "..."
        },
        {
          "code": "carrier_api_error",
          "source": "carrier_api",
          "quote_impacted": true,
          "message": "...",
          "carrier_api_error_messages": [ "...." ]
        }
      ]
      // member_exceptions array (if applicable)
    }
  ]
}
```

{% endcode %}

## Member Exceptions

The `member_exceptions` array contains an object for each member who has one or more eligibility issues flagged for the plan. Member exceptions are validations that flag specific members and not the group as a whole. Premiums for the member and their dependents are still returned alongside the exception — member exceptions do not prevent premiums from being quoted.

{% hint style="info" %}
The premiums for any member(s) with member exceptions flagged are included in the group's total premium returned in the higher-level premiums object (`rates[].premiums`). Member-level premiums for member(s) with exceptions are included in the member\_exceptions array (`rates[].member_exceptions[].premiums`) to enable easy access to calculate group premiums with these members omitted, if desired.

Additionally, a complete summary of valid quote exceptions and their associated error messages can be found in the [Quote and Member Exception Codes section](/quote-and-select/quote-groups/quote-and-member-exception-codes.md).
{% endhint %}

Each object in the `member_exceptions` array includes the following fields:

* **Member ID** `member_id` - the internal Ideon ID for the member, as returned in the Create Members endpoint.
* **Member External ID** `member_external_id` - the user-supplied external ID for the member, if one was provided when the member was added to the census.
* **Premiums** `premiums` - the member-level premium breakdown across rating methodologies for the plan. Only methodologies quoted for the plan are included. The structure of this object is consistent with the premiums returned at the plan level.
* **Exceptions** `exceptions` - an array of eligibility exceptions flagged for the member. Each exception in this array includes:
  * **Code** `code` - the standardized exception code. The codes that can surface as member exceptions are a subset of the full exception code catalogue.
  * **Source** `source` - the system that flagged the exception. Member exceptions are currently only sourced from *ideon\_business\_rules*.
  * **Message** `message` - a plain-language message describing the exception.
  * **Dependent Exceptions** `dependent_exceptions` - an array of dependent `id` values, identifying which of the member's dependents triggered the exception, if applicable. For example, a `dependent_age_maximum` exception will include the `id` of each dependent that exceeds the plan's maximum age. For member-level exceptions that do not apply to specific dependents, such as a member location exception, this array will be empty.

The relevant portion of the Display Rates response for a quoted plan with member exceptions:

{% code title="GET /quotes/\<quote.id>/rates" %}

```json
{
  "rates": [
    {
      // Plan identifiers,
      // rates array,
      // quote_exceptions array (if applicable),
      "member_exceptions": [
        {
          "member_id": "zxcv4321",
          "member_external_id": "001",
          "premiums": {
            // Member-level premiums by rating methodology,
          },
          "exceptions": [
            {
              "code": "dependent_age_maximum",
              "source": "ideon_business_rules",
              "message": "...",
              "dependent_exceptions": [
                "bee83536cf-8dd5aa0"
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

{% endcode %}