docs.vin

vin

The vin noun — identity, lifecycle, events, and every capability as an anchored section: 10 capabilities, 4 live, 6 sandbox, 0 declared.

vin is one of the estate's 317 automotive nouns — a job a car needs done. It carries 10 capabilities: 4 live, 6 sandbox, 0 declared · doors aggregator.vin.

Identity

Nounvin
PillarData (facets: 5 data · 4 services · 1 commerce)
Capabilities10 — 4 live · 6 sandbox · 0 declared
EntitiesVehicle
Doorsaggregator.vin
SDKVin.vin.* from apis.vin
Address/catalog/vin#{action} — the anchor IS the wire name minus vin.

Events

The vocabulary this noun can append to the record — 5 past-tense, versioned event types, each linked to the capability that emits it:

Discover & read

decode

vin.decode · GET /vins/decode · gate none · live · answers VinDecode@1

The first call most integrations make: one VIN in, the decoded Vehicle entity shape out. The answer is a typed envelope, not a bare object — narrow on answer.type before touching the payload, and the compiler enforces the gate law for you.

FieldTypeRequiredNotes
vinstringno—

Door — aggregator.vin serves this noun on its two routes: / (the landing) · /1C6JJTBG8LL135248 (the VIN lens).

Try it — live: answers on the wire today. A sandbox key still selects the deterministic simulated mode — drive the full outcome range with the magic triggers.

the SDK — vin.decode
import { vin } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await vin.decode({"vin":"1C6JJTBG8LL135248"})
GET /vins/decode
curl 'https://apis.vin/vins/decode?vin=1C6JJTBG8LL135248'

Curated example — hand-written in overlays/vin.decode.mdx, typechecked against the SDK's answer types on every CI run; everything else in this section is generated.

import { vin } from 'apis.vin'
import type { VinDecode } from 'apis.vin'

const answer = await vin.decode({ vin: 'JM3KFBXY1S0597748' })

// Answer<VinDecode> = Ok | Empty | Blocked | Offer — only OK carries the value
if (answer.type === 'OK') {
  const vehicle: VinDecode = answer.value
  console.log(`${vehicle.year} ${vehicle.make} ${vehicle.model} ${vehicle.trim}`)
} else if (answer.type === 'EMPTY') {
  // truthful absence — a typed EMPTY, never a faked 200
  console.log(answer.reason ?? 'no record behind this VIN')
}

Gotchas — curated field notes; the reference above stays generated.

  • Only OK carries value. Reading answer.value without narrowing on answer.type is a compile error — that is the gate law expressed in the type system, not a runtime convention.
  • answer.$http (transport status, raw non-JSON body) is attached non-enumerably: readable in code, invisible to JSON.stringify and spread. Serializing an answer always restores pure wire data.
  • answer.provenance labels where the payload came from — { environment, simulated }. A sandbox payload says so; it never masquerades as production data.

validate

vin.validate · GET /vins/validate · gate none · live · answers VinValidate@1

FieldTypeRequiredNotes
vinstringno—

Door — aggregator.vin serves this noun on its two routes: / (the landing) · /1C6JJTBG8LL135248 (the VIN lens).

Try it — live: answers on the wire today. A sandbox key still selects the deterministic simulated mode — drive the full outcome range with the magic triggers.

the SDK — vin.validate
import { vin } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await vin.validate({"vin":"1C6JJTBG8LL135248"})
GET /vins/validate
curl 'https://apis.vin/vins/validate?vin=1C6JJTBG8LL135248'

batchDecode

vin.batchDecode · GET /vins/batch-decode · gate none · sandbox · answers VinBatchDecode@1

No input — this capability takes no request body.

Door — aggregator.vin serves this noun on its two routes: / (the landing) · /1C6JJTBG8LL135248 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

