Retrieve Rates

Poll for quote complete status and access premiums for quoted plans

The "Display Rates" endpoint (API docs) can be used to poll for the completed status and retrieve premiums for quoted plans. The asynchronous processing of quotes - and thus the polling for quote status - is specific to v8. In lower versions, quotes are processed synchronously and the "Create a Quote" endpoint will return a complete status with a successful 201 response. For lower versions, the status polling step can be skipped.

Group rates for a quote, as returned in the "Display Rates" endpoint, are available to be retrieved for 18 months following the creation of the quote. Member and dependent rates for a quote, as returned in the "Display Member Rates" endpoint, are available to be retrieved for 6 months following the creation of the quote.

Polling for Quote Status

The quote status is returned in the meta object of the display rates endpoint response. There are currently three valid values:

• pending - the quote is in process and no rates have been returned.

• partially_complete - some, but not all, plans have been rated.

• complete - all available plans have either been rated, failed eligibility criteria, or encountered a quote error.

The asynchronous processing of quotes supports two primary integration methodologies: rates can be progressively loaded and presented to customers as they are available or loaded and presented in one phase when the quote is complete. For both methodologies, we recommend polling for status every 1-2 seconds.

Progressive Loading

In this context, progressive loading of rates is the process of, prior to full quote completion, pulling and displaying rates for plans that are successfully quoted to end users.

1. Poll for quote status through the display rates endpoint.

   1. The meta.status field indicates the quote status.

   2. The meta.total field counts the number of plans currently quoted.

2. If the status is partially_complete, pull rates for the total plans that have been quoted. The total field can be used in combination with pagination parameters to pull rates for only the plans that have been added throughout iterations of steps 1 and 2.

3. Repeat steps 1-2 until the status is complete, then ensure rates for all plans have been pulled.

Wait for Quote Completion

As an alternative to progressive loading, users can simply poll the status of the display rates endpoint until complete is returned. Once that condition is met, rates for all plans can be pulled. In this case, we recommend polling using the select parameter to limit the payload response time, through a GET /quotes/<quote.id>/rates?select=meta.status.

Retrieving Premiums for Quoted Plans

Premiums for quoted plans are returned in the display rates endpoint. The default pagination for this endpoint enforces a maximum of 25 results per page. When pagination parameters are included, up to 50 plans per page can be requested and returned.

By default, all available rating methodologies are included in the display rates response. Supported rating methodologies for medical group quoting are age_banded, 4_tier_composite, and adult_child_tier_composite. Given the variability in carrier support and regulation for the various methodologies, we recommend integrations to check for rates in all their corresponding objects. If rates for a methodology are not available, each of the nested keys will return null.

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 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 Idenfitiers section of the benefits grammar guides.

Member Limited Plans

Any member limited plans included in the quote can be identified in two ways. First, the member_limited key will be returned as true. Second, the members_quoted count for the plan will be less than the meta.total_members included in the group's census. To identify which members were ineligible for the quoted plan, see the Member and Dependent Rates section below.

Carrier Quote IDs

If a plan is quoted by a carrier's API, as could be the case for UHC plans for group medical, 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) to create a SAMx import link for efficient progression of the sold case and group application processes.

Member and Dependent Rates

Each quoted plan returned in the rates array has an identifier (id ) associated with it that is commonly referred to as the rate ID. This identifier is unique to the premiums quoted for the associated plan for the given quote. The rate ID can be used in the "Display Member Rates" endpoint (API docs) to look up the quoted premiums for the plan for each member and dependent, individually. Premiums for each member and their dependents are returned in separate objects in the member_rates array. Only members eligible for the plan, in the case of a member-limited plan being quoted, will be included in the member rates. Ineligible members can be identified by their omission from the array.