Decision guides

Each guide starts with what the caller actually has, then selects a documented goal and public operation. The OpenAPI contract remains authoritative for exact schemas and errors. If a branch below says “not documented”, stop rather than inventing an endpoint.

I have a VIN

Goal: retrieve vehicle data

1. Call GET /vin/{vin}/vehicle with the request parameters documented for the customer contract.
2. If the response requires a browser redirect, follow the documented redirect-session flow; otherwise consume the direct result.
3. Read tapiId, the returned selection value and the documented vehicle data from the success response.
4. Persist the VIN and tapiId separately; tapiId represents the matched technical vehicle type, not the individual physical car.
5. Continue with GET /vehicles/{tapiId} for technical vehicle data or POST /vehicles/{tapiId}/listing for listing text when needed.

Treat the numeric selection value as an opaque contract value. Do not infer capabilities, suppliers or data provenance from it.

Goal: retrieve vehicle-related parts

1. Call GET /vin/{vin}/parts with a full VIN and the request parameters documented for the customer contract.
2. Keep the optional numeric selection consistent for the same VIN. A conflicting value returns 409 vin_provider_mismatch.
3. On 200, map parts[], including each required tapiGenArt and vdi field, plus matchLevel, provider and the returned tapiId according to the schema. Preserve vdi=[] as the complete value for a position without a valid mapping.
4. On 202, persist the job and poll the required full statusUrl with GET /vin/parts/jobs/{jobId} after Retry-After. Compare Location with that documented URL and quarantine a mismatch rather than resolving its current root-relative example against the API origin.
5. Treat matchLevel as part of the result, not optional display text.

Do not retry the order merely because it returned 202. Do not discard positions. A successful VIN-parts position always includes exactly one tapiGenArt and one vdi array; an empty vdi array does not keep the job pending.

Goal: check an OE-number cart against the VIN

Use POST /vin/cart-check, not a parts lookup or SEO response. On 202, poll GET /vin/cart-check/jobs/{jobId}. Interpret the line results and the overall completeness field together. A negative line result in an incomplete comparison is not automatically a definitive exclusion.

Goal: match vehicle recalls

Call GET /recalls/vehicles/{vin}. The capability is a series-level match against the documented official registers and carries data-version information. Do not turn a match into a statement that a particular physical vehicle is affected beyond what the response schema says.

Goal: calculate an economic evaluation

Call GET /vin/{vin}/economic-evaluation only with a known full VIN and the documented request parameters. On 202, poll the required statusUrl for GET /vin/economic-evaluation/jobs/{jobId}. Keep the assumptions and returned result character with the evaluation.

Goal: calculate cluster-based VIN Economic Intelligence

Call POST /vin/economic-intelligence (createVinEconomicIntelligence) with a known full VIN, market country, currency, condition and a required Idempotency-Key. This follows the documented VIN-to-vehicle-parts-to-part-cluster Intelligence flow and is distinct from GET /vin/{vin}/economic-evaluation: its final result exposes evaluationId, pipeline coverage, a risk-adjusted portfolio, cluster candidates, confidence, provenance and warnings. The route belongs to a closed, allowlisted commercial pilot and currently returns 503 until VIN Economic Intelligence, approved positive pricing and atomic billing are enabled together. After enablement, a 202 is polled only through GET /vin/economic-intelligence/jobs/{jobId} (getVinEconomicIntelligenceJob); that status operation can continue to return 202 while work is pending. Do not automate acquisition from a result whose confidence, missing evidence or candidate exclusions violate the caller's review policy.

I have an OE number

Goal: validate and normalize the number

Call GET /parts/oe/normalize with the exact query parameter defined by OpenAPI. Use the returned status before reading normalizedOeNumber; the latter is null for every status other than matched.

Do not implement a local uppercase/whitespace rule and call it equivalent. Other OE operations state their own input treatment and may not use the same normalization behaviour.

Goal: retrieve the public base part

Call GET /parts/oe/{oeNumber}. A 200 response is a closed public object containing exactly:

