API DOCS

Identifiers and data flow

This guide answers “where do I get this value?” and “where may I send it next?” for the identifiers exposed by the public OpenAPI 3.1 contract (version 1.71.0). Field paths below start at a successful JSON response body unless a callback or request location is stated explicitly.

Treat every identifier as opaque unless its schema gives a format or pattern. Preserve the original string, case and separators when the contract does not promise normalization. Never derive one identifier type from another.

VIN

Question Contract answer
Meaning vin is the vehicle identification number used by the VIN and vehicle-recall operations. extractVinFromImage returns only a visibly photographed, complete and unambiguous 17-character VIN; the browser-session request separately permits a partial 3–17-character input so that a user can complete it in the interface. A VIN identifies the vehicle input; it is not a compatibility result and is not interchangeable with tapiId.
Producers and exact response fields Extraction: extractRegistrationDocument — production data.vehicle.vin, sandbox vehicle.vin; its deprecated extractRegistrationDocumentLegacyPath alias returns the same field. extractInternationalRegistrationDocument and deprecated extractInternationalRegistrationDocumentLegacyPath — vehicle.vin; extractCalculationDocument and deprecated 11-field extractDocument — vehicle.vin; extractVehicleDocument and deprecated extractVehicleDocumentLegacyPath — vehicle.vin; extractVinFromImage — vin; intakeVehicle — registrationDocument.vehicle.vin and top-level vin. These fields may be null where their schemas permit it. VIN-operation echoes/results: getVehicleByVin — vin; getPartsByVin — immediate vin, accepted-job vin, successful async result.vin; getVinPartsJob — job vin and successful result.vin; checkVinCart — immediate vin, accepted-job vin, successful async result.vin; getVinCartCheckJob — job vin and successful result.vin; getVinEconomicEvaluation — immediate vin, accepted-job vin, successful async result.vin; getVinEconomicEvaluationJob — job vin and successful result.vin; matchVehicleRecalls — vin.
Consumers Request body vin in createVinRedirectSession — POST /vin/redirect-sessions; path vin in getVehicleByVin — GET /vin/{vin}/vehicle; path vin in getPartsByVin — GET /vin/{vin}/parts; request body vin in checkVinCart — POST /vin/cart-check; path vin in getVinEconomicEvaluation — GET /vin/{vin}/economic-evaluation; request body vin in createVinEconomicIntelligence — POST /vin/economic-intelligence; path vin in matchVehicleRecalls — GET /recalls/vehicles/{vin}; optional request field vehicle.vin in classifyEndOfLifeVehicle — POST /vision/vehicle/elv-classification.
Prerequisites The caller must be authorised to transmit and process the VIN. For getPartsByVin, use any optional numeric selection consistently; a conflicting value returns 409 vin_provider_mismatch. getVinEconomicEvaluation accepts only the numeric selection enumerated in its schema. createVinEconomicIntelligence additionally requires market country, currency and condition and returns evaluationId, not a VIN echo, in its final response. Follow every operation's documented prerequisites.
Alternatives Obtain a VIN from a registration document with extractInternationalRegistrationDocument or extractRegistrationDocument, from a calculation with extractCalculationDocument, from a rich vehicle document with extractVehicleDocument, or through the combined intakeVehicle; obtain it from a photograph with extractVinFromImage. The four *LegacyPath/extractDocument paths are compatibility aliases, not alternatives for new integrations. If only tapiId is available, the public API can return Client-scoped technical vehicle data or compose listing text, but it has no operation that converts tapiId back to VIN.
Terminal/dead-end warnings A null scanner/intake VIN is not an identifier and must not be padded or guessed. The redirect callback returns no completed or normalized VIN; a 3–16-character session input therefore cannot feed parts, cart, economic or recall operations unless a full VIN is obtained independently. A cancelled callback has no tapiId. incomplete=true from getVehicleByVin means the VIN was not resolved to exactly one vehicle; remaining fields describe only the first candidate. If recall information cannot be resolved for a VIN, that operation returns 404.

tapiId

