> For the complete documentation index, see [llms.txt](https://even-financial.gitbook.io/developer-center/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://even-financial.gitbook.io/developer-center/marketplace-integrations/native-api/auto-insurance/ui-design-guide.md).

# UI Design Guide

## Offer Card Components & Display Logic

This section explains how Engine uses [fields returned by the Auto Insurance API](https://app.gitbook.com/o/-MeMv7LjIzSN9jTk7lWl/s/-MeMvVDbjd8vJWZ9Hwf0/~/edit/~/changes/388/marketplace-integrations/native-api/auto-insurance/api-reference/~/comments#offer-fields) to display offer card components. Use the logic below as reference for your UI implementation. 

<figure><img src="/files/bprES5JgttVMfYMfWfzl" alt=""><figcaption></figcaption></figure>

### Offer Card Ranking

* Use the `rank` field to order offers for display, in ascending order - the offer with `"rank": 1` should be displayed first.
* Only display offers where `"status": "active"`.

{% stepper %}
{% step %}

#### Carrier or partner logo

Display `financialInstitutionImageUrl` at the top of the offer card.
{% endstep %}

{% step %}

#### Headline

Use `headline` as the primary marketing message.
{% endstep %}

{% step %}

#### Marketing bullets

Display 3–4 checkmark bullet points from `descriptionPoints` beneath the headline.
{% endstep %}

{% step %}

#### Carrier or partner name

Use `financialInstitutionDisplayName` for accessibility labeling. Show it as supporting text where space allows.
{% endstep %}

{% step %}

#### View Rate CTA

Use `url` when `isMonetized` is true. Use `unmonetizedUrl` when the offer should not be tracked for monetization.

Open every click in a new tab.
{% endstep %}

{% step %}

#### Impression tracking

Fire each URL in `impressionTrackingPixelUrls` once when the card is rendered or viewed.
{% endstep %}
{% endstepper %}

## Impression Tracking

Each offer may include one or more URLs in `impressionTrackingPixelUrls`.

* These must be requested (e.g., via a 1x1 tracking pixel or background GET request) at the moment the corresponding offer card becomes visible to the user.

{% hint style="danger" %}
Failing to fire these pixels can result in inaccurate reporting and may affect a partner's ability to receive credit for the impression.
{% endhint %}

## UI Flow Design Guide

### Compare / Offers Page Layout

After the offer search generates a rate table, show available offers on a compare page.

* **Header:** Partner page header, showing the partner’s logo and an Engine “Powered by” logo, consistent with the rest of the flow.&#x20;
* **Title block:** A title such as “Your auto insurance matches are ready,” with the Advertiser Disclosure link right-aligned on the same row.&#x20;
* **Subtitle:** A supporting line such as “Compare personalized options from trusted providers and get your free quote.”&#x20;
* **Offer cards:** Each card shows the carrier/partner logo (financialInstitutionImageUrl), a headline, 3–4 checkmark bullet points from descriptionPoints, and a “View Rate” call-to-action button.&#x20;
* **Footer:** Disclaimer text (e.g., “Offer order is based on compensation from our partners, and other factors.”) plus any underwriter/license line supplied by the partner, followed by standard footer links: Engine, Terms, Privacy, Disclosures, and Do Not Sell/Share My Personal Information.&#x20;
* **Responsive layout:** On mobile, offer cards stack with adjusted spacing/heights, and carrier logos wrap into a grid where applicable.&#x20;
* **Back button:** The compare page should include a back button. If the user’s information was prefilled, back should return them to the confirmation/review step; otherwise, it should return them to the last question in the search flow.&#x20;

### Search Flow Questions

Because the Auto Insurance API requires only a small set of fields to return offers, Engine’s own search flow is kept short - a single question per screen, each mapped directly to a request field. Partners building their own flow can follow the same sequence and copy patterns as a starting point.

{% stepper %}
{% step %}

#### Enter the ZIP code

**Question:** “Let’s find your auto insurance matches.”\
**Input:** ZIP code text field.\
**Maps to:** `personalInformation.zipCode`
{% endstep %}

{% step %}

#### Select the current provider

**Question:** “Who is your current auto insurance provider?”\
**Input:** Typeahead search, such as State Farm, Progressive, Geico, Allstate, Liberty Mutual, or USAA. Include “My car is not insured.”\
**Maps to:** `autoInsuranceInformation.currentIssuer`
{% endstep %}

{% step %}

#### Select the vehicle count

**Question:** “How many vehicles do you want to insure?”\
**Input:** Single-select: 1, 2, 3, 4, or 5+ vehicles. Show a “Save 20%” bundling badge for 2+ vehicles.\
**Maps to:** `autoInsuranceInformation.numberOfVehicles`
{% endstep %}

{% step %}

#### Confirm home ownership

**Question:** “Do you own your home?”\
**Input:** Yes or No.\
**Maps to:** `autoInsuranceInformation.policyHolderInformation.isHomeOwner`
{% endstep %}

{% step %}

#### Confirm military service

**Question:** “Have you or your spouse honorably served in the U.S. Military?”\
**Input:** Yes or No.\
**Maps to:** `autoInsuranceInformation.policyHolderInformation.isMilitary`
{% endstep %}

{% step %}

#### Capture date of birth and consent

**Question:** “Help us personalize your quotes.”\
**Input:** Date field in `MM/DD/YYYY` format, consent checkbox, and “Agree and Continue” CTA.\
**Maps to:** `personalInformation.dateOfBirth`
{% endstep %}
{% endstepper %}

{% hint style="info" icon="circle-question" %}

#### Question context

Each question screen should explain why the information is needed. Examples:

* "Adding all vehicles can help surface multi-car discounts"
* "Some providers offer military-related discounts"

This context improves completion rates. It also shows how the data supports matching.
{% endhint %}

{% hint style="info" icon="file-signature" %}

#### Consent collection

The final step combines `dateOfBirth` with required consent language. See Compliance.

Use one **Agree and Continue** button. This captures consent when submitting the offer search.
{% endhint %}

{% hint style="info" icon="circle-plus" %}

#### Optional information

Additional information may improve match quality. Examples include extra vehicles, drivers, prior claims, and coverage limits.

Confirm optional fields against the latest API reference.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://even-financial.gitbook.io/developer-center/marketplace-integrations/native-api/auto-insurance/ui-design-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.