Car images for insurance claims and quotes

A quote form, a policy record and a first notice of loss all name the vehicle the same way: by its VIN, typed by a customer or read off a registration document. Everything a person then sees about the car is text, a year, a make, a model and perhaps a trim. Asking "is this your vehicle?" next to a line of text invites a yes to anything.

A picture of the model the VIN decodes to lets the customer and the adjuster check at a glance that the record names the right kind of car. It cannot show which car: a render is a studio illustration of a catalog make, model and year, and it does not depict any specific physical vehicle. That one fact shapes the whole integration below.

• Decode on intake. The quote flow or the policy system decodes the VIN once, for free, and stores the catalog's vehicle id with the policy. Claims opened against the policy inherit it.
• One view everywhere. front-3-4, the hero angle, in one box on the quote screen, the claims workbench, the quote PDF and the policy portal, so every screen shows the model the same way.
• Signed URLs, never the key. Browsers and PDF renderers load key-free URLs that your server mints.
• Words for what a picture cannot say. Trim, options, the color on record, damage and mileage stay text and photos, and the picture says it is representative.

GET /api/v1/vin/{vin} costs nothing and needs a key with images:read. It answers with the decoded fields from NHTSA's vPIC data (year, make, model, trim, series, body class, engine and every other attribute vPIC knows) and, when the catalog has the vehicle, a vehicle object with its stable id and a ready image_path.

Read the trim: "Carrera, Carrera T, Carrera 4". This VIN's pattern covers three trims, so even the decode cannot say which one the policy insures, and a render of the 2024 911 certainly cannot. Ask the customer to confirm the trim, keep it with series and body_class as text, and let the picture show the model.

• A VIN with a bad check digit still decodes, with valid: false and the problem in errors; suggested_vin marks the character vPIC thinks is wrong with !, which is what to show the person typing.
• A form that has only the first characters can send a partial VIN: at least five characters, with * for each unknown position and an optional year.
• A 404 means vPIC has no record of the pattern. vPIC covers vehicles made for the US market, so for other markets start from the make and model with POST /api/v1/images/resolve, which is free too.

Store data.vehicle.id on the policy as a plain string and copy it to every claim opened against it. The id is deterministic and permanent: the same vehicle has the same id on every deploy and after every catalog release, so it is safe as a foreign key, and every later request says vehicle=veh_78qtwrgh37bkr instead of spelling a make and a model.

When data.vehicle is null the decoded make and model are not in the catalog, as with trailers and some commercial chassis. The decoded fields are still yours to show. Show them without a picture, and never put a similar car in its place.

The quote screen, the claims workbench and the policy portal are browser apps, so your server mints signed URLs with POST /api/v1/image-urls: 1 credit per URL when it is minted, up to 50 per call, and free to load until it expires. Frame the picture once and reuse the shape: front-3-4 in a 640×400 box with fit: "contain", and trim with a little padding so a coupe and a pickup fill the box the same way. How long each URL should live depends on where it is shown:

• The claims workbench. Mint when the screen draws. The default lifetime of 1 hour covers a working session, and a claim reopened tomorrow gets a fresh URL.
• The quote PDF. When the PDF is rendered from HTML, the renderer loads the picture once and embeds it, so the default lifetime is plenty, and the PDF service never holds your key. format: "jpg" flattens the picture onto white, which is what a document wants.
• The policy portal and the renewal email. These outlive any lifetime, so mint with renew: true and ttl_seconds: 604800 (7 days). The URL keeps working, each further week in which it is opened costs 1 credit, and renew_days: 365, the longest allowed, covers a year-long policy term.

Give the key that mints the URLs a list of allowed origins on the dashboard: a URL loaded from another site answers 403 with origin_not_allowed, while email clients and PDF viewers, which send no Referer, still load it. Revoking the key ends every URL it minted.

Put the label where the picture is, not only in a footnote: in the alt text and in a caption under the image. The render shows the make, model and year in a paint you choose, and color can follow the color on the policy (a preset name or any hex). It is still the model in that paint, not the customer's car.

• Free: the VIN decode, resolve, catalog lookups, and every load of a signed URL within its lifetime.
• 1 credit: each picture delivered to your server or each URL minted, and each further week in which a renewing URL is opened.
• Distinct vehicles: a quote funnel sees many different vehicles, and each plan caps the distinct vehicles a month: Free 100, Pro 2,500 and Business 15,000; Enterprise has no cap. A vehicle already served this month is always allowed, and a request past the cap is refused before anything is charged, so size the plan to the vehicles you quote, not to the credits.

On a paid plan the license covers a render inside what your product produces for its users, a quote or a report included, for as long as the plan is active; the details are in the license.

• SDK: client.decodeVin(vin, { year? }) and client.createImageUrls(…), as above; client.resolve(query) for a vehicle without a VIN.
• MCP: decode_vin and create_car_image_urls are in the core toolset, so an assistant with the claim in context can answer "show me the insured model" from the VIN on file. Setup is on the MCP page.