Question Contract answer
Meaning tapiId is the stable public vehicle reference returned after a successful VIN flow or a successful vehicle-intake match. It refers to the matched technical vehicle type, not the individual physical vehicle; several VINs may share it. Access is Client-scoped. Store it separately from VIN.
Producers and exact response fields getVehicleByVin — tapiId; completed createVinRedirectSession flow — callback query parameter tapiId (not a session-creation JSON field); getPartsByVin — immediate tapiId or successful async result.tapiId; getVinPartsJob — successful result.tapiId; getVinEconomicEvaluation — immediate tapiId or successful async result.tapiId; getVinEconomicEvaluationJob — successful result.tapiId; intakeVehicle — nullable top-level tapiId. getVehicleByTapiId and composeVehicleListing echo the consumed value as top-level tapiId.
Consumers Path tapiId in getVehicleByTapiId — GET /vehicles/{tapiId}; path tapiId in composeVehicleListing — POST /vehicles/{tapiId}/listing. No other public request field consumes it.
Prerequisites The reference must previously have been returned through a successful VIN flow or as a non-null intakeVehicle.tapiId for the same authenticated Client. A browser callback produces it only with status=completed; an async VIN job produces it only inside a successful result. For vehicle intake, use the returned tapiId only when it is non-null; do not infer one from other response fields.
Alternatives If tapiId is unavailable but VIN is available, run the applicable VIN vehicle flow. intakeVehicle can combine document extraction and VIN matching, but its tapiId remains nullable.
Terminal/dead-end warnings tapiId=null, a cancelled callback, or a failed job cannot feed a {tapiId} path. An unknown, foreign or unavailable value returns 404. GET /vehicles/{tapiId} returns no VIN or equipment, and there is no reverse-lookup endpoint. Do not treat shared tapiId equality as proof that two records are the same physical vehicle.

OE number

Question Contract answer
Meaning An OE number is the part-number string submitted through fields named oeNumber or oeNumbers. A scanner reading is only a candidate until an OE operation confirms it. Preserve the business input separately from any normalized result.
Producers and exact response fields Vehicle-derived: getPartsByVin and getVinPartsJob — immediate or successful async parts[].number / result.parts[].number (nullable); getVinEconomicEvaluation and its job status — immediate or successful async parts[].number / result.parts[].number. Confirmed OE base: getOePart — oeNumber, part.number, grouped references[].numbers[], consolidated referenceNumbers.oe_oem_reference_numbers[], and directed replacementChain[].from / replacementChain[].to. Normalization candidates: normalizeOeNumber — original input, normalizedOeNumber, equivalentOeNumbers[], and knownCandidates[].value. Image readings: extractLabelPartNumbers — partNumbers[]; extractLabelDetails — data.primaryPartNumber and data.otherPartNumbers[]. Production and sandbox use these same shapes. Operation echoes: getOeAftermarketReferences, getOePrice and getPartSeo — oeNumber; checkVinCart and its job status — successful results[].oe / result.results[].oe; matchPartRecalls — positions[].oeNumber; generatePartImagesFromOeNumber and its status — oeNumber and successful result.oeNumber.
Consumers Path oeNumber in getOePart — GET /parts/oe/{oeNumber}; getOeAftermarketReferences — GET /parts/oe/{oeNumber}/aftermarket-references; getOePrice — GET /parts/oe/{oeNumber}/price; getPartSeo — GET /parts/oe/{oeNumber}/seo. Query oeNumber in normalizeOeNumber — GET /parts/oe/normalize; query oeNumber in resolvePartIntelligence — GET /parts/intelligence. Body oeNumbers[] in checkVinCart — POST /vin/cart-check; body positions[].oeNumber in matchPartRecalls — POST /recalls/parts; body oeNumber in generatePartImagesFromOeNumber — POST /vision/part/generate.
Prerequisites Validate a scanner reading with normalizeOeNumber or getOePart before treating it as a catalogue fact. Send the optional manufacturer only when it is known. Cart checking additionally requires a VIN and mode; recall matching accepts optional vehicle context; image generation applies its own documented reference-evidence mode.
Alternatives If the number is only visible on a label, use a label extraction operation first. If the business goal is parts for a vehicle and only VIN is known, use getPartsByVin. tapiGenArt and VDI codes are separate output classifications and cannot replace an OE-number request input.
Terminal/dead-end warnings OCR strings, reference or comparison numbers, aftermarket references and SEO reference matches do not prove technical interchangeability or installation. getOePart returns 404 without a confirmed complete base match. A replacement edge is directed from from to to; do not invent the inverse or derive direction from references or referenceNumbers. In a cart response, fits=false is a reliable exclusion only when complete=true.