the SDK — vin.batchDecode
import { vin } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await vin.batchDecode()
GET /vins/batch-decode
curl 'https://apis.vin/vins/batch-decode'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-16T14:50:10.086Z · HTTP 200
{
  "type": "OK",
  "answers": "VinBatchDecode@1",
  "value": {
    "vin": "1HGCM82633A004352",
    "noun": "vin",
    "asOf": "2026-08-10",
    "vehicleId": "VEH-ff80c984",
    "year": 2025,
    "bodyStyle": "sedan",
    "drivetrain": "fwd",
    "odometer": 32490,
    "condition": "clean",
    "status": "Decoded",
    "currentOwnerId": "ID-11f17424",
    "batch": [
      {
        "vin": "1HGCM82633A004352",
        "file": {
          "vehicleId": "VEH-ff80c984",
          "vin": "1HGCM82633A004352",
          "year": 2025,
          "bodyStyle": "sedan",
          "drivetrain": "fwd",
          "odometer": 32490,
          "condition": "clean",
          "status": "Decoded",
          "currentOwnerId": "ID-11f17424"
        }
      }
    ],
    "count": 1
  },
  "evidence": {
    "vin": "1HGCM82633A004352",
    "noun": "vin",
    "asOf": "2026-08-10",
    "vehicleId": "VEH-ff80c984",
    "year": 2025,
    "bodyStyle": "sedan",
    "drivetrain": "fwd",
    "odometer": 32490,
    "condition": "clean",
    "status": "Decoded",
    "currentOwnerId": "ID-11f17424",
    "batch": [
      {
        "vin": "1HGCM82633A004352",
        "file": {
          "vehicleId": "VEH-ff80c984",
          "vin": "1HGCM82633A004352",
          "year": 2025,
          "bodyStyle": "sedan",
          "drivetrain": "fwd",
          "odometer": 32490,
          "condition": "clean",
          "status": "Decoded",
          "currentOwnerId": "ID-11f17424"
        }
      }
    ],
    "count": 1
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "spec-sheet-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

checkDigitVerify

vin.checkDigitVerify · GET /vins/check-digit-verify · gate none · live · answers VinCheckDigitVerify@1

FieldTypeRequiredNotes
vinstringno—

Door — aggregator.vin serves this noun on its two routes: / (the landing) · /1C6JJTBG8LL135248 (the VIN lens).

Try it — live: answers on the wire today. A sandbox key still selects the deterministic simulated mode — drive the full outcome range with the magic triggers.

the SDK — vin.checkDigitVerify
import { vin } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await vin.checkDigitVerify({"vin":"1C6JJTBG8LL135248"})
GET /vins/check-digit-verify
curl 'https://apis.vin/vins/check-digit-verify?vin=1C6JJTBG8LL135248'

Apply & book

register

vin.register · POST /vins/register · gate offer · sandbox · answers VinRegister@1

FieldTypeRequiredNotes
vinstringno—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — aggregator.vin serves this noun on its two routes: / (the landing) · /1C6JJTBG8LL135248 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

Emits — Vin.registered@1.

the SDK — vin.register
import { vin } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await vin.register({"vin":"1C6JJTBG8LL135248"})
POST /vins/register
curl -X POST https://apis.vin/vins/register \
  -H 'content-type: application/json' \
  -d '{"vin":"1C6JJTBG8LL135248"}'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-17T12:42:18.807Z · HTTP 200
{
  "type": "OK",
  "answers": "VinRegister@1",
  "value": {
    "vin": "1C6JJTBG8LL135248",
    "noun": "vin",
    "asOf": "2026-08-10",
    "vehicleId": "VEH-6ddbe9b7",
    "year": 2024,
    "bodyStyle": "coupe",
    "drivetrain": "fwd",
    "odometer": 47077,
    "condition": "poor",
    "currentOwnerId": "ID-11f17424",
    "registration": {
      "registrationId": "VRG-a9f56aeb",
      "vin": "1C6JJTBG8LL135248",
      "register": "estate-vin-register",
      "status": "registered"
    }
  },
  "evidence": {
    "vin": "1C6JJTBG8LL135248",
    "noun": "vin",
    "asOf": "2026-08-10",
    "vehicleId": "VEH-6ddbe9b7",
    "year": 2024,
    "bodyStyle": "coupe",
    "drivetrain": "fwd",
    "odometer": 47077,
    "condition": "poor",
    "currentOwnerId": "ID-11f17424",
    "registration": {
      "registrationId": "VRG-a9f56aeb",
      "vin": "1C6JJTBG8LL135248",
      "register": "estate-vin-register",
      "status": "registered"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "spec-sheet-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

subscribe

vin.subscribe · POST /vins/subscribe · gate offer · sandbox · answers VinSubscribe@1

FieldTypeRequiredNotes
vinstringno—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — aggregator.vin serves this noun on its two routes: / (the landing) · /1C6JJTBG8LL135248 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

Emits — Vin.subscribed@1.

the SDK — vin.subscribe
import { vin } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await vin.subscribe({"vin":"1C6JJTBG8LL135248"})
POST /vins/subscribe
curl -X POST https://apis.vin/vins/subscribe \
  -H 'content-type: application/json' \
  -d '{"vin":"1C6JJTBG8LL135248"}'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-17T12:42:18.827Z · HTTP 200
{
  "type": "OK",
  "answers": "VinSubscribe@1",
  "value": {
    "vin": "1C6JJTBG8LL135248",
    "noun": "vin",
    "asOf": "2026-08-10",
    "vehicleId": "VEH-6ddbe9b7",
    "year": 2024,
    "bodyStyle": "coupe",
    "drivetrain": "fwd",
    "odometer": 47077,
    "condition": "poor",
    "currentOwnerId": "ID-11f17424",
    "subscription": {
      "id": "SSB-fd991d8e",
      "topic": "vin-notices",
      "status": "active"
    }
  },
  "evidence": {
    "vin": "1C6JJTBG8LL135248",
    "noun": "vin",
    "asOf": "2026-08-10",
    "vehicleId": "VEH-6ddbe9b7",
    "year": 2024,
    "bodyStyle": "coupe",
    "drivetrain": "fwd",
    "odometer": 47077,
    "condition": "poor",
    "currentOwnerId": "ID-11f17424",
    "subscription": {
      "id": "SSB-fd991d8e",
      "topic": "vin-notices",
      "status": "active"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "spec-sheet-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

assign

vin.assign · POST /vins/assign · gate offer · sandbox · answers VinAssign@1

FieldTypeRequiredNotes
vinstringno—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — aggregator.vin serves this noun on its two routes: / (the landing) · /1C6JJTBG8LL135248 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

Emits — Vin.assigned@1.

the SDK — vin.assign
import { vin } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await vin.assign({"vin":"1C6JJTBG8LL135248"})
POST /vins/assign
curl -X POST https://apis.vin/vins/assign \
  -H 'content-type: application/json' \
  -d '{"vin":"1C6JJTBG8LL135248"}'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-17T12:42:18.807Z · HTTP 200
{
  "type": "OK",
  "answers": "VinAssign@1",
  "value": {
    "vin": "1C6JJTBG8LL135248",
    "noun": "vin",
    "asOf": "2026-08-10",
    "vehicleId": "VEH-6ddbe9b7",
    "year": 2024,
    "bodyStyle": "coupe",
    "drivetrain": "fwd",
    "odometer": 47077,
    "condition": "poor",
    "currentOwnerId": "ID-11f17424",
    "assignment": {
      "assignmentId": "VAS-7c474afb",
      "vin": "1C6JJTBG8LL135248",
      "status": "assigned",
      "basis": "the-vin-is-the-identity"
    }
  },
  "evidence": {
    "vin": "1C6JJTBG8LL135248",
    "noun": "vin",
    "asOf": "2026-08-10",
    "vehicleId": "VEH-6ddbe9b7",
    "year": 2024,
    "bodyStyle": "coupe",
    "drivetrain": "fwd",
    "odometer": 47077,
    "condition": "poor",
    "currentOwnerId": "ID-11f17424",
    "assignment": {
      "assignmentId": "VAS-7c474afb",
      "vin": "1C6JJTBG8LL135248",
      "status": "assigned",
      "basis": "the-vin-is-the-identity"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "spec-sheet-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

Pay & settle

scanCapture

vin.scanCapture · POST /vins/scan-capture · gate key · sandbox · answers VinScanCapture@1

No input — this capability takes no request body.

Door — aggregator.vin serves this noun on its two routes: / (the landing) · /1C6JJTBG8LL135248 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

Emits — Vin.scanCaptured@1.

the SDK — vin.scanCapture
import { vin } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await vin.scanCapture()
POST /vins/scan-capture
curl -X POST https://apis.vin/vins/scan-capture \
  -H 'content-type: application/json' \
  -d '{}'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-16T14:50:10.086Z · HTTP 200
{
  "type": "OK",
  "answers": "VinScanCapture@1",
  "value": {
    "vin": "1HGCM82633A004352",
    "noun": "vin",
    "asOf": "2026-08-10",
    "vehicleId": "VEH-ff80c984",
    "year": 2025,
    "bodyStyle": "sedan",
    "drivetrain": "fwd",
    "odometer": 32490,
    "condition": "clean",
    "status": "Decoded",
    "currentOwnerId": "ID-11f17424",
    "capture": {
      "captureId": "VSC-d7f4a3e2",
      "vin": "1HGCM82633A004352",
      "method": "scan",
      "status": "captured"
    }
  },
  "evidence": {
    "vin": "1HGCM82633A004352",
    "noun": "vin",
    "asOf": "2026-08-10",
    "vehicleId": "VEH-ff80c984",
    "year": 2025,
    "bodyStyle": "sedan",
    "drivetrain": "fwd",
    "odometer": 32490,
    "condition": "clean",
    "status": "Decoded",
    "currentOwnerId": "ID-11f17424",
    "capture": {
      "captureId": "VSC-d7f4a3e2",
      "vin": "1HGCM82633A004352",
      "method": "scan",
      "status": "captured"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "spec-sheet-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

More actions

enrich

vin.enrich · GET /vins/enrich · gate none · live · answers VinEnrich@1

FieldTypeRequiredNotes
vinstringno—

Door — aggregator.vin serves this noun on its two routes: / (the landing) · /1C6JJTBG8LL135248 (the VIN lens).

Try it — live: answers on the wire today. A sandbox key still selects the deterministic simulated mode — drive the full outcome range with the magic triggers.

the SDK — vin.enrich
import { vin } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await vin.enrich({"vin":"1C6JJTBG8LL135248"})
GET /vins/enrich
curl 'https://apis.vin/vins/enrich?vin=1C6JJTBG8LL135248'

stamp

vin.stamp · POST /vins/stamp · gate offer · sandbox · answers VinStamp@1

FieldTypeRequiredNotes
vinstringno—

The gate is a 402 OFFER — the price and a hard ceiling on the wire, with a durable intent that executes on settlement. Never a wall, never "contact sales". Price: not posted — see /pricing.

Door — aggregator.vin serves this noun on its two routes: / (the landing) · /1C6JJTBG8LL135248 (the VIN lens).

Try it — sandbox: every call answers a deterministic, provenance-labeled simulated payload ({ environment, simulated } in the body). Force any documented outcome with the magic triggers. Going live is a connect, never a ballot: submit the credential at integrates.vin (dealer systems) or connects.vin (consumer accounts) — submissions enter the activation queue and rank live rollout.

Emits — Vin.stamped@1.

the SDK — vin.stamp
import { vin } from 'apis.vin'

// the gate law is in the type system: Answer<T> = Ok | Empty | Blocked | Offer
const answer = await vin.stamp({"vin":"1C6JJTBG8LL135248"})
POST /vins/stamp
curl -X POST https://apis.vin/vins/stamp \
  -H 'content-type: application/json' \
  -d '{"vin":"1C6JJTBG8LL135248"}'

Receipt — the sandbox wire answered the request above with this exact body at build time. Captured by the receipts runner (timestamped, provenance in the payload), never authored; it re-executes only when this descriptor changes.

receipt · executed 2026-08-17T12:42:18.814Z · HTTP 200
{
  "type": "OK",
  "answers": "VinStamp@1",
  "value": {
    "vin": "1C6JJTBG8LL135248",
    "noun": "vin",
    "asOf": "2026-08-10",
    "vehicleId": "VEH-6ddbe9b7",
    "year": 2024,
    "bodyStyle": "coupe",
    "drivetrain": "fwd",
    "odometer": 47077,
    "condition": "poor",
    "currentOwnerId": "ID-11f17424",
    "stamp": {
      "stampId": "VST-5edef539",
      "vin": "1C6JJTBG8LL135248",
      "status": "stamped"
    }
  },
  "evidence": {
    "vin": "1C6JJTBG8LL135248",
    "noun": "vin",
    "asOf": "2026-08-10",
    "vehicleId": "VEH-6ddbe9b7",
    "year": 2024,
    "bodyStyle": "coupe",
    "drivetrain": "fwd",
    "odometer": 47077,
    "condition": "poor",
    "currentOwnerId": "ID-11f17424",
    "stamp": {
      "stampId": "VST-5edef539",
      "vin": "1C6JJTBG8LL135248",
      "status": "stamped"
    }
  },
  "provenance": {
    "simulated": true,
    "environment": "sandbox",
    "source": "spec-sheet-sandbox"
  },
  "events": [],
  "meter": {
    "charged": "0.00",
    "posted": false
  }
}

Data model

The record shape behind this noun — one entity, each property an evidence field. See the whole estate model on the data model page.

Vehicle

Modeled

The noun drawn out — its record shape, its lifecycle, and how it is exercised end to end. One diagram, rendered from the estate model.

Vin · Class model

Generated from the catalog. Every capability, answer, gate, and entity on this page is a rendered descriptor — it cannot drift from the wire.

vehicle

The vehicle noun — identity, lifecycle, events, and every capability as an anchored section: 20 capabilities, 8 live, 12 sandbox, 0 declared.

vinClone

The vinClone noun — identity, lifecycle, events, and every capability as an anchored section: 4 capabilities, 0 live, 4 sandbox, 0 declared.

On this page

Identity
Events
Discover & read
decode
validate
batchDecode
checkDigitVerify
Apply & book
register
subscribe
assign
Pay & settle
scanCapture
More actions
enrich
stamp
Data model
Vehicle
Modeled