Vehicle marketplaces and listing portals: listings from the vehicle match instead of from typing

Where data is missing in the process

A listing is only as good as what the seller enters — rarely complete, not always correct. What is missing costs visibility in the filters and trust with the buyer; what is wrong costs enquiries and withdrawals. The typical points:

• Entering the vehicle. The seller copies VIN, first registration and type key numbers from the registration certificate. A transposed digit in the VIN surfaces only when a buyer compares the number with the vehicle; with foreign documents even the mapping of the fields is often unclear.
• Filter fields. Gearbox, drivetrain, body and engine are not fully stated on the certificate. What the seller does not enter stays empty, and the listing does not appear in the search.
• Listing text. Title and description come from text modules or are copied from the previous listing — including equipment this vehicle does not have.
• Photos. Shots from the yard with neighbouring vehicles in the background, inconsistent, often with a readable number plate. Whether one is readable is rarely checked before publishing; the masking itself remains the portal's job.
• Condition and recalls. Condition statements come from the seller and are not evidenced; whether a recall campaign exists for the model line is known neither to the portal nor to the buyer.

What the API delivers

A process from start to finish

1. Photograph the document. The seller photographs the registration certificate; the portal backend stores the file and passes its address as fileUrl to POST /scanner/document/registration/international — for German certificates POST /scanner/document/registration is enough. The vehicle fields pre-fill the form; names, addresses, number plates and VIN are never translated, and the keeper fields are not taken over by the portal, see Data in an end-of-life vehicle: what stays in the infotainment when the car goes.
2. Start the vehicle match. For provider 1, GET /vin/{vin}/vehicle answers a third-party system with redirect_required. The backend therefore creates a session with POST /vin/redirect-sessions from vin, the absolute HTTPS returnUrl and a state carrying its own listing number, and sends the seller to the redirectUrl. Providers 2 and 3 can be queried directly.
3. Handle the return. After the match in the tapinoma interface the seller comes back to the returnUrl — with status=completed, tapiId and state, or with status=cancelled. Vehicle, equipment or access data never appear in the redirect; the session expires after ten minutes. The portal stores the tapiId on the listing.
4. Fill filter fields and text. GET /vehicles/{tapiId} returns the technical vehicle data as part of the previously paid VIN workflow, without VIN and without equipment. POST /vehicles/{tapiId}/listing with language and optional dealer notes in notes returns title, description and equipment highlights — no invented properties, no price, no condition statement.
5. Record the walk-around. Up to 8 shots go to POST /vision/condition-report; back come findings per zone in a fixed order and an overall grade A, B or C. POST /vehicles/intake combines document, vehicle match and condition report in one call — the match there runs fixed via provider 2 without redirect, and photoUrls takes up to five shots.
6. Prepare the photos. POST /vision/vehicle/remove/bg cuts out the vehicle; the model determines only the outline, the pixels remain those of the photo, see cut-outs without redrawing. POST /vision/license-plate says whether and which number plate is readable on a shot — characters, country, front or rear; it returns no image coordinates and masks nothing. If it reports a readable plate, the portal holds the release; the masking remains the portal's own task.
7. Show the recall notice. GET /recalls/vehicles/{vin} checks the model line against the official registers — Kraftfahrt-Bundesamt, EU Safety Gate, NHTSA. The VIN is resolved only from the existing stock, no supplier call is made. The portal shows the notice on the listing as a working aid.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <UUID_PER_TRANSACTION>' \
  -d '{"language": "en", "notes": "Tow bar retrofitted"}' \
  'https://api.tapinomahub.com/vehicles/<TAPI_ID>/listing'

The integration

1. Store the key server-side. The API key goes out as header X-Api-Key from the portal backend and belongs in its configuration — never in the listing form in the browser, never in source code.
2. Choose one endpoint. Reading the registration document at listing time is the obvious entry point because it immediately replaces typing errors. The listing text via POST /vehicles/{tapiId}/listing requires a completed VIN process and comes afterwards.
3. Define the field mapping. Which response field lands in which listing field? That mapping is the actual work. The listing additionally needs a field for the tapiId and a note of which values came from the lookup.
4. Distinguish empty result from error. 404 vehicle_not_found is not an error but a result: not found. The portal still creates the listing, leaves the fields empty and asks the seller to complete them — never as a red error message; status=cancelled on return is not an error either. A dropped connection, by contrast, may be retried with the same Idempotency-Key.
5. Collect long-running jobs. If an endpoint answers with 202, Location and Retry-After name the job and the waiting time. The status is collected at the associated job endpoint, not by calling the original endpoint a second time.
6. Roll out and observe. First one seller with a manageable stock, then the whole platform. GET /client/usage and the response header X-Tapinoma-Usage-Warning show credit consumption; the path from contract to go-live is described in the integration guide.

What to watch out for

• Set an `Idempotency-Key`. Recommended is a UUID per business transaction, at least 8 characters, such as listing-<no>-text-<uuid> — not the listing number alone, because a key counts as completed after the first success and document reading, redirect session and listing text would otherwise receive the same stored response. After a dropped connection the backend repeats the call with the same key and receives the same response, recognisable by the header X-Tapinoma-Idempotent-Replay; it is stored for 24 hours and only on success. The exception is calls that issue a secret key (sub-users, partner workspaces): after a timeout, reconcile the stock instead of blindly retrying.
• Leave empty fields empty. If the response returns null, the field stays empty — no default, no text module, no derivation from similar listings. Plausible equipment in a listing is more dangerous than a visible gap, because the buyer reads it as a promise.
• Store the `tapiId`. It is stable and the key to GET /vehicles/{tapiId} and POST /vehicles/{tapiId}/listing. Results belong in the portal's database, not in every page view; every request costs.
• Never put the key in the browser. The listing form talks to the portal backend, the backend to the API. The redirect session for provider 1 is also created server-side; the browser only sees the redirectUrl, and on return the backend checks that state belongs to one of its own transactions.
• Set rate limits per seller. PUT /client/users/{clientId}/rate-limits limits per user, key or endpoint, so that a faulty stock import by one dealer does not use up the portal's credit.
• Have the result checked. Listing text, condition report, cut-out image and recall notice are working aids. The seller reads the text and reviews the images before publishing; the recall notice applies to the model line, not as proof for this vehicle.

What the API does not do

The API does not value a vehicle and names no price — the listing text deliberately contains none, and there is no price guarantee. The condition report from POST /vision/condition-report describes what is visible and is not an appraisal; it calculates neither repair nor salvage value, see Accident vehicles: write-offs, salvage value and what matters to a dismantler. For the number plate there is no keeper lookup, no register check and no anonymisation — POST /vision/license-plate makes plates readable, not unreadable. Provider 1 is reachable for third-party systems only through the browser redirect. And it sells no data set: what is owed is the lookup or analysis with its result; responsibility for the listing stays with the seller. What the material does not yield remains a gap — why is explained in VIN lookup in practice: process, result, billing.