normalizedOeNumber

Question Contract answer
Meaning normalizedOeNumber is the confirmed normalized OE number returned by the API, not a local formatting transform. In normalization it is non-null only for status=matched; in the base OE response it is the confirmed normalized number to which the response applies.
Producers and exact response fields normalizeOeNumber — normalizedOeNumber; getOePart — normalizedOeNumber; matchPartRecalls — positions[].normalizedOeNumber.
Consumers No public request schema has a field named normalizedOeNumber. The normalization schema states that a matched value is used for further work; pass it through an operation's oeNumber input when that is the intended next step.
Prerequisites For normalizeOeNumber, require status=matched before consuming the field. For matchPartRecalls, require a non-null position value. A base OE 200 already represents a confirmed match.
Alternatives getOePart can return a confirmed normalized value together with the base part. When explicit status, reasons, equivalent numbers or candidates are required, use normalizeOeNumber instead.
Terminal/dead-end warnings The normalization response is null for unresolved, ambiguous and invalid. Do not implement uppercase/strip logic and label it normalizedOeNumber.

part.name

Question Contract answer
Meaning Nullable public part designation for the confirmed OE base response. The value is a string or null; the public contract makes no guarantee about its language or origin.
Producer and exact response field getOePart — part.name. When available, its value is a string or null.
Consumers Catalogue, ERP and display integrations may store or render the returned value. Translation can receive the non-null value through translatePartName when its separate single-designation input contract is satisfied.
Prerequisites Consume only after a successful getOePart base match and preserve the returned value exactly.
Alternatives When null, request human curation or leave the local label empty. Do not reconstruct it from another response field.
Terminal/dead-end warnings part.name describes a part but does not prove fitment, interchangeability or VIN-specific installation.

tapiGenArt

Question Contract answer
Meaning tapiGenArt is the stable public tapinomahub GenArt attached to a returned part, represented as a string matching ^TGA-[0-9]{6,}$. In getOePart the required field is null when no valid classification is available. It is opaque and distinct from OE numbers and VDI codes.
Producers and exact response fields getOePart — top-level required tapiGenArt containing a valid code or null; getPartsByVin — immediate parts[].tapiGenArt or accepted job's successful result.parts[].tapiGenArt; getVinPartsJob — successful result.parts[].tapiGenArt. Every successful VIN-parts position contains exactly one non-null value.
Consumers None. No public path, query parameter or request body field accepts tapiGenArt.
Prerequisites Obtain a non-null value from a successful confirmed OE base response or a returned VIN-parts position. Do not create it from a name, numeric suffix or another classification value, and do not treat null in a confirmed OE response as a failed base match.
Alternatives Use the OE number for OE operations and vdi[] for confirmed VDI mappings. These identifiers describe different contract concepts and are not substitutions for tapiGenArt.
Terminal/dead-end warnings It is output-only in the released API. There is no public “parts by tapiGenArt” or “vehicles by tapiGenArt” operation. Treat the entire string as opaque; do not convert its suffix to an integer. The independently returned vdi[] field is a separate classification and must not be derived from tapiGenArt.

VDI

