Claims management and insurers: estimates, condition and salvage value via API

Where data is missing in the process

A claim file consists largely of documents and photos whose content does not exist as a record. The estimate arrives as a PDF, the photos come from the first notice of loss. Whatever is needed in fields is read off and typed in by someone today.

• Estimates and appraisals arrive as PDFs. Totals, spare parts, labour items and equipment codes are transferred by hand for review and comparison.
• The damage is photographed but not described. The claims handler writes free text that differs from colleague to colleague.
• The condition outside the damage zone is undocumented. For salvage value and disposal, what is not damaged counts too — a dismantler values precisely those parts, see Body panels: assessing condition and describing it honestly.
• Repair or end-of-life is decided by feel. Whether a vehicle is goods or waste after the loss determines its onward route — see Used vehicle or end-of-life vehicle? The line that decides export.
• Vehicle identity and recalls live in separate sources and rarely end up in the same file.

What the API delivers

A workflow from start to finish

1. First notice with photos. 1 to 5 photos of the same damage go to POST /vision/damage/describe; back comes a description in six fixed sections that sits in the file as a finding, not as free text.
2. Match the vehicle. The VIN goes to GET /vin/{vin}/vehicle with provider=2 or provider=3; provider 1 is reachable from third-party systems only via the browser redirect and is required if the economic evaluation is to follow later. The match binds the VIN for this client to the chosen provider. Back come vehicle data and a tapiId — or 404 vehicle_not_found: no record, the field stays empty, the case continues.
3. Read the estimate. The PDF goes via fileUrl to POST /scanner/document/calculation. Totals, repair assessment, line items and equipment with DAT codes as strings are then available as fields — only values from the document, nothing is added.
4. Check recalls. GET /recalls/vehicles/{vin} returns model-line-related measures including the stop-drive flag before the vehicle is released for repair.
5. Condition and classification. Up to 8 walk-around photos go to POST /vision/condition-report; 1 to 10 photos with market value and repair estimate go to POST /vision/vehicle/elv-classification. The level altfahrzeug arises only from a highly evidenced criterion or from arithmetic with the values supplied.
6. Prepare the salvage question. GET /vin/{vin}/economic-evaluation accepts only provider=1 and requires that the vehicle was matched via provider 1 beforehand — from third-party systems only via POST /vin/redirect-sessions with a return of status=completed and tapiId; a VIN matched via provider=2 or provider=3 is bound to that provider. The evaluation then returns the parts revenue potential as min/average/max and a dismantling ranking; status via GET /vin/economic-evaluation/jobs/{jobId}. That is a basis for calculation, not a salvage value — that arises from bids, see Accident vehicles: write-offs, salvage value and what matters to a dismantler and Vehicle purchasing: what an end-of-life vehicle is really worth.
7. Close the file. tapiId, document fields and findings stay in the file; GET /vehicles/{tapiId} later returns the technical vehicle data as part of the previously paid VIN workflow, without VIN and equipment.

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

The integration

1. Store the key server-side. The API key belongs in the backend configuration and in the X-Api-Key header — never in a browser application.
2. Start with one endpoint. Usually POST /scanner/document/calculation, because that is where typing happens today; technically an HTTPS call with JSON, independent of language and platform.
3. Define the field mapping. Which response fields land in which fields of the claim file? That mapping is the actual work.
4. Separate failure from no-finding. 404 vehicle_not_found, a null field or a section without findings are business results and are stored; a technical error triggers a retry or a task, never a default value.
5. Build the `202` pick-up. Long-running calls answer with 202, Location and Retry-After; the status is fetched from the corresponding .../jobs/{jobId} endpoint. Until then the case stays „in progress“.
6. Roll out and observe. One tenant first, then all; GET /client/usage and GET /client/credits show calls and credit.

What to watch out for

• Set an `Idempotency-Key`. A retry after a timeout then returns the same response, recognisable by X-Tapinoma-Idempotent-Replay. Calls that issue a key once are not replayed: after a timeout, reconcile against the existing state instead of retrying blindly.
• Do not fill empty fields. A null in the estimate means the document does not state the value; a section without findings means nothing visible. Both belong in the file as they are — no default, no estimate.
• Store the `tapiId`. It is the stable identifier of the matched vehicle and the key for every later query without a new match.
• Never put the key in the browser. For provider 1 too: the backend creates a single-use session via POST /vin/redirect-sessions from vin, returnUrl and state; the return carries only status, tapiId and state, never vehicle or access data. The session expires after ten minutes.
• Rate limits per tenant. PUT /client/users/{clientId}/rate-limits limits per user, key or endpoint so that one batch run does not slow the other tenants; X-Tapinoma-Usage-Warning signals low credit.
• Have results checked. The damage description replaces no inspection, the classification no appraisal, the revenue potential no salvage value. The file shows which field came from which call.

What the API does not do

The API produces no appraisal and replaces no appraiser: the condition report contains no repair or salvage calculation, the damage description covers only what is visible, and the level gutachten_empfohlen means exactly that — appraisal recommended. It performs no keeper lookup and no check against the registration register; the recall check is model-line-related and a working aid — whether an individual vehicle is affected and a measure completed is answered bindingly only by the manufacturer. Price evaluations and revenue potential are indicative, not a price guarantee. Provider 1 is reached by third-party systems only via the browser redirect. And tapinomahub sells no data set: what is owed is the execution of the query or analysis — a completed image analysis is billed even without findings — and checking and using the results is the customer's responsibility. What vehicle data in a claim file means under data protection law is covered in Data in an end-of-life vehicle: what stays in the infotainment when the car goes.