Salvage exchanges and auction platforms: listing, bidding and calculating through the API

Where data goes missing in the process

A salvage exchange depends on both sides trusting the listing: the lister has to describe a vehicle completely in little time, the bidder has to decide within the bidding window what it is worth to them. Gaps regularly arise at five points:

• When listing. The VIN is typed from the appraisal or from a photo; a swapped character surfaces only once a bidder has calculated the wrong vehicle.
• In the damage description. Every lister photographs and phrases differently. Two listings for the same damage pattern are not comparable.
• In the images. Nobody checks systematically before publication whether a photo still shows a legible plate; in parts auctions the images show serial numbers and other instance-specific identifiers the seller does not want to disclose before the hammer falls.
• In the listing copy. Title, description and equipment list are written by hand for each vehicle — and once more in another language for bidders abroad.
• At the bid. The dismantler calculates from experience within the bidding window: which parts yield revenue, what equipment the vehicle has, whether it may be transported as goods. The equipment is not in the photos, and the end-of-life classification remains guesswork.

What the API delivers

One process from start to finish

1. Identify the vehicle. The lister uploads the photos; the backend reads the VIN from the vehicle photo with POST /scanner/vin/extract. If it is not readable, vin is null — the field stays empty and becomes follow-up work. If the registration document is at hand, POST /vehicles/intake with fileUrl handles this and the next step in one call.
2. Match the vehicle and obtain a `tapiId`. With provider 2 or 3, GET /vin/{vin}/vehicle answers directly. Provider 1 may not be retrieved directly by a third-party system: the backend creates a session from vin, returnUrl and state with POST /vin/redirect-sessions and sends the user to redirectUrl; after the match in the tapinoma interface they return to returnUrl with status=completed, tapiId and state — or with status=cancelled. Vehicle data is never in the redirect; the session expires after ten minutes. The VIN process and the later listing calls run under the same key, because the tapiId is bound to the client that obtained it.
3. Document condition and damage. The walk-around with up to 8 photos goes to POST /vision/condition-report and returns as a finding per zone with overall grade A/B/C. The actual damage is described by POST /vision/damage/describe from 1 to 5 photos in six fixed sections; sections without findings are stated as such, and only what is visible is described — see Accident vehicles.
4. Check images before publication. POST /vision/license-plate reads from up to 3 photos the characters, country, confidence and position on the vehicle (vorne/hinten); with the characters your software checks the vehicle against the order, and a non-empty plates shows before publication that an image still contains a legible plate. The masking itself is not something the API does. In parts auctions, POST /vision/identifiers/redact anonymises instance-specific identifiers in the part image before it goes live; type and OE identifiers remain visible — see Part images.
5. Generate the listing copy. POST /vehicles/{tapiId}/listing with language per target market and lister notes in notes returns title, description and equipment highlights from the documented vehicle data. The text invents no properties and states neither prices nor condition.
6. Bidder side: calculate before bidding. Before the evaluation, the bidder completes the provider 1 vehicle match via POST /vin/redirect-sessions under their own key. Only then does GET /vin/{vin}/economic-evaluation run with provider=1: it answers with 200 if the parts list and market price assessments are already available, otherwise with 202, Location, Retry-After and a job ID; the result is then collected by GET /vin/economic-evaluation/jobs/{jobId}. It contains the parts revenue potential as min/average/max, a dismantling ranking sorted by revenue and a purchase recommendation. Small parts are filtered out, and market price assessments are reused for up to 30 days — see Vehicle purchasing and Dismantling depth.
7. Bidder side: classify as end-of-life. Whether the vehicle is transported as goods or as waste after the hammer falls decides logistics and paperwork. POST /vision/vehicle/elv-classification delivers from 1 to 10 photos the level kein_altfahrzeug_verdacht, gutachten_empfohlen or altfahrzeug; altfahrzeug is assigned only on a highly evidenced criterion or from the arithmetic with a supplied market value and repair estimate. The legal distinction is covered in Used car or end-of-life vehicle.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/vin/<VIN>/economic-evaluation?provider=1'

The integration

1. Store the key server-side. The X-Api-Key header is set only from the backend. Neither the lister interface nor the bidder app talks to the API directly; the redirect session is created on the server as well.
2. Start with one endpoint. Listing side: POST /vision/condition-report, because it makes listings comparable; bidding side: the provider 1 vehicle match via POST /vin/redirect-sessions under the bidder's own key, only then GET /vin/{vin}/economic-evaluation with provider=1. Plate, listing and end-of-life classification follow as separate steps.
3. Define the field mapping. Which zones of the condition report and which values of the evaluation land in which fields of the listing and the bidder view? That mapping is the actual work; the reference is in the integration guide.
4. Separate failure from empty result. 404 vehicle_not_found and vin being null are empty results, not errors: create the listing, leave the field empty, keep the match as follow-up work. A completed image analysis is billed even without findings; retry only where it could not be performed at all.
5. Build in the pick-up on `202`. The economic evaluation answers with 200 if the parts list and market price assessments are already available, otherwise with 202, Location, Retry-After and a job ID; the result is then collected by GET /vin/economic-evaluation/jobs/{jobId} from a queue in your backend — not from the bidder's browser. Your software has to handle both answers.
6. Roll out step by step. First one group of listers, then the bidders. GET /client/usage shows which calls run how often; X-Tapinoma-Usage-Warning reports low credit.

What to watch out for

• Set `Idempotency-Key`. An upload submitted twice must not trigger a second analysis; the header makes the repeat recognisable (X-Tapinoma-Idempotent-Replay), and billing happens once. Exception: calls that issue a key are not replayed — after a timeout, reconcile what exists.
• Leave empty fields empty. An unreadable VIN, a zone without findings, a position without a market reference: the result names the gap, the listing shows it — no default value, no completion from a similar vehicle.
• Store the `tapiId` on the listing — together with the client. It is the stable identifier for listing copy and vehicle data; GET /vehicles/{tapiId} later delivers the technical data as part of the previously paid VIN workflow, but only with the key of the client that obtained the tapiId there. With any other key the API answers 404.
• Never put the key in the browser. Neither in the lister interface nor in the bidder app. Every call and every redirect session runs through your backend.
• Plan for rate limits. Before an auction closes, many bidders query the same listings; evaluations belong in a queue, not in the click. Limits per user, key or endpoint are set via PUT /client/users/{clientId}/rate-limits.
• Have the result checked. Condition report, damage text and purchase recommendation are working aids; the bid remains the bidder's decision, the release of the listing the lister's.

What the API does not do

Condition report and damage text are not appraisals and contain no repair or salvage value calculation; they describe what is visible in the photos. The plate is read, not checked against a register; there is no keeper lookup. The economic evaluation is a purchase recommendation from market references, not a salvage value and not a price guarantee — the salvage value arises on your platform from the bids. Vehicle data from provider 1 cannot be retrieved directly by a third-party system via GET /vin/{vin}/vehicle; that match runs through the user's browser via POST /vin/redirect-sessions. No data set is sold: what is owed is the performance of the query or analysis; the result is checked and used by you, your listers and your bidders.