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_<numeric>. 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). |
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. |
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 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)
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). | ✅ |
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.