• oeNumber
• normalizedOeNumber
• tapiGenArt
• vdi
• part
• fitment
• replacementChain
• references
• referenceNumbers

No confirmed base hit returns 404; an ambiguous input can return 422. The required part object proves that a base record exists, but its public enrichments manufacturer, name and listPrice can each be null. Preserve part.name as the returned string or null. The response always includes tapiGenArt as a valid code or null and vdi as an array of valid full codes or []; they are independent best-effort enrichments, and missing classification data does not invalidate the confirmed base part. tapiGenArt, vdi, fitment, a comparison number or a replacement edge cannot independently create a successful base-part hit.

Interpret the four relationship views separately. fitment contains the available type-level vehicle assignments and can be empty. references[] groups confirmed reference and comparison numbers by manufacturer, while referenceNumbers.oe_oem_reference_numbers[] is the consolidated confirmed list including the confirmed OE number. replacementChain carries confirmed directed from/to edges. Do not derive any of these views from another.

Goal: retrieve aftermarket references

Call GET /parts/oe/{oeNumber}/aftermarket-references. This operation states that it uses the submitted string without OE normalization. Returned references are not installation guarantees. If the business workflow needs a confirmed base part, run the base OE lookup separately rather than treating a reference result as equivalent.

Goal: evaluate price

Use GET /parts/oe/{oeNumber}/price. Preserve whether figures describe new or used ranges and the currency fields exactly as returned. The API result is an evaluation, not a sales-price instruction.

Goal: resolve a part cluster and inspect market intelligence

Call GET /parts/intelligence (resolvePartIntelligence) with oeNumber and, when known, its manufacturer plus kType, NatCode or GenArt context. A required Idempotency-Key represents one business request even though this is a GET. The current closed, allowlisted commercial pilot does not deliver real Intelligence results until approved positive pricing and atomic billing are active. Approved Observed Supply data and the authorised dealer panel are not yet available in production, and adaptive refresh is disabled; without an eligible materialized snapshot, the route returns a documented error instead of starting a refresh. kType, NatCode and GenArt can disambiguate but cannot independently establish cluster identity. On 200, retain the returned clusterId, clusterVersion, scope, timestamps, separated observedSupply, verifiedSales and internalUsage evidence, prices, standtime, trend, scores, confidence and provenance. After refresh enablement, a 202 is polled only through GET /parts/intelligence/jobs/{jobId} (getPartIntelligenceJob). Never map observed listings into verified sales or consume an Opportunity Score without its interval, factors, limitations and confidence.

Goal: optimise an eBay or marketplace article listing

Call GET /parts/oe/{oeNumber}/seo with the target marketplaceId, the content language and vehicleType. This one operation answers every "optimise my eBay article", "which category and item specifics does this part belong in" and "write the listing title for this OE number" goal. There is no separate eBay endpoint: the documented marketplaceId values are the eBay marketplaces EBAY_AT, EBAY_AU, EBAY_BE, EBAY_CA, EBAY_CH, EBAY_DE, EBAY_ES, EBAY_FR, EBAY_GB, EBAY_HK, EBAY_IE, EBAY_IT, EBAY_NL, EBAY_PL, EBAY_SG and EBAY_US, with EBAY_DE as the default. language accepts de, en, fr, es, it, nl, pl and zh.

A successful response carries the listing-ready output for that marketplace and language:

• content.ebayTitle — the article title for the eBay listing headline, inside the documented 80-character limit.
• categoryId — the category identifier for the requested marketplace; for an EBAY_* marketplace, the eBay category. Required-present and null when none is returned.
• itemSpecifics[] — the article's item specifics as {name, value[]} entries, one name able to carry several values.
• keywords[] — search terms for the listing and shop search.
• product — manufacturer, name and nameAddition for product naming.
• content.title, content.h1, content.metaTitle, content.metaDescription, content.slug, content.bulletPoints — the shop-side SEO text with the documented length limits.

