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_<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.
secondary_inspection_cutoff_at	ISO 8601 with offset	yes	Deadline for secondary_inspection_required: true orders: end of day (auction day − D) in your integration’s timezone (default D=2, Africa/Lagos — e.g. for a Thursday auction you have all of Tuesday, local time). Calendar-based — the auction’s start time is irrelevant. null for dealer/buy-now. Added 2026-07-08 (v1.48).
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.
secondary_inspection_cutoff_at	ISO 8601	yes	The inspection request cutoff enforced at creation. null unless the order was created with secondary_inspection_required: true on an auction vehicle (also null for orders predating v1.48).
secondary_inspection_url	string (URL)	yes	LMN URL of the completed secondary-inspection report. Populated when the order reaches secondary_inspection_ready (when available) — the order.status_changed webhook for that transition carries it, so you can surface the report at the confirm/decline decision point. null before the inspection completes and for orders without a recorded report. Added 2026-07-15 (v1.49).
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)
        ├─→ secondary_inspection_in_progress → secondary_inspection_ready ─┬─→ acquiring
        │                                              └─→ cancelled (secondary_inspection_declined / secondary_inspection_failed)
        └─→ cancelled                                  (from placed)

Inspection is optional: an order may go placed → acquiring directly (skip inspection) or placed → secondary_inspection_in_progress → secondary_inspection_ready → acquiring (inspected). When inspection fails, the order is cancelled (reason secondary_inspection_failed), never failed.

Value	Set by	Meaning	Terminal
placed	Partner	Order accepted; LMN has queued it.
secondary_inspection_in_progress	LMN	Optional pre-acquisition inspection underway. On complete → secondary_inspection_ready.
secondary_inspection_ready	LMN	Inspection completed. Partner may confirm (POST /v1/orders/{id}/confirm → acquiring) or decline (DELETE /v1/orders/{id} → cancelled, reason secondary_inspection_declined); LMN/admin may also advance to acquiring or cancel (reason secondary_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 secondary_inspection_ready (Partner via DELETE, reason secondary_inspection_declined; or LMN/admin, reason secondary_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
secondary_inspection_declined	Partner sent DELETE /v1/orders/{id} while secondary_inspection_ready.	secondary_inspection_ready
secondary_inspection_failed	Admin judged the inspection disqualifying and cancelled while secondary_inspection_ready.	secondary_inspection_ready
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.