One POST when the job closes.

Push, not pull

CarKnown never reaches into your system. When a repair order closes (and the customer has approved sharing), your software POSTs the record. That's the whole integration.

Idempotent by design

Send your system's stable record id as sourceRecordId. Retries, crashes, and replays are always safe — the same record is never created twice.

How records are counted. A shop's profile and the “shops with published records on this engine” list on a vehicle page are built from one rule, applied in the database and nowhere else: a sealed record, not removed, attributed to a shop by shopId; a correction chain counts once; one record per shop per vehicle per day; history a shop imported from its own prior records is counted apart from work recorded as it happened. Engines are grouped by the identity CarKnown derives from the VIN — make, displacement, cylinders, fuel — never by anything a partner sends. Lists are sorted by published records on this engine, most first; ties by distinct vehicles, then most recent record, then name, and nothing renders until at least 3 shops each have at least 5 records on that engine. Nothing else is a count: no ratings, no repeat customers, no comeback rate, no technician data, no claimed specialty, no money, no partner-sent totals, no paid placement.

Send your system's stable id for the shop as shopId (and its URL slug as shopSlug, if it has one). shopName is free text and two shops can share one; shopId is what a shop's CarKnown profile and its verified-experience counts hang off. It is optional — a record without it is still sealed and still shows on the vehicle page — but it belongs to no shop, and the response says so. Engine identity is never sent: CarKnown derives it from the VIN, the same way for every partner.

What the shop measured. Trouble codes read, tests run, and the photographs and scope captures the shop holds, added to the same record. Every one is a fact about the vehicle on the day it was read, so it stays true for as long as the record stands. All optional:

  "dtcs": [
    { "code": "P0303", "status": "confirmed", "module": "PCM", "clearedAtVisit": true }
  ],
  "tests": [
    { "type": "compression", "result": "pass",
      "measurements": [
        { "name": "cylinder 3", "value": 165, "unit": "psi" },
        { "name": "cylinder 4", "value": 168, "unit": "psi" }
      ],
      "spec": { "min": 140, "unit": "psi" } },
    { "type": "scope.ignition-secondary", "result": "fail",
      "measurements": [{ "name": "burn time", "value": 0.6, "unit": "ms", "position": "cyl 3" }],
      "capture": { "sha256": "<SHA-256 of the capture file>", "channel": "A", "circuit": "coil cyl 3" } }
  ],
  "photos": [
    { "sha256": "<SHA-256 of the image file>", "kind": "issue" },
    { "sha256": "<SHA-256 of the image file>", "kind": "work" }
  ]

dtcs — code matching /^[PBCU][0-3][0-9A-F]{3}(?:-[0-9A-F]{2})?$/ (SAE J2012, optional failure-type byte); status one of confirmed, pending, permanent, history, or omit; module, description (your words, shown as yours) and clearedAtVisit optional. A code was read at the visit the record describes — codes read on another day belong on that day's record.

tests — type a lowercase key like compression or battery.load; result one of pass, fail, advisory (shown as the shop's result, never CarKnown's); measurements as { name, value, unit, position? } where value is a number and unit is one of psi kpa bar % v a ah cca ms hz ohm mm in 32nds f c rpm deg kv; spec and capture optional.

Names go in values, never in keys. CarKnown refuses any field whose name contains a money word — rate, charge, total, balance and the rest — so { "stateOfCharge": 78 } is refused and { "name": "state of charge", "value": 78, "unit": "%" } is not.

photos and a test's capture carry the SHA-256 of the file, never the file. The image stays with the shop; the sealed fingerprint proves it existed when the record was sealed and has not been swapped since. kind is one of issue, work, before, after, part. When photos is sent, the photograph count is taken from it.

Never sent: a licence plate, registration or fleet number — plate, registration, license and fleet are refused as field names. A plate is reissued to strangers and links a car to whoever holds it; a fleet number names the owner and changes on sale. Keep unit, asset and stock numbers in your own system.

A malformed code, test, measurement or photograph is dropped, the rest of the record seals, and the response names what was dropped in warnings and counts what was kept in facts. Limits per record: 50 codes, 30 tests, 24 measurements per test, 40 photographs.