A no-match is the documented, uncharged HTTP 404 PartSeoNoMatchResponse, not a success variant. The operation also has operation-specific live-availability behaviour: 429 seo_live_requests_paused and the optional liveAvailability object state when live enrichment can be requested again. Send no Idempotency-Key. Review the returned copy before publication; it is publication content and never a fitment claim.

Goal: generate publication images

Call POST /vision/part/generate, then poll GET /vision/part/generation-jobs/{jobId} when accepted. This is image generation from an OE number, not evidence that a photographed stock item has the same appearance or condition. Preserve the documented synthetic/disclosure metadata.

Goal: check part recalls

Call POST /recalls/parts with the request positions defined by OpenAPI. Preserve per-position output and register data versions. Do not substitute this for an OE base lookup or vehicle compatibility check.

Goal: retrieve documented vehicle-type assignments

Call GET /parts/oe/{oeNumber} and read fitment[] for the documented reverse OE-to-vehicle-type assignments. The list contains the available assignments and can be empty.

Each result carries an opaque vehicleTypeKey plus its recorded criteria[]; it does not include make/model data and is not a VIN-specific installation guarantee. Criteria are unstructured display text without a documented AND/OR relationship, polarity or executable vocabulary. Preserve them with their key and do not turn them into local compatibility rules. An empty list means no assignment evidence could be returned under the rules above, not that the part fits no vehicle.

API 1.71.0 has no public operation that resolves vehicleTypeKey to make, model or tapiId, and the contract makes no worldwide completeness promise. If the question concerns one known vehicle, call POST /vin/cart-check with the VIN and OE-number position instead. Never substitute aftermarket references, VDI codes, references, referenceNumbers or replacement-chain edges for either evidence scope.

I have a clusterId

Goal: read the current scoped snapshot

Call GET /parts/clusters/{clusterId}/intelligence (getPartClusterIntelligence) with a required Idempotency-Key and explicit market dimensions. Supply clusterVersion when the workflow must pin the cluster composition. On 202, poll GET /parts/intelligence/jobs/{jobId} (getPartIntelligenceJob); keep the returned scope and cluster version attached to the final result.

Goal: compare historical snapshots

Call GET /parts/clusters/{clusterId}/history (getPartClusterIntelligenceHistory) with required from, to, market dimensions and Idempotency-Key. Preserve each point's asOf, clusterVersion, evidence, scores, confidence and provenance.snapshotId. This operation reads materialized history and has no 202 branch: it does not create missing snapshots or start a backfill job.

I have a vehicle registration document

Goal: extract normalized international document fields

For new integrations, call POST /scanner/document/registration/international with the exact fileUrl request property and omit quality or set it to standard. Personal-document extraction offers no other processing level. The response uses the normalized, country-aware field model. Use the vehicle-registration field mapping when mapping printed country codes to canonical response fields.

Use POST /scanner/document/registration when an integration deliberately needs the national response envelope. The deprecated /scanner/registration-document/v2 and /scanner/registration-document paths remain compatibility aliases for existing callers: they do not emit an HTTP redirect and each returns the documented response of its canonical counterpart.

Goal: create a vehicle file in one workflow

Call POST /vehicles/intake. This operation combines registration-document analysis and vehicle matching and may return tapiId for later calls. Use it when the target workflow is vehicle intake, not when the caller only needs OCR fields.

Goal: extract a calculation with its documented equipment

Use POST /scanner/document/calculation with the documented fileUrl and optional quality=standard; no enhanced or maximum level is offered for this personal-document operation. It returns the fixed DocumentCalculationResponse: the previous 11 calculation fields plus required equipment[]. The caller cannot submit an output schema or arbitrary field definition. Preserve equipment[].codes[].value as source strings, including leading zeroes, and keep equipmentKind, sourceSection and sourcePage with every row.

