> ## Documentation Index
> Fetch the complete documentation index at: https://lmn.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Eagle Eye overview
> A product overview for partner teams: how LMN helps dealers find, watch, and act on the right Korean vehicles.
Eagle Eye is a sourcing assistant for partner dealers. Instead of asking a dealer to refresh inventory, repeat the same search, and manually notice price changes, LMN watches the Korean market for them and surfaces the cars worth acting on.
The goal is simple: **help each dealer catch the right opportunity at the right time** across Korean auction and dealer inventory.
## The problem
Dealers already know what their buyers want: maker, model, year, budget, mileage, condition, and sometimes a very specific trim. The hard part is not defining the search. The hard part is watching a fast-moving market without missing the moment when:
* a new matching car appears,
* a watched car drops in price,
* a car keeps reappearing across auction rounds,
* a listing looks meaningfully cheaper than comparable cars,
* a car disappears and should no longer be shown as actionable.
Today, that work often becomes manual monitoring. Eagle Eye turns it into a saved condition and a change feed.
## Product idea
A partner creates an **Eagle Eye watch** for a dealer's buying intent.
That watch has two parts:
| Part | What it means |
| --------- | --------------------------------------------------------------------------------------------------- |
| `filters` | The dealer's must-have criteria: source, make, model, year, mileage, price, etc. |
| `signals` | Extra reasons a car is interesting: price drop, repeat listing, undervalued versus comparable cars. |
The watch produces two surfaces:
A live list of cars that match the dealer's condition. This is what the product UI can render as a watch inbox.
Webhook batches when something changes: new matches, price drops, signal hits, or removals.
This lets partner teams build a product experience that feels like: "Save this buying brief, then tell me when something worth my attention happens."
## What LMN will provide
Eagle Eye adds a new API surface, not just a new behavior on `/v1/vehicles`.
| Capability | Product meaning |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Search preview | Try a buying condition and show the current matches before saving it. |
| Saved watches | Persist the condition so LMN keeps watching the market. |
| Match inbox | Let the dealer review current matches and hide cars they have already handled. |
| Change alerts | Send webhook batches when new matches, price drops, or removals happen. |
| Static lists | Hand-pick specific cars to monitor instead of relying on saved criteria — auction and dealer cars alike. The fit for favorites: an un-priced auction car notifies the moment a price appears; a dealer car notifies on every price change and on delisting. |
| Order handoff | Use the matched `vehicle_id` with the existing LMN order API. |
Engineering reference: [Eagle Eye endpoints](/endpoints/eagle-eye).
## What the dealer sees
For a dealer, Eagle Eye should feel like a watched buying brief.
Example:
> "Find me Mercedes-Benz GLE 450s, 2020 or newer, below 70,000 km, under my budget. Tell me when a new one appears or the price drops."
The dealer should not need to understand auction batch timing, dealer inventory polling, or comparable-set logic. They should see:
* a named watch, such as "GLE 450 for Musa",
* a count of active matches,
* the newest cars that match,
* why each car appeared,
* whether the watch is quiet, active, muted, or paused,
* alerts only when something changed.
## Why a car appears
Every match should be explainable in product copy. The partner UI can show one or more reasons:
| Reason | Suggested user-facing wording |
| ------------------------ | ------------------------------- |
| `filters` | "Matches your saved criteria" |
| `signals.price_drop` | "Price dropped" |
| `signals.repeat_listing` | "Repeated auction listing" |
| `signals.undervalued` | "Below comparable market price" |
Signals are additive. They do not replace the saved criteria. A car still has to belong to the watch's buying universe, and then it may have extra reasons to be highlighted.
For signal matches, LMN should give enough detail for the UI to explain the alert:
| Signal | Detail the partner can show |
| ---------------- | ------------------------------------------------------------------------------------------------------ |
| `repeat_listing` | How many matching auction listings were seen in the window, plus the cumulative price drop percentage. |
| `undervalued` | The reference market price and how far below that price the listing is, as a percentage. |
| `price_drop` | Previous price, current price, and drop percentage. |
## Notification philosophy
Eagle Eye is intentionally **delta-only**.
When a watch is created, LMN can seed the current shortlist so the dealer immediately has cars to review. Those seeded cars are not pushed as notifications. Notifications begin when the market changes after the watch exists.
Dealers are notified only for actionable changes: new matches, meaningful price drops, and removals. If a vehicle price increases but the vehicle still matches the saved criteria, it stays in the shortlist and simply loses the price-drop signal; LMN does not send a notification for that.
This avoids the common failure mode where a partner creates a watch and immediately receives a noisy dump of cars they already saw.
Think of it this way:
| State | Visible in match list? | Sends notification? |
| ------------------------------------------------------- | ---------------------: | ------------------: |
| Current cars at watch creation | Yes | No |
| New matching car after creation | Yes | Yes |
| Existing match with a price drop | Yes | Yes |
| Existing match with a price increase but still matching | Yes | No |
| Existing match with no change | Yes | No |
| Hidden/reviewed car | Hidden by default | No |
| Sold, delisted, or put under contract | Removed | Yes |
## Dealer inventory scope
Eagle Eye covers both Korean auction sources and dealer inventory, but the mechanics differ.
**Dealer-source vehicles can be added to tracking on both surfaces.** Create a watch with `"dealer"` in `filters.source` — alone or mixed with auction sources — and LMN tracks matching dealer cars exactly like auction cars: seeded shortlist, new-match alerts, price drops, removals. Or hand-pick specific dealer cars onto a **static list** by id: LMN re-checks them hourly and notifies on price changes and delisting — see [Tracking dealer-source vehicles](/endpoints/eagle-eye#tracking-dealer-source-vehicles).
Auction inventory arrives through LMN's scheduled auction data pipeline. Dealer inventory is queried live per dealer watch on a schedule. Product teams do not need to expose that distinction, but it matters for expectations:
* Dealer watches can find new dealer matches.
* Dealer watches can detect dealer price drops after a baseline exists.
* Dealer watches can detect removals when a previously matched dealer car no longer appears.
* Dealer watches can use the reliable vehicle fields LMN already exposes, while option-sensitive workflows should be treated carefully until source coverage is stronger.
* Repeat-listing and undervalued signals are auction-first in v1.
For v1, dealer inventory should be positioned as: **filters plus price-drop monitoring, plus hand-picked favorites via static lists**.
## Product controls
Partner teams should model four simple watch controls:
| Control | Dealer meaning |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Active | "Keep watching and notify me." |
| Muted | "Keep watching, but stop notifications for now." |
| Paused | "Stop collecting matches until I resume." |
| Retired | "I'm done with this watch for good." There is no separate delete — pause it. A paused watch stops counting against the active-watch cap and can always be resumed later if needed. |
Muted and paused are different. Muted still collects matches silently. Paused does not collect anything while paused.
For individual matches, support a "hide" or "mark reviewed" action. Hidden cars leave the default inbox and do not notify again for that watch unless the partner unhides them.
## What teams can build
A page where a dealer sees all active watches, match counts, newest matches, and last activity.
A form that captures source, make/model, budget, mileage, year, and optional signals.
Push notifications, WhatsApp messages, CRM tasks, or internal alerts triggered by Eagle Eye webhooks.
A call-to-action from a match into the existing LMN order flow.
## Buyer-fit tolerance (flexibility)
Dealers rarely have rigid criteria. A dealer looking for a 2020 Hyundai Santa Fe gasoline under $13,700 landed — no frame damage — may still be interested in a 2020 Santa Fe that costs $13,782, or a Santa Fe Hybrid at the same price point. Eagle Eye's `flexibility` block captures that tolerance without the dealer needing to broaden their stated brief.
### How it works
When you include a `flexibility` block in the watch request, LMN widens the filter bounds by the specified tolerance and runs the wider query alongside the strict one. Matching results from the widened query are admitted to the watch and tagged so the partner UI can explain the match.
**Example — the Santa Fe watch:**
> A dealer wants a 2020 or newer Hyundai Santa Fe, gasoline, no frame damage, estimated landed cost no more than \$13,700.
The watch might be created like this:
```json theme={null}
{
"filters": {
"source": ["dealer"],
"make": "Hyundai",
"model": "Santa Fe",
"fuel": "gasoline",
"year_min": 2020,
"estimated_landed_max_usd": 13700,
"no_frame_damage": true
},
"flexibility": {
"fields": {
"estimated_landed_max_usd": { "level": "medium" },
"model": {
"level": "small",
"allowed_values": ["Santa Fe Hybrid"]
},
"fuel": { "level": "none" },
"no_frame_damage": { "level": "none" }
}
}
}
```
With `level: "medium"` on `estimated_landed_max_usd`, the effective landed-cost bound becomes `floor(13700 × 1.05) = 14385`. A car priced at \$13,782 landed — above the strict limit but inside the medium tolerance — is admitted and tagged `match_type: "flex"` with this detail:
```json theme={null}
{
"estimated_landed_max_usd": {
"requested": 13700,
"level": "medium",
"effective": 14385,
"actual": 13782
}
}
```
A car priced at \$13,200 landed is an exact match and carries `match_type: "exact"` with no `flex_detail`.
The Santa Fe Hybrid alternative means LMN also runs a parallel search for `model: "Santa Fe Hybrid"`. A match from that variant carries `match_type: "flex"` with a categorical `flex_detail` showing the requested model, the alternatives, and the actual model matched.
### When to use no\_frame\_damage vs no\_accident
Both damage filters exclude structurally damaged cars, but they differ in how they treat exterior repair history.
| Goal | Use this filter |
| ------------------------------------------------------------ | ----------------------- |
| Strictest possible clean record — no exterior repairs either | `no_accident: true` |
| Frame integrity guaranteed, exterior repairs accepted | `no_frame_damage: true` |
| No damage filter | Omit both |
`no_frame_damage` is the **source-equivalent** filter — it maps to the same structural standard on both dealer (encar) and auction inventory. `no_accident` is stricter on dealer (zero exterior repairs) than on auction (exterior work is permitted at grade A), so a watch mixing `source: ["dealer", "glovis"]` with `no_accident: true` applies the strictest predicate each source can verify.
For most frame-sensitive buyers, `no_frame_damage` is the right choice. It gives consistent behavior across sources and still excludes structurally compromised cars.
`flex_detail` and `match_type` appear on every match-bearing surface: search rows, match list items, and `additions` / `price_changes` entries in `eagle_eye.match` webhooks. Partner UIs can use this to show dealers whether a match is an exact hit or a tolerance-admitted alternative.
Engineering reference for request shape, tolerance tables, and error codes: [Eagle Eye endpoints — Buyer-fit tolerance (flexibility)](/endpoints/eagle-eye#buyer-fit-tolerance-flexibility).
***
## Acting on an opportunity
Eagle Eye does not replace ordering. It sits before ordering.
The flow is:
1. Dealer saves a watch.
2. LMN surfaces a matching vehicle.
3. Partner UI shows the vehicle and the reason it matched.
4. Dealer decides to act.
5. Partner creates an LMN order using the same vehicle ID.
Auction vehicles still require a bid ceiling. Dealer inventory should hand off through the existing LMN order flow for that vehicle.
## Current scope
Eagle Eye is deliberately focused on the core watch workflow:
* Saved watches scoped to each partner.
* Current match lists.
* Change webhooks.
* New matches, price changes, removals.
* Dealer inventory through scheduled dealer polling.
* Auction signals for repeat listings and undervalued cars.
* Dealer price-drop monitoring.
* Hide, mute, pause, resume.
* Static lists — hand-picked cars monitored outside the filter model, for tracking specific favorited cars across auction and dealer sources. See [Eagle Eye endpoints — Static lists](/endpoints/eagle-eye#static-lists) and [Tracking dealer-source vehicles](/endpoints/eagle-eye#tracking-dealer-source-vehicles).
## Implementation expectation
Partner product and UX teams can treat Eagle Eye as a saved-search-plus-alerts feature. Partner engineering teams can treat it as:
* one write path to create or update a watch,
* one read path for current matches,
* one webhook stream for changes,
* one handoff into the existing order API.
The most important product decision is not the endpoint shape. It is how the partner wants dealers to triage opportunities: inbox, CRM task, chat alert, saved search page, or all of the above.