Question Contract answer
Meaning A VDI 4081 code identifies a catalogue item. getVdiCatalog returns a base code matching ^VDI4081_[0-9]+$. A confirmed part mapping in getOePart.vdi[], getPartsByVin.parts[].vdi[] or getVinPartsJob.result.parts[].vdi[] may additionally have one numeric installation-location suffix and matches ^VDI4081_[0-9]+(?:_[0-9]+)?$.
Producers and exact response fields getVdiCatalog — entries[].code for base codes, plus stand, mainGroups[] and entry metadata; getOePart — required top-level vdi[] containing only valid confirmed full codes associated with the confirmed OE base record; getPartsByVin — required immediate parts[].vdi[] or a successful job's result.parts[].vdi[]; getVinPartsJob — required result.parts[].vdi[] on success.
Consumers None. No public path, query or body field accepts a VDI code.
Prerequisites Use getOePart after a confirmed OE base match when a mapping for one known OE number is required. Use the required vdi[] field of each returned VIN-parts position when the mapping belongs to that VIN result. Use getVdiCatalog with pagination when catalogue metadata is required.
Alternatives tapiGenArt is a separate tapinomahub part-category identity and OE number is a separate part identifier. Neither is a documented conversion of a VDI code.
Terminal/dead-end warnings vdi=[] means no valid mapping was available; it does not invalidate the part and does not leave a VIN-parts job incomplete. getVdiCatalog explicitly returns no OE assignments. A catalogue base code omits any installation-location mask; do not invent, append or strip a suffix to create an undocumented mapping.

vehicleTypeKey

Question Contract answer
Meaning vehicleTypeKey is the opaque string key of one type-level assignment in PartOeResponse.fitment[]. It is neither a VIN nor a tapiId. Keep every criteria[] value attached to the key that carries it.
Producers and exact response fields getOePart — fitment[].vehicleTypeKey. The same entry's criteria[] contains its documented restrictions; an empty list means no restriction is recorded for that assignment.
Consumers None in API 1.71.0. No public path, query parameter or request body accepts vehicleTypeKey.
Prerequisites Consume it only from a successful base OE response. fitment=[] means that no assignments were returned.
Alternatives For one known vehicle, use VIN plus POST /vin/cart-check. For Client-scoped technical vehicle data, obtain a tapiId through a documented VIN flow and call GET /vehicles/{tapiId}. Neither operation converts vehicleTypeKey.
Terminal/dead-end warnings The API does not resolve the key to make, model, VIN or tapiId, and it does not promise worldwide assignment completeness. Do not parse the key, join it to an undocumented table or treat it as installation approval.

clusterId

Question Contract answer
Meaning clusterId is the UUID identity of one versioned part cluster. clusterVersion identifies the returned composition of that cluster. Neither value is an OE number, aftermarket number, fitment result, kType, NatCode or GenArt.
Producers and exact response fields resolvePartIntelligence, getPartClusterIntelligence and the final getPartIntelligenceJob response — cluster.clusterId and cluster.clusterVersion; getPartClusterIntelligenceHistory — top-level clusterId and each points[].clusterVersion; createVinEconomicIntelligence and the final getVinEconomicIntelligenceJob response — candidates[].clusterId and candidates[].clusterVersion.
Consumers Path clusterId in getPartClusterIntelligence — GET /parts/clusters/{clusterId}/intelligence; path clusterId in getPartClusterIntelligenceHistory — GET /parts/clusters/{clusterId}/history. The current-snapshot operation can additionally consume the exact returned clusterVersion as a query parameter.
Prerequisites Obtain the UUID from an Intelligence result and keep clusterVersion, market scope, asOf and provenance.snapshotId with the result that produced it. A resolver request needs an OE or aftermarket identity anchor; kType, NatCode and GenArt are only disambiguation context.
Alternatives With only an OE or aftermarket number, call resolvePartIntelligence. With only a VIN, call createVinEconomicIntelligence and use its returned candidate clusters.
Terminal/dead-end warnings A cluster UUID does not prove technical interchangeability or VIN fitment. A newer cluster version must not silently rewrite a stored snapshot. Evidence and results are scoped to the authenticated Client and returned market dimensions; matching UUID text does not make tenant-scoped evidence portable.

evaluationId

Question Contract answer
Meaning evaluationId is the UUID of one VIN Economic Intelligence evaluation. In the current pilot, the same UUID identifies the originating request and, during asynchronous processing, its job; the final response therefore has evaluationId === requestId === jobId for that workflow.
Producer and exact response field createVinEconomicIntelligence on immediate completion, or the final getVinEconomicIntelligenceJob response — top-level evaluationId. An accepted or still-running 202 exposes the same UUID as requestId and jobId, but does not yet contain an evaluationId field.
Consumers While the evaluation is pending, pass the same UUID under the jobId path parameter to getVinEconomicIntelligenceJob. No separate lookup path consumes an evaluationId field in API 1.71.0.
Prerequisites Retain it only from a schema-valid final response and keep it with asOf, scope, pipeline, candidate set, confidence, provenance and warnings.
Alternatives Use the returned statusUrl while work is pending and retain the field roles even though requestId, jobId and the later evaluationId intentionally contain the same UUID in this pilot.
Terminal/dead-end warnings The equality is specific to the VIN Intelligence pilot contract. Never move the UUID to another job family or substitute it for clusterId, VIN or a local vehicle ID.

