Fleet management systems: vehicle data from intake to defleet

Where data is missing in the process

A fleet system is only as good as its master data. In practice that data is created where someone types up a document or assigns a photo by hand. Typical gaps:

• At intake. The registration certificate is typed up — for international fleets from documents laid out differently in every country. Errors in VIN, type codes or first registration travel into every later report. See The registration certificate: the fields that matter in the yard.
• In damage and driver reports. A photo arrives with a licence plate but no vehicle identifier; someone searches the plate in the stock and assigns it.
• With recalls. Manufacturer letters and register notices are checked against the stock by hand, often only once a driver asks.
• At return. Condition is ticked on a form and the photos sit unstructured next to it; in a dispute the link between finding and photo is missing.
• At defleet. Sale, export or recycling is decided without a figure basis — and without asking whether the vehicle is legally still goods. See Used vehicle or end-of-life vehicle? The line that decides export.

What the API delivers

One process from start to finish

1. Intake. The registration document goes as image or PDF via fileUrl to POST /scanner/document/registration/international. The normalised core fields fill the master data, sourceValue keeps the print. Names, addresses, plates and VIN are never translated.
2. Identification. The recognised VIN goes to GET /vin/{vin}/vehicle; providers 2 and 3 answer directly, provider 1 answers third-party systems with redirect_required. The backend then creates a session via POST /vin/redirect-sessions from vin, returnUrl and state and sends the user to redirectUrl; the match runs in the tapinoma interface, the return carries status=completed, tapiId and state — never vehicle data. The session expires after ten minutes. Structure of the number in VIN: Reading, checking and using the vehicle identification number.
3. Operation. A damage report arrives with a photo. POST /vision/license-plate returns from up to 3 images the characters, a comparison form and the country as ISO 3166-1 alpha-2; the comparison form is matched against the stock.
4. Recalls. A nightly run calls GET /recalls/vehicles/{vin} for the stock; the VIN is resolved only from the own, previously matched stock, with no supplier call. A measure with a stop-drive flag creates a block and a task.
5. Return. Up to 8 walk-around images go to POST /vision/condition-report. The findings per zone — front, left side, right side, rear, roof, interior, engine bay, other — and the overall grade land in the return record; which image belongs to which zone is recorded by the fleet system itself, the response only carries imageCount.
6. Defleet. POST /vision/vehicle/elv-classification clarifies from 1 to 10 images whether there is an end-of-life suspicion; gutachten_empfohlen means an expert report must carry the decision. For sale or recycling, GET /vin/{vin}/economic-evaluation with provider=1 returns the parts' revenue potential as min, average and max — 200 straight away when the parts list and valuations are already available, otherwise 202 with a job ID and the result via GET /vin/economic-evaluation/jobs/{jobId}. Context in Accident vehicles: write-offs, salvage value and what matters to a dismantler and Vehicle purchasing: what an end-of-life vehicle is really worth.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"fileUrl": "<FILE_URL>"}' \
  'https://api.tapinomahub.com/scanner/document/registration/international'

The integration

1. Keep the key server-side. The X-Api-Key lives in the backend configuration. Driver apps and browsers talk to your own server, never to the API directly.
2. Start with one endpoint. For a fleet system that is usually reading the registration document at intake; whoever holds a matched VIN stock starts with the recall check.
3. Define the field mapping. Which document field fills which master-data field? fields and sourceValue are kept, every field carries its provenance: document, match or hand.
4. Separate empty result from error. 404 vehicle_not_found is a domain-level empty result, not a technical error; a null field stays empty and raises a task. A completed image analysis is billed even without a hit.
5. Collect long-running calls. A 202 carries Location, Retry-After and a job ID. The backend polls the job endpoint and writes the result as soon as it is there.
6. Roll out in stages. One tenant first, then all. GET /client/usage shows which calls run how often; X-Tapinoma-Usage-Warning reports low credit.

What to watch out for

• Set `Idempotency-Key`. A repeated call after a dropped connection must not trigger a second analysis; X-Tapinoma-Idempotent-Replay marks the replay. Calls that issue a key are not replayed — after a timeout, reconcile the stock via GET /client/users.
• Leave empty fields empty. Whatever document or image do not yield comes back as null. A plausible default is more dangerous than a visible gap.
• Store the `tapiId`. It is stable, and GET /vehicles/{tapiId} returns the technical data as part of the previously paid VIN workflow — no second match every time the file is opened.
• Never put the key in the browser. Not in a driver app or a kiosk on site either.
• Rate limits per tenant. The recall run belongs in a time window, and PUT /client/users/{clientId}/rate-limits caps what a single user can trigger.
• Check the results. Confidence on the plate, match confidence on the recall and A/B/C on condition are statements about reliability, not decisions. What is owed is the analysis, use is the customer's — legally framed in Data in an end-of-life vehicle: what stays in the infotainment when the car goes.

What the API does not do

It does not identify a keeper: POST /vision/license-plate reads the plate from the photo without any register or keeper check. It does not replace an expert report: the condition report is a visual inspection without repair or residual-value calculation, and gutachten_empfohlen means exactly that. It guarantees no price: the economic evaluation names a revenue potential from market references, not a sale price. The recall check is a model-line-level working aid, not a vehicle-specific statement by the manufacturer. Provider 1 is reachable for third-party systems only through the redirect flow. And it sells no database: what is owed is the analysis and the output of the result. What goes into recycling can be accompanied by evidenced attributes — see CO₂ and used parts: what can honestly be said.