# Vision

A complete vision plan schema can be found in the Vision Plan Show endpoint ([API docs](https://docs.ideonapi.com/#vision-plans-vision-plans-get)). The latest available version, *v8*, must be specified in the request headers. Ideon's vision data is sourced directly from carriers and standardized into this data schema. Vision plans can be available across multiple years, defined uniquely by their `id`. 

This page is organized into sections to cover all data for vision plans, including their metadata and benefits. All sections are included on a single page to enable cmd+f searching based on schema keys or conventional terminology. Not all fields in the vision plan schema are included; those omitted are redundant or legacy fields. The navigation pane in the top-right of the page can be used to quickly jump between sections. 

## Plan Metadata

A plan's metadata includes all information that is not considered a cost share based benefit. Given the breadth of data included, format, and data type varies by metadata field. The below tables list all fields included in Ideon's vision plan dataset and summaries of how the data is presented.

### Plan Identifiers

The availability and structure of plan identifiers varies by carrier for vision plans. Most carriers have unique identifiers available as plan codes or numbered plans. These are included in the `identifiers` array and commonly referenced in the plan's `name` as well.

<table data-full-width="true"><thead><tr><th width="149.9918212890625">Metadata Field</th><th width="150.055419921875">API Schema Key</th><th width="100.34765625">Data Type</th><th width="200.1495361328125">Example</th><th>Notes</th></tr></thead><tbody><tr><td>Internal Ideon ID</td><td>id</td><td>string</td><td>"WQmui7Mi"</td><td>The unique ID for the plan, internal to Ideon's database.</td></tr><tr><td>Carrier-specific Identifiers</td><td>identifiers[type="issuer_internal_id"].value</td><td>string</td><td>"SF049"</td><td>The identifier(s) used by the carrier to reference the plan. One or more identifiers with the same or different <code>type</code> can be included for a single plan. Identifiers with a <code>type</code> of <em>plan_scraper_key</em> should be ignored. </td></tr></tbody></table>

### Carrier Information

<table data-full-width="true"><thead><tr><th width="149.981201171875">Metadata Field</th><th width="149.50140380859375">API Schema Key</th><th width="99.9853515625">Data Type</th><th width="199.6097412109375">Example</th><th>Notes</th></tr></thead><tbody><tr><td>Carrier Info - ID</td><td>carrier.id</td><td>string</td><td>"d31dc8f5-00bd-422d-bcb3-44caa4227b38"</td><td>Unique identifier for the carrier, consistent across Ideon's Quote and Select data.</td></tr><tr><td>Carrier Info - Name</td><td>carrier.name</td><td>string</td><td>"Humana"</td><td>The carrier's brand or marketing name.</td></tr><tr><td>Carrier Info - Logo URL</td><td>carrier.logo_url</td><td>string</td><td>"https://d1hm12jr612u3r.cloudfront.net/images/logos/353/thumb.png?1724342730"</td><td>Carrier logos are presented in thumb size by default. To access a higher resolution image, replace "thumb" in the URL with "medium".</td></tr><tr><td>Carrier Info - Issuer ID</td><td>carrier.issuer_id</td><td>string</td><td>"A0001"</td><td>The Ideon-generated issuer ID for the carrier. For vision plans, there is a one to one relationship between a carrier and the issuer ID.</td></tr><tr><td>Carrier Disclaimers</td><td>carrier_disclaimers</td><td>string</td><td>"For all Principal plans, only one plan, per group, can be selected."</td><td>Disclaimers are open-text strings that pass through important information from the carrier. They are only used when the disclaimer is specifically requested to be included by the carrier providing the data. Disclaimers are typically between 50 - 500 characters. Rarely, they can exceed 1,000 characters in length.</td></tr></tbody></table>

### Additional Metadata

<table data-full-width="true"><thead><tr><th width="150.43927001953125">Metadata Field</th><th width="149.96307373046875">API Schema Key</th><th width="99.5167236328125">Data Type</th><th width="200.2027587890625">Example</th><th>Notes</th></tr></thead><tbody><tr><td>Plan Name</td><td>name</td><td>string</td><td>"VSP Choice Plan #1"</td><td>The name of the plan as detailed in carrier documentation.</td></tr><tr><td>Benefits Summary Document</td><td>benefits_summary_url</td><td>string</td><td>"https://d2ed110nmrd591.cloudfront.net/blobs/jstaFtGGzy17S5c8CsNs7LEJ.pdf"</td><td>The benefit summary documents that ancillary carriers provide will be available via this link; document structure will vary by carrier.</td></tr><tr><td>Quoted via Carrier's API</td><td>quoted_via_carrier_api</td><td>boolean</td><td>true or false</td><td>Indicates whether or not the plan is quoted in real-time through an integration to the carrier's API (indicated by <em>true</em>). Plans with a <em>false</em> value in this field are quoted by Ideon's rating engine.</td></tr></tbody></table>

## Service Frequency

The service frequency defines how often a member is eligible to receive a given vision benefit — for example, an eye exam once per year or new frames once every two years. These are included in the `service_frequency` object, with keys for `exams`, `lenses`, `frames`, and `contacts`. The grammar for this field is "X {item/exam}(s) per X {month/year}(s)". For example, the service frequency for contacts is commonly *1 item(s) per 12 month(s)*.&#x20;

## Exam and Materials Copays

Exam and Materials Copays are the fixed out-of-pocket amount a member pays for exam visits or the purchases of vision materials, such as eyeglass lenses. These copays are typically represented as summary values in carrier documentation and are included in Ideon's schema as `exam_copay` and `materials_copay`. In most cases, they will match the detailed plan benefits as seen in the `benefits` object. Most commonly these will be represented as single values in the "$X" format; for example, *$20*. In rare cases, a range of values will be shown if carrier plan documentation does not show a consistent amount; for example, *$10-$30*.&#x20;

## Plan Benefits

Plan benefits are presented as the cost share the plan enrollee is responsible for. Data for each benefit includes the cost shares for seeing In-Network and Out-of-Network providers as well as any limitations on usage. The fillings benefit below shows an example of how this might be presented.

```json
"eye_exam": {
    "in_network": "$20",
    "out_of_network": "$50 allowance",
    "limit": "1 exam(s) per year"
}
```

For grammar formats and notes, the most common use cases are included. This is not an exhaustive list of all cost share and limit formats; values not listed here are rarely used to handle edge case scenarios. Tiered in-network benefits, as described for Medical plans in the [Tiered Medical Benefits section](/quote-and-select/additional-information-and-workflows/benefit-grammar-guides/medical.md#tiered-plan-benefits), are very rarely used for Vision plans.

### Cost Share Formats

Benefit cost shares, presented in the `in_network` and `out_of_network` keys in the plan response, are represented as the cost share the plan enrollee is responsible for. For example, if the cost share is presented as *20%*, the enrollee is responsible for 20% of the service cost while the plan will pay 80%. The most common cost share formats are included in the table below.

<table data-full-width="true"><thead><tr><th width="181.1484375">Cost Share Format</th><th width="148.28515625">Structure</th><th width="145.50390625">Example</th><th>Notes</th></tr></thead><tbody><tr><td>Standard Copay</td><td>$X</td><td>$25</td><td>A $0 copay indicates the carrier documentation presents the benefit as a $0 copay or a 0% coinsurance.</td></tr><tr><td>Copay Range</td><td>$X-$Y</td><td>$10-$50</td><td>When multiple or a range of copays are shown for a benefit in a single tier, the range of values is shown.</td></tr><tr><td>Standard Coinsurance</td><td>X%</td><td>20%</td><td>Coinsurances for plan benefits are presented as the cost to the enrollee.</td></tr><tr><td>Allowance Benefits</td><td>$X allowance<br>X% after $Y allowance</td><td>$50 allowance<br>100% after $100 allowance</td><td>The enrollee is provided a lump sum allowance by using that plan's benefit and can use it throughout the plan year or until the allowance amount is reached. <br><br>When <em>$X allowance</em> is used, it is implied that the enrollee is responsible for 100% of costs after the allowance amount is reached.</td></tr><tr><td>Reimbursement (Out-of-Network)</td><td>up to X reimbursement</td><td>up to $100 reimbursement</td><td>Indicates that the member may be eligible for reimbursement of expenses associated with the service or material. Typically used for out of network benefits.</td></tr><tr><td>Discounts Available</td><td>discounts available</td><td>discounts available</td><td>Indicates that there may be discounts available for the service or material that are not categorized as a typical cost share benefit.</td></tr><tr><td>Not Covered</td><td>Not Covered</td><td>Not Covered<br>not covered</td><td>This denotes a benefit that is not covered by a plan - the enrollee is responsible for all costs. </td></tr><tr><td>Not Included in Carrier Documentation</td><td>null<br>not in plan design</td><td>null<br>not in plan design</td><td>This indicates that the benefit is not specified nor implied in the carrier's plan benefit documentation.</td></tr></tbody></table>

### Limit Formats

Benefit limits are included where applicable to detail standardized limitations or additional details for the benefit's cost shares. The most common limit formats are included in the table below.&#x20;

<table data-full-width="true"><thead><tr><th width="181.1484375">Limit Format</th><th width="148.28515625">Structure</th><th width="145.50390625">Example</th><th>Notes</th></tr></thead><tbody><tr><td>Standard Limit</td><td>X {measured service}(s) per {time period}</td><td>1 exam(s) per year<br>2 item(s) per 36 month(s)</td><td>For most benefit limitations, the {measured service} is an item or exam. The {time period} is typically months or years.</td></tr><tr><td>Discounts Available</td><td>discounts available</td><td>discounts available</td><td>Indicates that there may be discounts available for the service or material that are not categorized as a typical cost share benefit. When used as a limit, these discounts are documented separately from the cost shares presented.</td></tr><tr><td>Documentation Reference</td><td>see carrier documentation for more information</td><td>see carrier documentation for more information</td><td>The documentation reference limit is included when important information is included in the SBC or other carrier document for the benefit that is non-standardizable. This is most commonly used in cases in which the additional information could impact the amount the enrollee would pay for the benefit. This limit is also commonly used when visit limits are aggregated with other benefits.</td></tr><tr><td>No Limit Included</td><td>null</td><td>null</td><td>If no limit is included for the benefit, the limit string will return null.</td></tr></tbody></table>

### Benefits by Field

The below table includes a list of all supported benefit fields in Ideon's plan schema, ordered alphabetically by API Schema Key.&#x20;

<table data-full-width="false"><thead><tr><th width="349.6558837890625">Benefit Field</th><th width="349.949951171875">API Schema Key</th></tr></thead><tbody><tr><td>Additional Pairs of Eyeglasses</td><td>additional_pairs_of_eyeglasses</td></tr><tr><td>Contact Lenses - Conventional</td><td>contact_lenses_conventional</td></tr><tr><td>Contact Lenses – Disposable</td><td>contact_lenses_disposable</td></tr><tr><td>Contact Lenses – Medically Necessary</td><td>contact_lenses_medically_necessary</td></tr><tr><td>Eye Exam</td><td>eye_exam</td></tr><tr><td>Frame</td><td>frame</td></tr><tr><td>Eyeglass Lenses – Bifocal</td><td>eyeglass_lenses_bifocal</td></tr><tr><td>Eyeglass Lenses – Lenticular</td><td>eyeglass_lenses_lenticular</td></tr><tr><td>Eyeglass Lenses – Single Vision</td><td>eyeglass_lenses_single_vision</td></tr><tr><td>Eyeglass Lenses – Trifocal</td><td>eyeglass_lenses_trifocal</td></tr><tr><td>Laser Vision Correction</td><td>laser_vision_correction</td></tr><tr><td>Photochromatic Lenses</td><td>photochromatic_lenses</td></tr><tr><td>Polarized Lenses</td><td>polarized_lenses</td></tr><tr><td>Premium Anti-Reflective Coating</td><td>premium_antireflective_coating</td></tr><tr><td>Premium Contact Lens Fit &#x26; Follow-Up</td><td>premium_contact_lens_fit_and_follow_up</td></tr><tr><td>Premium Progressive Lenses</td><td>premium_progressive_lenses</td></tr><tr><td>Retinal Imaging</td><td>retinal_imaging</td></tr><tr><td>Standard Anti-Reflective Coating</td><td>standard_antireflective_coating</td></tr><tr><td>Standard Contact Lens Fit &#x26; Follow-Up</td><td>standard_contact_lens_fit_and_follow_up</td></tr><tr><td>Standard Polycarbonate Lenses (Adult)</td><td>standard_polycarbonate_lenses_adult</td></tr><tr><td>Standard Polycarbonate Lenses (Child)</td><td>standard_polycarbonate_lenses_child</td></tr><tr><td>Standard Progressive Lenses</td><td>standard_progressive_lenses</td></tr><tr><td>Standard Scratch Resistance</td><td>standard_scratch_resistance</td></tr><tr><td>Tint</td><td>tint</td></tr><tr><td>UV Coating</td><td>uv_coating</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ideonapi.gitbook.io/quote-and-select/additional-information-and-workflows/benefit-grammar-guides/vision.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.