Odometer units. Send mileageUnit with mileage, one of mi, km, h — miles, kilometres, or engine hours for equipment that runs on an hour meter. Omitted means miles, as mileage always has. A reading is only ever compared with one it can be: miles and kilometres against each other, converted exactly (1 mi = 1.609344 km) and flagged across units only when lower by more than one mile, so two honest readings rounded into different units never flag; hours only against hours, never against distance. An unknown unit drops the reading, with a warning, rather than guessing one. A correction can restate the unit alone — { "mileageUnit": "km" } — when the number was right and the unit was not; the reading it replaces stops counting, and any flag it raised is resolved.

Shapes and limits. A test type matches /^[a-z][a-z0-9]*(?:[-.][a-z0-9]+)*$/. Text is limited per field; text over its limit is dropped with a warning, never truncated, because cutting a shop's words short would change what it said:

• dtcs[].module — 16
• dtcs[].description — 200
• tests[].type — 60
• tests[].measurements[].name — 40
• tests[].measurements[].position — 16
• tests[].capture.channel — 8
• tests[].capture.circuit — 60
• tests[].capture.timebase — 24
• tests[].capture.scale — 24

Field names CarKnown refuses. Every key in a submission, at any depth, is split into words — partPrice, part_price and part-price are all part + price — and the whole record is refused if any word is on this list, which is printed from the code that applies it:

• money — prices, costs and payment details are between the shop and its customer: price prices cost costs amount total subtotal tax discount fee charge rate msrp markup margin invoice balance payment paid deposit currency
• customer — a record describes a vehicle, not a person: customer client owner email phone mobile address street zip postcode firstname lastname fullname dob license plate registration
• ownership — who owns a vehicle is not part of its record: fleet
• individual — records identify the shop, not the individual who did the work: technician tech mechanic advisor adviser writer sealer employee staff operator
• supply — who a shop buys parts from is its own business: vendor supplier distributor

Always allowed whatever words they contain, matched without regard to case: sourcerecordid signature signaturealg keyid.

CarKnown seals it

On ingestion the record is validated (including mileage consistency against the vehicle's history), hashed, and Ed25519-signed with CarKnown's published key. Anyone can verify it forever at its verify URL.

Say how the record came to exist

Send provenance: "captured" when your system recorded the work as it happened, or "imported" when a shop is bringing across its own prior records (add importedAt for when). CarKnown shows the difference to consumers, because it is a real difference in evidence. Omit the field and CarKnown records it as unstated — it will never assume the stronger claim on your behalf.

Backdate freely — history is the point

There is no limit on how far back occurredAt may be, and any number of shops can hold records on the same VIN. Only impossible dates are refused: the future, and anything before 1981 when the 17-character VIN began.

Every record must identify, date and describe

Required: vin, sourceRecordId, shopName, occurredAt, and something real in work or complaint. An absent date used to default to today, which stamped imported history as having happened this morning — so it is now required outright.

Work lines that say nothing — "L", "Labor", "Service" — are dropped with a warning, and a record left describing nothing at all is refused. Mileage stays optional; most shops never capture it.

Tag the kind of job, and grade the parts

Both optional. serviceTypes takes your own category keys — brakes.front, oil, emissions.dpf, whatever your platform classifies — so "Front brakes" and "R&R front pads and rotors" can be recognised as the same fact. You are not confined to a CarKnown list: any lowercase dotted key is kept and displayed, and CarKnown only decides how nicely it is named. Where you send none, CarKnown reads a tag from your own wording and marks it as read rather than stated.

Each part takes an optional grade: oem, oe-equivalent, aftermarket, remanufactured or used. Absent means you did not say, which is not the same as aftermarket.

Say how well evidenced the repair is, if you score it

Optional. Send evidence as { confidence: 0-100, band: "Well documented" }, where the band is the word your own scale puts on the figure. CarKnown shows it as your score, attributed to you, and describes it as how well corroborated the repair is rather than how well it was done.

Nothing is inferred if you omit it, and evidence that arrives malformed is dropped with a warning rather than failing the record — a real repair should not be lost over a score.

The same rules for every partner

One API, one set of fields, one validation path and one set of trust labels. No platform gets privileged standing, extra fields, or a softer check — including any platform connected to CarKnown today. A registry that graded its partners differently would not be worth reading.

Send only what's public

Descriptions, part names, mileage, photo count. Never prices, customer names, or contact details — the vehicle's record is public by design.