drive-snowflake

VIN-based fallback (VIN lookup)

VIN lookup resolves a Redbook vehicle key from a dealer-supplied VIN when neither the dealer's feed nor an AGVI lookup already supplied one. It runs inside the same enrichData() hook described in Enrichment — but unlike the AGVI lookup, it applies to every provider's every file, not just Autograb's. It's the third and last resolution attempt before a record is given up on.

What it's for: a meaningful share of dealer feeds arrive with no usable Redbook key and no agvi value at all — only a VIN. Without this fallback those records have no redbook_vehicle_key, and get filtered out of stock_int entirely later on (see Redbook key resolution hierarchy). VIN lookup gives them a second chance by calling Autograb's VIN endpoint directly.

How it works: every record is classified into exactly one outcome, checked in this order:

When the VIN lookup is triggered

A record enters the VIN lookup path only when all three are true:

  1. It does not already have a usable Redbook key.
  2. It does not have an agvi value.
  3. It has a VIN that passes validation.

If any of the three fails, the record is resolved another way (STOCK_FEED or AGVI_MAPPING) or passed through unchanged — the VIN lookup is never reached.

Per-record classification

  1. Has a usable Redbook key already → tagged STOCK_FEED. No API call, VIN lookup not triggered.

    "Usable" means: a non-empty string after trimming whitespace and stripping leading (/[ and trailing )/] characters. "AUVTOYO2025AEAC" and "(ABC123)" both count; "", null, " ", "()" do not.

  2. Has an agvi value → goes to the AGVI branch above instead of VIN lookup. Tagged AGVI_MAPPING on success. VIN lookup not triggered.

  3. Has a VIN that passes validation → this is the condition that triggers the VIN lookup. A VIN must:

    • Be exactly 17 characters, from [A-HJ-NPR-Z0-9] (letters I, O, Q are invalid VIN characters and excluded).
    • Not be a known synthetic/placeholder WMI (e.g. prefix "6ZZ").
    • Have no run of 5 or more identical characters in a row.

  4. None of the above (no usable key, no agvi, no valid VIN) → passed through unchanged, no tag. VIN lookup not triggered.

Resolution outcome once triggered

Triggering the lookup does not guarantee a resolved key:

  • Stage 1 (resolveAgviFromVin) must return confidence: "standard" exactly. "reduced" or a missing confidence field → discarded, no Stage 2 call, record left unchanged, no error.
  • If Stage 1 returns an agvi but no inline key, Stage 2 (lookupVehicleKeyByAgvi, the same function the AGVI branch above uses) is called. If that also finds nothing, the record stays unresolved.
  • On success, tagged VIN_LOOKUP.

Scope and limits

Applies to every provider's every file, every dealer — no per-dealer allowlist, no per-file cap.

Structural limits (infrastructure, not business logic):

  • Lambda timeout: 900 seconds, hard cutoff (stockInboundProcess).
  • Up to 5 files processed concurrently (maximumConcurrency: 5).
  • The Autograb HTTP call has no per-request timeout — a stalled call can hold up to Node's default socket timeout, and every VIN candidate in a file is dispatched concurrently in one batch with no internal throttling. A known, accepted risk, not a bug still being worked on.

See also

Esc
Esc Close