jobId

Question Contract answer
Meaning jobId is a UUID identifying one asynchronous job family. It is not a general resource identifier and must be polled through the status operation paired with its producer.
Producers and exact response fields getPartsByVin 202 — jobId; checkVinCart 202 — jobId; getVinEconomicEvaluation 202 — jobId; generatePartImagesFromOeNumber 202 — jobId; resolvePartIntelligence or getPartClusterIntelligence 202 — jobId; createVinEconomicIntelligence 202 — jobId. For both Intelligence families, requestId and jobId are the same UUID. A pending Intelligence status response repeats that UUID; the final VIN result exposes it again as requestId and evaluationId.
Consumers getVinPartsJob — GET /vin/parts/jobs/{jobId}; getVinCartCheckJob — GET /vin/cart-check/jobs/{jobId}; getVinEconomicEvaluationJob — GET /vin/economic-evaluation/jobs/{jobId}; getPartImageGenerationJob — GET /vision/part/generation-jobs/{jobId}; getPartIntelligenceJob — GET /parts/intelligence/jobs/{jobId}; getVinEconomicIntelligenceJob — GET /vin/economic-intelligence/jobs/{jobId}.
Prerequisites Create the value only by receiving the corresponding 202. Store the required full statusUrl, job family and retry timing together; also capture Location for comparison, but do not construct or origin-resolve a URL from its current root-relative example. Poll queued or running jobs after the returned Retry-After/retryAfterSeconds.
Alternatives Follow statusUrl rather than constructing a path. For VIN parts, cart checks, economic evaluations and Intelligence requests, an immediate 200 contains the result and creates no job to poll. Part-image generation is documented as asynchronous and starts with 202.
Terminal/dead-end warnings Use every jobId only with its returned statusUrl and paired status operation. Older job resources can return HTTP 200 while their domain state is still non-terminal; Intelligence status operations return 202 while pending and 200 only with the final business result. Never send a job ID to another family's path.

clientId

Question Contract answer
Meaning clientId addresses a Client account. Every API key belongs to exactly one Client, and billing, credit, plans and rate limits attach to that Client. In ClientUser responses, the same Client identifier is spelled id, not clientId.
Producers and exact response fields listClientUsers — users[].id; createClientUser and updateClientUser — user.id; replaceClientUserRateLimits — rateLimits[].clientId; getClientUserUsage and getClientUsage — top-level clientId and balance.clientId; getClientCredits — clientId; listSponsorshipGrants and listReceivedSponsorshipGrants — sponsorshipGrants[].sponsor.clientId and .beneficiary.clientId; grant mutation/choice responses — sponsorshipGrant.sponsor.clientId and .beneficiary.clientId. createPartnerWorkspace separately returns workspace.id and optional sponsorshipGrant.beneficiaryClientId; the contract does not normatively declare the former to be a {clientId} alias.
Consumers Path clientId in updateClientUser — PATCH /client/users/{clientId}; createClientUserApiKey — POST /client/users/{clientId}/keys; replaceClientUserRateLimits — PUT /client/users/{clientId}/rate-limits; getClientUserUsage — GET /client/users/{clientId}/usage. The same identifier concept is consumed as body beneficiaryClientId by upsertSponsorshipGrant and optional body sponsorClientId by chooseSponsorshipBillingMode.
Prerequisites Managed Sub-user operations require the authenticated Master client and a managed Sub-user. Sponsorship operations apply sponsor/beneficiary roles as documented by the selected operation.
Alternatives externalReference is the integrator's stable key for createPartnerWorkspace; it prevents duplicate provisioning in that workflow but cannot replace a {clientId} path, and there is no public lookup by that value. Retrieve existing managed IDs with listClientUsers.
Terminal/dead-end warnings Do not confuse ClientUser.id, workspace.id, apiKey.id, plan IDs, rate-limit record IDs or sponsorship-grant IDs. Do not search only for a response field literally named clientId: Client creation returns user.id. Do not send workspace.id into a {clientId} path unless the public contract explicitly establishes that relationship. A Client ID does not authorise cross-Client access by itself.

