Leasing companies and remarketing: return, condition and listing through the API

Where data goes missing in the process

A vehicle return is a short appointment with many transfers: the registration document is photographed and typed up later, the condition goes into a free-text field, the listing is assembled from the contract record — which does not always describe the vehicle that actually came back. Gaps regularly arise at five points:

• At acceptance. The VIN from the contract and the VIN on the document are not cross-checked; typing errors surface only when the listing is live or the deregistration fails.
• In the condition protocol. Every site photographs and describes differently. Two reports on the same damage are not comparable, and a buyer on the auction platform can rely on neither.
• In the listing. Title, description and equipment list are written by hand for each vehicle — and once more in another language for every target market.
• Before release. Nobody systematically checks whether an open recall exists for the model series, although the vehicle is going to a new keeper.
• At the end of the chain. Vehicles that can no longer be marketed go to dismantling without a data basis: whether they legally count as end-of-life vehicles and what the parts still yield remains guesswork.

What the API delivers

One process from start to finish

1. Before the walk-around: reset the vehicle. Infotainment to factory settings, pairings disconnected, storage media removed — while the vehicle still has power. This is not an API call but a field in the return protocol; why is explained in Data in the end-of-life vehicle.
2. Create the return in one call. The app at the site uploads the photo of the document and up to 5 walk-around photos; the backend calls POST /vehicles/intake with fileUrl and photoUrls. Back come the document fields, the vehicle data with tapiId and the condition report in eight zones. components states for each part whether it was delivered; commercial treatment follows the terms shown before ordering and agreed in the contract.
3. Check the plate against the contract. From one front photo, POST /vision/license-plate reads characters, country and confidence — for comparison with the contract record, not as a keeper lookup.
4. Match recalls before release. GET /recalls/vehicles/{vin} checks the model series against the official registers. A campaign with a stop-drive flag blocks the release in your own system; the others are completed before hand-over or attached to the listing as a note.
5. Generate the listing. POST /vehicles/{tapiId}/listing with language per target market and dealer notes in notes returns title, description and equipment highlights from the documented vehicle data. Price and condition statement are added by your own software; the text invents no properties.
6. Classify vehicles that cannot be marketed. Where accident, defect or age rule out remarketing, POST /vision/vehicle/elv-classification delivers the classification from 1 to 10 photos with evidenced criteria; the legal distinction is covered in Used car or end-of-life vehicle and Accident vehicles. What the vehicle still yields in dismantling is answered by GET /vin/{vin}/economic-evaluation with provider=1 — a long-running operation that answers with 202. The evaluation requires the vehicle match with provider 1, which the intake does not deliver: for third-party systems it runs through the user's browser via POST /vin/redirect-sessions; the call follows only after the return with status=completed.
7. Store the identifier. The tapiId goes into the vehicle file. GET /vehicles/{tapiId} later delivers technical vehicle data as part of the previously paid VIN workflow — without VIN and equipment and without a renewed match.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <IDEMPOTENCY_KEY>' \
  -d '{
    "fileUrl": "https://example.com/return/registration.jpg",
    "photoUrls": [
      "https://example.com/return/front.jpg",
      "https://example.com/return/rear.jpg"
    ]
  }' \
  'https://api.tapinomahub.com/vehicles/intake'

The integration

1. Keep the key server-side. The X-Api-Key header is set only from the backend. The return app talks to your server, never to the API directly.
2. Start with one endpoint. POST /vehicles/intake replaces three captures at once and is the most rewarding entry point. Recalls, listing and end-of-life classification follow as separate steps.
3. Define the field mapping. Which document fields, vehicle data and zones of the condition report land in which fields of the return protocol? That mapping is the actual work; the reference is in the integration guide.
4. Separate failure from empty result. For the intake, an empty result is a 200 response: if the VIN stays unreadable or the data path does not answer, components.vehicle is vin_not_readable or unavailable and complete is false. The return is created, the document fields taken over, the match remains follow-up work. 404 vehicle_not_found is the empty result for the VIN at GET /vin/{vin}/vehicle and the economic evaluation; at POST /vehicles/{tapiId}/listing and GET /vehicles/{tapiId} the same code means an unknown or foreign tapiId. For the recall match, 404 means the VIN cannot be resolved from the existing stock. Commercial treatment follows the terms shown before ordering and agreed in the contract. Retry only when the analysis could not be performed at all.
5. Build in retrieval for `202`. The economic evaluation answers with 202, Location, Retry-After and a job ID; GET /vin/economic-evaluation/jobs/{jobId} retrieves the result — from a queue in your backend, not from the app.
6. Roll out site by site. One return site first, then the others. GET /client/usage shows which calls run how often; X-Tapinoma-Usage-Warning signals low credit.

What to watch out for

• Set `Idempotency-Key`. An app on a mobile network occasionally sends twice; with the header, the second call is recognised as a repeat (X-Tapinoma-Idempotent-Replay) and not billed twice. Exception: calls that issue a key are not replayed — after a timeout, reconcile what exists instead of creating again.
• Leave empty fields empty. An unread document field, a zone without findings, a vehicle without a match: the result names the gap, and the software takes it over as a gap — no default value, no completion from the contract.
• Store `tapiId` on the file. It is the stable identifier for listing and vehicle data. Whoever discards it matches the same vehicle a second time.
• Never put the key in the browser. Neither in the return app nor in the dealer portal. Every call goes through your backend.
• Plan for rate limits. A bulk import from the archive belongs in a queue. Limits per user, key or endpoint are set by you via PUT /client/users/{clientId}/rate-limits.
• Have the result checked. Condition report, recall match and listing copy are working aids; the release remains a decision in your own process. A performed image analysis is billed, even without findings.

What the API does not do

The condition report is not an appraisal and contains no repair or residual value calculation; it describes what is visible in the photos and marks zones without findings as such. The plate is read, not checked against a register; there is no keeper lookup. The listing copy names no prices, and the economic evaluation is a purchase recommendation from market references, not a price guarantee — how a purchase is calculated is covered in Vehicle purchasing. Vehicle data from provider 1 cannot be fetched 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 execution of the query or analysis; the result is checked and used by you and your customers.