History lookups

Submit a Korean plate or VIN and receive a normalized English vehicle-history report and PDF.

A history lookup returns the vehicle history held by CarHistory (carhistory.or.kr, Korea Insurance Development Institute) as normalized English JSON plus an English PDF: accidents and repair costs, total-loss/theft/flood flags, owner and plate changes, rental/commercial use, mileage, ADAS and an insurance-reference value range.

Route	Returns
POST /v1/history-lookups	Submits a lookup. 202 with status: queued.
GET /v1/history-lookups	Your lookups, newest first. Filter by status, created_from, created_to.
GET /v1/history-lookups/{id}	One lookup, with report once completed.
GET /v1/history-lookups/{id}/report.pdf	The English PDF (application/pdf). 409 history_report_not_ready until completed.

Async flow

1. POST /v1/history-lookups with exactly one of plate or vin, an Idempotency-Key header, and optional fresh and reference. The response is 202 with status: queued.
2. The result arrives as a history_lookup.completed or history_lookup.failed webhook on your existing endpoint. The event carries the full lookup, so no follow-up GET is needed. Results usually arrive within minutes.
3. Polling GET /v1/history-lookups/{id} is the fallback. status moves queued → processing → completed or failed.

Replaying the same Idempotency-Key with the same body returns the original lookup with 200. The same key with a different body returns 422 idempotency_key_reused, as POST /v1/orders does.

Keys: plate or VIN

• Plate: searches by plate.
• VIN: searches by VIN first. This works for deregistered and exported cars.
• Plate fallback: if CarHistory refuses the VIN and our inventory holds that car’s plate, we retry by plate. The lookup then has fallback_plate_from_inventory: true, query.key_used: "plate", and an identity_check that tells you whether the report matches the car you asked about.
• A car that is still registered in Korea and is not in our inventory needs its plate.

identity_check is matched, mismatch, unverified or not_applicable (null until the lookup is completed; also null for failed). identity_check_basis lists the attributes that agreed (manufacturer, model_year). A mismatch report is still delivered, flagged, and is never billed.

no_record

A failed lookup with failure.code: "no_record" means CarHistory returned nothing for the key. CarHistory does not say why. Causes include a deregistered car searched by plate, a rental-heavy history, or too many accidents. Other failure codes are provider_unavailable and provider_error.

Reading the report

• Null, missing and []: every scalar is nullable. null means the source did not state the value or it could not be read. A section absent from the source is null; [] means the section is present and empty.
• Dates: full dates are YYYY-MM-DD. Fields named *_month are YYYY-MM.
• Money: *_krw fields are integers in Korean won. There is no FX conversion.
• Damage direction: own_vehicle_damage is damage to this vehicle. other_vehicle_damage is damage this vehicle caused to another vehicle. paid_by says who paid: own_insurer, other_party_insurer or unknown.
• Summary counts are as the source states them. They are not recomputed from the lists, so they can differ from the list lengths.
• value_range is an insurance reference value only (basis: "insurance_reference"). It is not a market price.
• ownership_history[].kind is owner_change, plate_change, use_change or null. plate_masked (e.g. 47버XXXX) is the only report field that can contain Hangul.
• source and report_as_of: source: "fresh" means we fetched the report for this lookup. source: "cache" means we reused an earlier report and report_as_of keeps the original fetch time. Send fresh: true to skip the cache.

Billing

billable on the lookup says whether it counts toward your invoice.

Rule	Detail
Price	$3 per lookup for the first 500 in a KST calendar month,$2 after.
mismatch	Never billed.
failed	Not billed.
Sandbox	Never billed.

Limits

Per-partner caps return 429 rate_limited with a Retry-After header:

• 10 lookups in flight at once;
• 200 lookups per KST day.

details.scope is in_flight or daily; details.retry_after_seconds matches the Retry-After header. The daily cap resets at the next KST midnight.

capacity_exceeded (429) is reserved for global capacity admission. It is not returned yet, and sandbox never returns it.

Sandbox

Sandbox is available to every partner and completes lookups from synthetic fixtures. It never calls CarHistory. Any other valid plate or VIN returns the clean fixture.

Plate	Outcome
00가0000	completed, clean
00가0001	completed, with own-vehicle damage paid by the other party’s insurer, other-vehicle damage, an owner change, uninsured month ranges and a value range
00가0002	completed, with absent sections (null) and unreadable summary values
00가0404	failed, no_record
00가0503	failed, provider_unavailable

VIN	Outcome
LMNSBX00000000000	completed with key_used: "vin"
LMNSBX00000000001	completed with key_used: "plate" through the inventory fallback
LMNSBX00000000404	failed, no_record, after trying both VIN and plate

Production availability

Production is enabled per partner after onboarding. Until then, POST /v1/history-lookups returns 403 history_lookup_not_enabled.