> ## 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.
# Schemas
> Vehicle, Order, and shared Eagle Eye payload shapes.
## Vehicle
Two shapes — `VehicleSummary` (list view) and `Vehicle` (single fetch detail).
Eagle Eye reuses `VehicleSummary` for vehicles returned in search results, match rows, and `eagle_eye.match` webhook `additions` / `price_changes`. Eagle Eye-specific fields such as `watch_id`, `match_reason`, and `signal_detail` wrap this shared vehicle model.
### VehicleSummary
Returned by `GET /v1/vehicles`.
| Field | Type | Nullable | Notes |
| ----------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | no | Vehicle ID. Two formats: auction listing/appearance ID with a source prefix (`glovis_…`, `sk_…`, `aj_…`, `lotte_…`, `kcar_…` — e.g., `glovis_20260420_1064_2345`), or dealer ID `encar_`. Use this for `GET /v1/vehicles/{id}` and (auction only) `POST /v1/orders`. Auction IDs are not permanent physical-car IDs; the same car can receive a different ID when re-listed. |
| `source` | enum | no | `dealer \| glovis \| sk \| aj \| lotte \| kcar`. `dealer` listings are fulfilled via a live proxy to a third-party retail inventory; see endpoint docs for dealer-specific constraints. |
| `make` | string | no | |
| `model` | string | no | |
| `trim` | string | yes | Dealer (`encar_*`) uses encar's canonical English grade name. |
| `year` | integer | no | |
| `mileage_km` | integer | no | |
| `fuel` | enum | yes | `gasoline \| diesel \| hybrid \| electric \| lpg \| hydrogen \| gasoline_hybrid \| diesel_hybrid \| plug_in_hybrid`, or `null` for rare upstream gaps. Multi-word values use `snake_case` (e.g. `gasoline_hybrid`, never `"gasoline hybrid"`) to match the `options_include` convention and avoid URL-encoding ambiguity. `hydrogen` covers Hyundai Nexo and similar FCEVs. |
| `transmission` | enum | yes | `auto \| manual \| cvt \| dct`. Populated for dealer (`encar_*`) too as of 2026-06-03. |
| `color` | string | yes | |
| `engine_cc` | integer | yes | Populated for dealer (`encar_*`) too as of 2026-06-03. |
| `drivetrain` | string | yes | e.g., `FWD`, `AWD`, `4WD`. |
| `options` | array of strings | no | Equipment list. Empty array if none known. To **filter** by option, use the `options_include` query param — the full token catalog (62 dealer-filterable tokens + 2 dealer-unsupported) lives in [Vehicles → `options_include` for dealer (full catalog)](/endpoints/vehicles#options_include-for-dealer-full-catalog). |
| `accident_grade` | enum | yes | `A \| B \| C \| D \| F` (no E). `null` for dealer source. |
| `exterior_grade` | enum | yes | `A \| B \| C \| D \| F`. `null` for dealer source. |
| `auction_date` | ISO 8601 with offset | yes | KST `+09:00`. `null` for dealer source. |
| `order_cutoff_at` | ISO 8601 with offset | yes | `auction_date − N minutes`, where N is your integration's pre-negotiated lead time (default 1440 = 24h; lower for integrations without a secondary inspection step). `null` for dealer/buy-now. Updated 2026-04-29. |
| `thumbnail_url` | string (HTTPS URL) | yes | |
| `pricing` | object | no | Summary shape: `{ listing_price, sold_price, discount_config, breakdown }`. Monetary values are whole USD. As of 2026-05-26, `discount_config` and `breakdown` are returned on the summary too (same shape as detail) so list-view cards can show landed-cost without a per-row detail fetch. `auction_fee_config`, `history`, and `market_assessment` remain detail-only. See [`pricing`](#pricing). |
| `auction_result` | enum | yes | `upcoming \| sold \| negotiation_sold \| no_bid \| negotiation_requested`. `null` for dealer. |
| `auction_count` | integer | yes | Number of times listed at auction. `null` for dealer. |
### Vehicle (Detail)
`VehicleSummary` plus:
| Field | Type | Nullable | Notes |
| ------------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vin` | string | yes | Dealer (`encar_*`, added 2026-06-03): from the listing, or promoted from the inspection report's 차대번호 when the listing omits it. `null` only when encar publishes no VIN for the listing (a minority — e.g. listings whose inspection is an abbreviated record with no structured form). Treat `null` as "not available from source" and request the VIN from the dealer where needed — do not infer it. |
| `license_plate` | string | yes | Korean format. |
| `photos` | array of HTTPS URLs | no | All photos (not just thumbnail). |
| `photo_tags` | array | no | Same photo URLs with a `tag` such as `front`, `side_l`, `side_r`, `rear`, `interior`, `dashboard`, `front_seats`, `rear_seats`, `trunk`, `engine`, `odometer`, `vin`, `other`. Each item is `{ url, tag }`; array order follows `photos`. Most tags are positional heuristics from photo array order. `vin` is precision-tagged — when present, that photo shows the VIN plate (차대번호) and can appear at any index. At most one `vin` tag per car; `vin` may be absent when the upstream listing did not include a VIN plate photo or when one could not be identified with confidence. |
| `body_condition` | object | yes | `{ image_url, panels[] }` — panel-level damage map, for **both auction and dealer** sources. `panels[]` lists damaged panels only; a clean car returns `{ image_url, panels: [] }` (an empty array, not `null`) so you still render the diagram. `image_url` is LMN-mirrored HTTPS media when available (Glovis), else `null`; upstream auction-site image URLs are not exposed. `null` only when the source has no inspection record. |
| `inspection_report` | object | yes | Source's inspection, normalized to English-only keys for partner use. Populated for **both auction and dealer** sources whenever the inspection is reachable — a clean car returns a report with zero damage and a populated `checklist[]` (not `null`). Includes `inspection_sheet_url` (`string \| null` — original inspection PDF; SK/AJ only, else null). Dealer (`encar_*`) reports carry a `dealer_inspection` block (`{ critical_frame_damage, exterior_damage, rank_counts, frame_status, panel_status, simple_repair, insurance_history, insurance_amount, vehicle_info, overall_status[], photos[], certification, registration_no }`; `rank_counts` is `{ rank_one, rank_two, rank_a, rank_b, rank_c }` — integer per-rank damaged-panel counts, where `rank_a + rank_b + rank_c === critical_frame_damage` and `rank_one + rank_two === exterior_damage`; `vehicle_info` holds only inspection-form-specific fields — Valid Period, Warranty, Engine Model, etc. — identity like make/model/year/plate/VIN is top-level only) and surface accident state via `has_accident` / `accident_summary` rather than `accident_history[]`. `null` only when the source has no inspection record (e.g. dealer upstream 404) or the fetch failed transiently. Retains `category_grades[]` and `issues[]` for backward compatibility (auction-rich; dealer emits `category_grades` as frame/exterior and an empty `issues[]`). Any monetary fields in `accident_cost_summary`, and `dealer_inspection.insurance_amount`, are whole USD (FX-converted server-side). |
| `comparables` | object | no | `{ past_sales, upcoming_sales }`. Each comparable includes `vehicle_id`, `vin`, `license_plate`, USD price fields, and auction metadata. `upcoming_sales` does not include `sold_price`. |
| `pricing` | object | no | Adds fee config, landed-cost breakdown, same-car history, and market assessment. See [`pricing`](#pricing). |
### `pricing`
`pricing` groups this vehicle's prices, fee estimates, same-car history, and market assessment. Every monetary number inside this object is a whole USD integer.
| Field | Type | Nullable | Notes |
| -------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `listing_price` | integer | no | Current listed/estimated vehicle price. For auction vehicles this is the estimated final price when comparable-market data exists, otherwise the auction starting price. For dealer vehicles this is the asking price. **Summary + detail.** |
| `sold_price` | integer | yes | Final sold price when the auction result is `sold` or `negotiation_sold`; otherwise `null`. **Summary + detail.** |
| `discount_config` | object | no | `{ bid_threshold, rate_below, rate_at_or_above, fixed_discount_amount, vehicle_discount_pct }`. Always populated. For auction: bid-based fields drive the discount, `fixed_discount_amount` is 0. For dealer: bid-based fields are all 0; `fixed_discount_amount` carries the entire economic effect (300 USD, offsets the flat dealer fee). `bid_threshold` is compared against the **partner's bid amount**, not the listing price. `vehicle_discount_pct` is a whole-percent integer; partner-specific — `0` for partners without a configured discount. When `vehicle_discount_pct > 0`, the basis is discounted before fees/freight/LMN are added, and the bid-rate fields (`bid_threshold`, `rate_below`, `rate_at_or_above`) and dealer `fixed_discount_amount` are all `0` (the vehicle discount replaces them entirely). **Summary + detail** (added to summary 2026-05-26). |
| `breakdown` | object | no | Illustrative landed-cost estimate. Contains `auction_fee`, `dealer_fee`, `lmn_commission`, `ocean_freight`, and `estimated_landed`. **`ocean_freight` varies per vehicle** by body type and maker — it is **not** a fixed value: Mercedes-Benz is 1800 (any body type); other makers are 1800 for SUV-class (SUV, minivan, van, truck) and 1500 for sedan-class (sedan, compact, wagon, coupe, convertible); vehicles with an unknown body type use 1500. Read the value from each response rather than hardcoding it. **Fee shape is symmetric** — both `auction_fee` and `dealer_fee` are always integers (`0` where the concept doesn't apply, real value where it does); branch on `source`, not on `null`. For auction: `auction_fee` populated, `dealer_fee: 0`. For dealer: `auction_fee: 0`, `dealer_fee: 300` (flat USD). `estimated_landed` for auction: `basis + auction_fee + lmn_commission + ocean_freight − (bid_rate_discount + fixed_discount_amount)`. For dealer: `listing_price + dealer_fee + lmn_commission + ocean_freight − fixed_discount_amount` (dealer\_fee and fixed\_discount net to zero, so this reduces to `listing_price + lmn_commission + ocean_freight`). For exact auction totals at the partner's own bid, recompute using `auction_fee_config` and `discount_config`. **Summary + detail** (added to summary 2026-05-26). |
| `auction_fee_config` | object | yes | `{ percentage, minimum, maximum }`, where `minimum` and `maximum` are source/category fee caps converted to USD. `null` for dealer. **Detail only** — fee schedule is constant per source/category so partners can hold a static copy. |
| `history` | array | no | Same physical vehicle's auction appearances, not comparable cars. |
| `market_assessment` | object | yes | Server-side price verdict over sold comps; `null` for dealer. |
## Order
Returned by `POST /v1/orders`, `GET /v1/orders`, `GET /v1/orders/{id}`, `DELETE /v1/orders/{id}`, `POST /v1/orders/{id}/status`.
Use `GET /v1/orders/{id}/vehicle` for the purchased vehicle snapshot. That response is the same `VehicleDetail` schema as `GET /v1/vehicles/{id}` and is stored at order creation so dealer purchases remain readable after the live Encar listing is removed.
| Field | Type | Nullable | Notes |
| --------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string (ULID) | no | |
| `vehicle_id` | string | no | Auction listing/appearance ID the order was placed against. Not a permanent physical-car ID. |
| `vin` | string | yes | VIN snapshotted from the upstream listing at order creation. `null` when the upstream listing carried no VIN. Self-contained — webhook consumers can match dealer records without a follow-up `GET /v1/vehicles/{id}`. |
| `license_plate` | string | yes | Korean license plate snapshotted at order creation. `null` when the upstream listing carried no plate. |
| `options` | array of strings | no | English Title-case feature names (e.g. `Sunroof`, `Leather Seats`, `LED Headlamps`) snapshotted from the vehicle at order creation. Byte-equal to `Vehicle.options` on `GET /v1/vehicles/{id}` so consumers don't need a follow-up lookup. Both auction and dealer (`encar_*`) sources return Title-case English. Empty array (`[]`) when the upstream listing exposed no options, or for orders created before v1.21. |
| `status` | enum | no | See state machine below. |
| `max_bid_amount_usd` | integer | yes | Whole USD. Set at creation. `null` for buy-now/dealer. Settlement obligation applies only on `secured`. |
| `is_highest_bid` | boolean | no | Computed; `true` when no competing orders. |
| `current_max_bid_usd` | integer | no | Computed across all active orders for the vehicle. |
| `amounts` | object | no | `{ purchase_price_usd, auction_fee_usd }` — both `null` until `secured`. Computed from the auction's KRW final price using the order's locked `fx_rate`. |
| `fx_rate` | number | yes | **KRW-per-USD rate locked at order creation time.** Does **not** change on PATCH or status updates — the settlement amount is deterministic from day one. `null` only if the FX provider was unavailable when the order was created; in that case LMN applies the secured-day rate (communicated offline). |
| `auction_date` | ISO 8601 | yes | `null` for dealer orders. |
| `order_cutoff_at` | ISO 8601 | yes | `null` for dealer/buy-now. |
| `acquired_at` | ISO 8601 | yes | Set at `secured`. |
| `shipped_at` | ISO 8601 | yes | Set at `in_transit`. |
| `shipment` | object | yes | `null` until `export_processing`. See below. |
| `failure_reason` | enum | yes | Set only when `status: failed`. Mutually exclusive with `cancellation_reason`. |
| `cancellation_reason` | enum | yes | Set only when `status: cancelled`. Mutually exclusive with `failure_reason`. |
| `created_at` | ISO 8601 | no | |
| `updated_at` | ISO 8601 | no | |
### `shipment` object
`null` until `in_transit`; populated by LMN at vessel loading. Stable for the rest of the shipping leg.
| Field | Type | Notes |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `vessel_name` | string | e.g., `Glovis Sky`. |
| `voyage` | string | e.g., `GS-2604E`. |
| `bl_number` | string | Bill of Lading number from the carrier, e.g., `MAEU1234567890`. Carrier-specific format; free-form alphanumeric. Use as the correlation key when filing customs entries or raising disputes — every party sees the same value. |
| `container_id` | string | Container holding the vehicle, e.g., `MSKU7654321`. Typically follows ISO 6346 (4 letters + 6 digits + 1 check digit); format is not enforced at the API layer. |
| `etd_korea` | ISO 8601 | Departure from Korean port. |
| `eta_destination` | ISO 8601 | Estimated arrival at destination port. |
| `destination_port` | string | e.g., `Tin Can Island, Lagos`. |
### Order `status` enum (11 values)
```
placed ─┬─→ acquiring → secured → export_processing → in_transit → customs → delivered
│ └─→ failed (acquiring only)
├─→ inspection_in_progress → inspection_ready ─┬─→ acquiring
│ └─→ cancelled (inspection_failed)
└─→ cancelled (placed only)
```
Inspection is **optional**: an order may go `placed → acquiring` directly (skip
inspection) or `placed → inspection_in_progress → inspection_ready → acquiring` (inspected). When
inspection fails, the order is `cancelled` (reason `inspection_failed`), never
`failed`.
| Value | Set by | Meaning | Terminal |
| ------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `placed` | Partner | Order accepted; LMN has queued it. | |
| `inspection_in_progress` | LMN | Optional pre-acquisition inspection underway. On complete → `inspection_ready`. | |
| `inspection_ready` | LMN | Inspection completed; LMN can move to `acquiring`, or cancel with `inspection_failed`. | |
| `acquiring` | LMN | LMN is bidding (auction) or purchasing (dealer). | |
| `secured` | LMN | Vehicle won/purchased; `purchase_price` and `auction_fee_usd` locked. | |
| `export_processing` | LMN | Title transferred to LMN; Korean export workflow in progress (declaration, port trucking, vessel booking, loading). | |
| `in_transit` | LMN | Bill of Lading issued and vessel has departed Korean port. | |
| `customs` | Partner | Vessel arrived at destination port; vehicle in customs-bonded area. | |
| `delivered` | Partner | Customs cleared and vehicle handed to the dealer. **Partner must push this** — terminal. | ✅ |
| `failed` | LMN | Acquisition did not complete (`failure_reason` set). Reachable from `acquiring` only. | ✅ |
| `cancelled` | Partner or LMN | Reachable from `placed` (Partner via `DELETE`, or LMN auto-cancel: reschedule-too-soon, source-cancel, seller-withdraw) or from `inspection_ready` (LMN, reason `inspection_failed`). | ✅ |
**Boundary:** statuses up to `in_transit` are LMN-driven (server-side). From `customs` onward, the partner pushes via `POST /v1/orders/{id}/status`.
### `failure_reason` enum
| Value | When | Triggers from |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `outbid` | External bidder exceeded the partner's max bid at auction. | `acquiring` |
| `outbid_internally` | Another partner's higher bid won at auction. All competing `placed` orders on the same lot enter `acquiring` together before resolution. | `acquiring` |
| `vehicle_unavailable` | LMN's dealer purchase attempt fails because the car was sold to another buyer. | `acquiring` |
| `auction_cancelled` | Auction house cancels the event after LMN has begun bidding. Pre-`acquiring` discovery routes to `cancelled` (see `cancellation_reason`). | `acquiring` |
| `auction_passed` | Vehicle was passed at auction (no winning bid), OR system zombie cleanup at `auction_date + 24h` for orders LMN never picked up. | `acquiring` |
| `seller_withdrew` | Seller withdrew the car after LMN started attempting to acquire. Pre-`acquiring` discovery routes to `cancelled` (see `cancellation_reason`). | `acquiring` |
### `cancellation_reason` enum
| Value | When | Triggers from |
| ------------------------------ | ----------------------------------------------------------------------------------------- | ------------- |
| `dealer_cancelled` | Partner sent `DELETE /v1/orders/{id}` while `placed`. | `placed` |
| `auction_rescheduled_too_soon` | LMN auto-cancel because the auction was rescheduled past the order cutoff. | `placed` |
| `auction_cancelled` | LMN auto-cancel because the auction event was cancelled before LMN started bidding. | `placed` |
| `seller_withdrew` | LMN auto-cancel because the seller pulled the dealer listing before LMN started purchase. | `placed` |
`failure_reason` and `cancellation_reason` are **mutually exclusive** — an order has one or the other, never both. For reasons that appear in both enums (`auction_cancelled`, `seller_withdrew`), the order's current status at the moment of the upstream event decides which terminal — and therefore which field — applies.
### Settlement
At `secured`: partner owes LMN `purchase_price_usd + auction_fee_usd + lmn_commission_usd + ocean_freight_usd − discount_usd`, where discount = `ceil(purchase_price_usd × rate / 100) + fixed_discount_amount`; `rate` follows `pricing.discount_config` evaluated against `purchase_price_usd` (the actual hammer price). The breakdown is communicated via the payment-due report, not exposed via the API. Wire transfer same US business day expected.
There is **no dealer-deposit concept** in this API. Partner-to-dealer arrangements are entirely outside LMN's scope.