The deprecated POST /scanner/document/extract path is a compatibility path for strict clients of the previous contract. It returns the documented 11 top-level fields and omits equipment; it is not an HTTP redirect. Do not reuse one Idempotency-Key across the canonical and compatibility paths: their response projections differ and the API returns HTTP 409 instead of replaying a differently shaped result.

Goal: extract rich vehicle and equipment data from a vehicle document

Use POST /scanner/document/vehicle with fileUrl, optional quality=standard and includeSensitiveData=false unless there is an authorised, purpose-bound need for named parties, contact, bank, payment or contract details. No enhanced or maximum level is offered for this personal-document operation. Choose this operation instead of calculation extraction when the goal is the rich schemaVersion=1.0 vehicle contract: detailed identifiers, powertrain, transmission, energy, colours, equipment[], warnings and the explicit sensitive-data boundary. Preserve equipment codes as strings exactly as returned, including leading zeroes. Keep equipmentKind (standard, variant, special or null) independent from availability; neither field may be derived from the other. The deprecated /scanner/vehicle-document/extract path is a compatibility alias with the same response contract, not a redirect.

Every response is marked Cache-Control: no-store. With sensitive output disabled, an Idempotency-Key may be used for identical retries. With includeSensitiveData=true, do not send that header: the API rejects it and never stores the sensitive response for replay.

Next step after a detected VIN

Validate the response according to its schema, keep the document extraction record separate from the vehicle lookup result, then follow I have a VIN. A detected string is input to a vehicle lookup, not proof that all document fields describe the resulting technical vehicle type.

I have a parts label image

Choose the smallest operation that meets the goal:

Never persist an OCR candidate directly as a confirmed OE number. Keep the source image reference, candidate, confirmation result and operator decision distinct in the customer system.

I have one or more images

Select by outcome, not by a generic “AI image” category.

All scanner and Vision calls require a documented legal basis and rights for every submitted file and URL. Use only an explicitly approved storage and retention policy.

I have a tapiId

• Use GET /vehicles/{tapiId} to retrieve documented technical vehicle data.
• Use POST /vehicles/{tapiId}/listing to compose marketplace-ready listing text from the documented vehicle data and request inputs.
• Do not send tapiId where an operation requires a VIN.
• Do not treat tapiId as the identifier of a physical stock vehicle; keep the integrating system's own vehicle-record ID.

I need to check an OE cart against a VIN

Use this sequence:

VIN selected for the Client
  -> POST /vin/cart-check with OE-number positions
  -> 200: map final response
  -> 202: store jobId + validated statusUrl + nextPollAt
           -> GET /vin/cart-check/jobs/{jobId}
           -> queued/running: wait according to Retry-After
           -> succeeded: map result
           -> failed: map embedded job error; do not treat HTTP 200 as success

Store input position IDs so results can be reconciled without relying on array order unless the schema explicitly guarantees order.

I need to separate customers or applications

1. Keep the Master client API key in the partner backend.
2. For a complete partner onboarding action, use POST /client/partner-workspaces only when its combined allowlist/key/sponsorship contract matches the workflow.
3. Otherwise create a Sub-user with POST /client/users, then configure its rate limits with PUT /client/users/{clientId}/rate-limits and add keys with POST /client/users/{clientId}/keys as required.
4. Store each plaintext API key exactly once when issued; it cannot be retrieved later.
5. After an ambiguous network failure, enter operation-specific reconciliation_required state and never retry a key-issuing operation blindly. POST /client/users permits partial reconciliation through GET /client/users, but the lost raw key still cannot be recovered. The public contract provides neither raw-key recovery for POST /client/users/{clientId}/keys nor lookup by externalReference for POST /client/partner-workspaces.
6. Read usage through GET /client/usage or, as a Master client, GET /client/users/{clientId}/usage.

The integrating system's Tenant remains its own domain object. Map it to a Client; do not add an undocumented tenant field to API calls.

I need a function that is not listed

Search the published OpenAPI contract by goal, tag, operation ID and path. If no matching operation exists under OpenAPI paths, the capability is not part of API 1.71.0. Do not fabricate a call.