From the VIN to the economic evaluation: the vehicle route

A damaged vehicle is in the yard, the seller wants a price, and the decision happens in minutes. Relying on experience alone means overpaying on unusual series and leaving money behind on ordinary ones. The vehicle route of the tapinomahub API starts exactly where the buyer starts: at the vehicle identification number — and ends at a traceable figure with an order of work for dismantling.

Stage 1: make the vehicle unambiguous

GET /vin/{vin}/vehicle matches the VIN against the enabled source. includeEquipments, includeColors and includeTechnical control how deep the answer goes; country sets the market context and provider the contractually agreed source. A successful match contains a stable tapiId — the reference by which every later call means the same vehicle. The service description is in Compare vehicle data by VIN.

curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/vin/WVWZZZ1KZAW000000/vehicle?includeEquipments=true&includeTechnical=true'

Stage 2: the vehicle's parts list

GET /vin/{vin}/parts returns the OE positions found: per part number and numberUnformatted, name and nameAddition, category, manufacturer, amount, price, tapiGenArt and the required vdi field. vdi contains confirmed full VDI 4081 codes and remains present as [] when no valid mapping is available. More important than the list itself is how it is qualified: matchLevel states how reliable the assignment is, and missingCategories states what is absent. A non-empty missingCategories explicitly means the parts list is incomplete. Details in Compare parts assignments by VIN.

Handling the asynchronous job properly

The parts list and the evaluation can take longer than an HTTP response should wait. The API therefore either answers 200 immediately or accepts the job with 202 — including Location, Retry-After and a jobId. That is the documented normal case, not a malfunction.

1. Handle both answers. An integration that only knows 200 works in testing and fails in production. 202 supplies jobId, statusUrl, status and retryAfterSeconds.
2. Poll at the stated interval, not in a tight loop. GET /vin/parts/jobs/{jobId} and GET /vin/economic-evaluation/jobs/{jobId} return queued, running, succeeded or failed.
3. On `succeeded` the result is in `result` — the same structure as a direct 200 response. Your code therefore needs only one parsing path.
4. On `failed`, `error.code` distinguishes vehicle_not_found — an empty business finding — from vin_service_unavailable, a technical outage. Only the second justifies a retry.
5. The job reference belongs in the record. Lose it and the result cannot be collected; an unknown job ends in 404 vin_parts_job_not_found.

# 202 Accepted: {"jobId":"8f1c…","status":"queued","retryAfterSeconds":5,…}
curl \
  -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/vin/parts/jobs/8f1c2f9e-2a44-4b7f-9a1e-6d4b8f0c3a21'

Stage 3: the economic evaluation

GET /vin/{vin}/economic-evaluation combines the parts list with market prices and calculates three things: the vehicle's revenue potential, an order of work for dismantling and a purchase recommendation. The response discloses its assumptions so that every figure can be recalculated — see Create an economic evaluation by VIN.

• `coverage` makes the data situation visible: totalParts, excludedIrrelevant, relevantParts, selectedParts, pricedParts and unpricedParts. A high unpricedParts is a warning sign, not a detail.
• `revenuePotential` gives min, average and max. The range stays fully visible — it is not compressed into one number.
• `purchaseRecommendation.goodPurchasePriceEur` is the figure for the conversation in the yard: recoveryRate times the minimum, less the assumed cost per priced part.
• `assumptions.priceBasis` reports min. The result therefore documents the basis the recommendation rests on.
• `parts[]` carries rank, number, name, category and pricing with min, average, max, confidence and evaluatedAt. The amounts in pricing are per unit.
• `amount` comes unchanged from the provider's parts list, is unverified and enters no calculation. The arithmetic uses one unit per part.

Billing: the monthly VIN bundle

• VIN Vehicle, VIN Parts and VIN Cart Check form the bundle `VIN_MONTHLY_LOOKUP`. Billing and repetitions are governed exclusively by the agreed terms. Cache or result reuse does not change customer billing.
• The `X-Tapinoma-Billing-Bundle` header is set when a call falls under that cap. X-Tapinoma-Billing-Source names the billing decision alongside it.
• A plan applies per endpoint key, not across the board. If no plan covers the call or the monthly quota is used up, the balance is charged; if that is not enough, the API answers 402 insufficient_credits.
• `404 vin_not_resolvable` marks a lookup that was not performed; its commercial treatment follows the terms shown before ordering and agreed in the contract.
• The sandbox follows the agreed terms. It uses the same base address, answers only with documented synthetic test data and behaves as described for validation, rate limits and asynchronous states — the right place to build your 202 handling.

The workflow when buying

1. Capture the VIN — typed, from the registration document via POST /scanner/document/registration, or from the vehicle via POST /scanner/vin/extract. Seventeen characters, otherwise 400 invalid_vin.
2. Match the vehicle and record tapiId, the matchLevel of later calls and incomplete in the record.
3. Request the parts list and handle 202 properly. Store the job reference, poll at the stated interval.
4. Request the evaluation with your assumptions, not the defaults. Your business knows its recovery rate and cost per part better than any default.
5. Show recommendation, range and coverage together. A figure without coverage next to it invites confidence the data does not support.
6. Plan dismantling by rank. The first positions carry the revenue; the rest decide how long the vehicle occupies the hall.
7. Reconcile after selling: achieved revenue against the recommendation, priced parts against sold parts. That is how your own reliable recoveryRate comes about.

Limits you need to know

• An evaluation is not a price guarantee. It is indicative, it rests on market offers and assumptions, and it does not replace an inspection. No VIN lookup sees damage, mileage or completeness.
• Coverage depends on the source. Depending on manufacturer, year and market, the amount of available data differs. incomplete, missingCategories and unpricedParts are the fields that make that visible.
• A VIN relates to a vehicle and can become personal data. Transmit only what you are authorised to transmit, and only what the purpose requires. Retention in your own system follows your agreement and your deletion periods.
• `vehicle_type_candidates` is not a fitment statement. At that level the list describes the vehicle type, not the individual vehicle.
• The parts list is not an inventory. It says what can be fitted in this type — not what is still fitted in this vehicle and sellable. The inspection makes that difference.

Schemas, error codes and example responses are in the developer documentation. Once the evaluated vehicle becomes individual parts, continue with From the OE number to a marketplace-ready article and, once those parts are on the bench, with From part photo to listing: the image route through the tapinomahub API.