Dealer management systems: vehicle intake and matching through the API

Where data is missing in the process

A DMS creates vehicles at many points: at trade-in, at used-car purchase, at service reception of a vehicle from another brand, at the import of a fleet. Each time a registration certificate lies on the counter, and each time someone transfers its fields by hand.

• Trade-in. The customer sits alongside while the salesperson types VIN, first registration and key numbers into the valuation form. A transposed digit in the VIN surfaces only when the marketplace rejects the record.
• Technical file. What the document does not state — gearbox, drivetrain, body — is added from memory, from a manufacturer site, or not at all. For other brands there is no manufacturer access at all.
• Listing text. Title and description come from text modules that may or may not fit the vehicle.
• Service reception. Which recall campaigns are published for the model line is something the service advisor looks up in a manufacturer portal outside the DMS — for other brands often not at all. Whether a campaign has been completed on the individual vehicle is answered only by the manufacturer portal, even with the API in place.
• Parts ordering. Whether an OE number fits this exact vehicle is decided by the parts desk from catalogue and experience. For components with many variants, that is a frequent source of wrong orders.

What the API delivers

A process from start to finish

1. Photograph the document. The salesperson photographs the registration certificate in the DMS app. The DMS stores the file on its own server and passes its address as fileUrl to POST /vehicles/intake; walk-around photos, up to 5 shots, go along as photoUrls.
2. Write the response into the file. Document fields fill VIN, first registration and type data; vehicle data with tapiId fill the technical file; the condition report is attached. components states per component whether it was delivered; one not delivered leaves its fields empty and is refunded proportionally. The match in the intake always runs via provider 2; provider in the response is always 2.
3. Provider 1 match as an alternative. If the vehicle is to be matched via provider 1 instead, GET /vin/{vin}/vehicle answers a third-party system with redirect_required. The DMS then creates a session server-side with POST /vin/redirect-sessions from vin, the absolute HTTPS returnUrl and a state for its own transaction, and sends the salesperson to the redirectUrl.
4. Handle the return. After the match in the tapinoma interface the salesperson 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.
5. Reload vehicle data. With the stored tapiId the DMS calls GET /vehicles/{tapiId} as part of the previously paid VIN workflow — without VIN and without equipment.
6. Generate the listing. POST /vehicles/{tapiId}/listing with language and optional dealer notes in notes returns title, description and equipment highlights. The text invents no properties and names neither price nor condition.
7. Prepare service. GET /recalls/vehicles/{vin} lists campaigns for the model line from the official registers. Prerequisite: the VIN was matched before via POST /vehicles/intake or a VIN process of this client, because it is resolved only from the client's own stock built by a previous VIN lookup, not from a supplier; otherwise the endpoint answers 404 vin_not_resolvable. Its commercial treatment follows the terms shown before ordering and agreed in the contract. Whether a campaign has been completed on the individual vehicle is still answered only by the manufacturer. Before a parts order, POST /vin/cart-check checks up to 30 OE positions against the vehicle (mode=vehicle) or the type (mode=type); for control units, coding remains the workshop's job, see Used control units: coding, immobiliser, listing.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <CASE_NUMBER>' \
  -d '{"fileUrl": "https://dms.example/documents/4711.pdf", "photoUrls": ["https://dms.example/photos/4711-front.jpg"]}' \
  'https://api.tapinomahub.com/vehicles/intake'

The integration

1. Keep the key server-side. The API key is sent as the X-Api-Key header from the DMS backend and belongs in its configuration — never in the browser interface, never in a mobile app, never in source code.
2. Pick one endpoint. POST /vehicles/intake is the natural starting point because it covers vehicle intake in a single call. Anyone who only wants to read the document begins with POST /scanner/document/registration.
3. Define the field mapping. Which response field lands in which field of the file? That mapping is the actual work. The file also needs a field for the tapiId and a note of which values came from the lookup.
4. Distinguish an empty result from an error. 404 vehicle_not_found is not an error but an outcome: not found. The DMS still creates the file, leaves the fields empty and raises a follow-up — „no hit“ never appears to the user as a red error message. A dropped connection, by contrast, may be retried, with the same Idempotency-Key.
5. Collect long-running jobs. If an endpoint answers 202, Location and Retry-After name the job and the waiting time. The status is collected at the job endpoint, for the parts check via GET /vin/cart-check/jobs/{jobId} — not by calling the original endpoint a second time.
6. Roll out and observe. One pilot dealership first, then the rest. 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`. If a connection drops, the DMS repeats the call with the same key and receives the same response, recognisable by the header X-Tapinoma-Idempotent-Replay. The exception is calls that issue a secret key (sub-users, partner workspaces): after a timeout, reconcile against what exists instead of repeating blindly.
• Leave empty fields empty. If the response returns null, the field stays empty — no default, no derivation from the world manufacturer identifier. A plausible entry in a listing is more dangerous than a visible gap.
• Store the `tapiId`. It is stable and the key to GET /vehicles/{tapiId} and POST /vehicles/{tapiId}/listing. Whoever loses it pays for the match again.
• Never put the key in the browser. The interface talks to its own backend, the backend to the API. The redirect session for provider 1 is also created server-side; the browser sees only the redirectUrl.
• Set rate limits per user. PUT /client/users/{clientId}/rate-limits limits per user, key or endpoint so that a faulty import does not use up the whole dealership's credit.
• Have the result checked. Listing text, recall list and fitment statement are working aids. The salesperson reads the text before publishing, the service advisor checks the model-line recalls against the manufacturer portal, and complete=false means a no is not final.

What the API does not do

The API delivers no valuation and no appraisal: the condition report from POST /vehicles/intake describes what is visible, it calculates neither repair nor residual value. It performs no keeper lookup and gives no price guarantee — the listing text deliberately names no price. 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; its use lies with the dealership. What the material does not yield remains a gap — why is explained in VIN lookup in practice: process, result, billing.