grantReference

Question Contract answer
Meaning grantReference is the sponsor-selected external reference used to address and idempotently replace a sponsorship grant. It is 1–100 characters matching ^[A-Za-z0-9._:-]+$ and is unique per sponsor. The response spelling is reference, not grantReference.
Producers and exact response fields The sponsor is the original producer because it chooses the path value. listSponsorshipGrants and listReceivedSponsorshipGrants return it as sponsorshipGrants[].reference; upsertSponsorshipGrant, revokeSponsorshipGrant and chooseSponsorshipBillingMode return it as sponsorshipGrant.reference. createPartnerWorkspace may also return sponsorshipGrant.reference. There is no JSON response field named grantReference.
Consumers Path grantReference in upsertSponsorshipGrant — PUT /client/sponsorship-grants/{grantReference}; revokeSponsorshipGrant — DELETE /client/sponsorship-grants/{grantReference}; chooseSponsorshipBillingMode — PUT /client/sponsorship-grants/received/{grantReference}/billing-mode.
Prerequisites Grant issue/replacement and revocation are sponsor operations. Billing-mode choice is a beneficiary operation. When several sponsors use the same text reference for one beneficiary, chooseSponsorshipBillingMode additionally requires body sponsorClientId.
Alternatives List issued or received grants to recover the response reference. The returned grant id is informational; public mutation paths do not address a grant by that ID. externalReference identifies partner provisioning and is not a general substitute.
Terminal/dead-end warnings Reusing a reference under the same sponsor replaces the grant; it does not create a second grant. The same text can be ambiguous from a beneficiary's perspective when used by several sponsors. Revocation stops new covered requests but does not delete existing results or entitlements. Active and historical grants remain listable; inspect active, dates and revocation state rather than treating presence as active coverage.

state

Question Contract answer
Meaning state is optional caller-owned context for the browser-guided VIN flow, for example a cart identifier. It is a string or null with a maximum of 512 characters and is returned unchanged to the callback URL. An empty value counts as unset.
Producers and exact response fields The caller is the only producer: send request body state to createVinRedirectSession. The session-creation JSON response has no state field. If set, the later browser redirect includes query parameter state on both completed and cancelled callbacks. This callback parameter is not a JSON response field.
Consumers Only the caller's returnUrl handler consumes it to recover its own context. No public tapinomahub operation accepts a path, query or body field named state after session creation.
Prerequisites Create the session server-side with body vin, an absolute HTTPS returnUrl without credentials or fragment, and optional state. Redirect the user's browser to the returned single-use redirectUrl; do not send the API key to the browser.
Alternatives Omit state and correlate the callback entirely in the caller's own application state. The public API defines no separate session identifier field in VinRedirectSessionResponse; it returns redirectUrl and expiresAt.
Terminal/dead-end warnings Empty or null state is omitted from the callback. state does not indicate completion: branch separately on callback status. A cancelled callback contains no tapiId; a completed callback contains no vehicle, equipment or access data beyond the documented query values. Do not expect state in the creation response or send it to another API endpoint.

Minimal hand-off rules

  1. Record the operation that produced each value and its exact response path.
  2. Record nullability and state gates such as status=matched, status=succeeded and status=completed with the value.
  3. Pass a value only to a consumer listed in its section; otherwise stop because the public contract does not define that use.
  4. Keep VIN, tapiId, vehicleTypeKey, OE number, normalizedOeNumber, tapiGenArt, VDI code, clusterId, clusterVersion, evaluationId, jobId, clientId, grantReference and state as distinct semantic fields in the integrating system. The current VIN Intelligence pilot intentionally places the same UUID in requestId, jobId and the later evaluationId; do not generalise that alias to another workflow.