Enrichment / API reference

Vehicle profile

Read cached vehicle enrichment through the unified API, with independent availability for each product.

GET/v1/connections/{id}/vehicles/{vehicleId}/profile

Authentication: Bearer consumer API key with an explicit connection grant.

Preview contract. Availability depends on the deployed release, authorized connection and asset.

How to use this endpoint

Implementation pending rollout. These routes require migration 008 and reviewed API deployment; enrichment starts only after this connection is explicitly enabled. Public docs deployment alone does not enable an API route.
Uses the same connection-scoped consumer key as telemetry. A VIN is an identity attribute, never permission to access another fleet's data.
New VINs automatically enter a background queue. GET reads cached results without calling suppliers. pending means work remains; missing means a completed lookup found no data; failed and blocked include a safe error code.
identity: vin, year, make, model, manufacturer, trim, style, body, engine, drivetrain, transmission and VIN validity/ambiguity flags. Null means unknown; enrichment never overwrites the fleet roster.
images: data.images contains url, kind and source. vin_listing means dealer/auction photos associated with this VIN; it does not establish current condition. Generic stock-image support is not verified yet. No image is a normal missing result.
specifications: vin, name, seatingCapacity, measurementFormat:provider_text, and categories of engine/fuel/measurements/features. Unit-bearing strings retain the reported units (such as in., lbs., MPG); they are not normalized telemetry numbers. Available options are not proof of installed options.
build: VIN-specific factory year/make/model/manufacturer, trim, series, style, drivetrain, engine, transmission, confidence, interiorColor, exteriorColor, options, headUpDisplay and rainSensingWipers, when supplied. Factory data does not include later upfits; prices are omitted until currency semantics are established.
Specifications and factory build are independently enabled after account entitlement is confirmed. Missing or malformed VINs return missing_vin or invalid_vin without making a supplier call. Profiles are scoped to the asset's current VIN.
fetchedAt is enrichment retrieval time, not a live vehicle observation. No periodic paid refresh is enabled; supplier corrections or image changes require an operator-managed refresh until a refresh API is added.

Parameters

Name	Where	Required	Type and behavior
`id`	path	Yes	`string`
`vehicleId`	path	Yes	`string`

Request example

bash

curl "$TELEMATICS_ORIGIN/v1/connections/$CONNECTION_ID/vehicles/$VEHICLE_ID/profile" \
  --header "Authorization: Bearer $TELEMATICS_CONSUMER_KEY"

Response fields

HTTP 200 returns VehicleProfile. Fields listed as required are guaranteed by this contract; optional fields may be absent.

Field	Type	Required
`vehicleId`	`string`	Yes
`vin`	`string \| null`	Yes
`identity`	`IdentityValue`	Yes
`images`	`ImagesValue`	Yes
`specifications`	`SpecificationsValue`	Yes
`build`	`BuildValue`	Yes

Nested field shapes and constraints are defined in the OpenAPI contract. For latest telemetry values, see normalized units and availability.

Response example

Synthetic values; this is a shape example, not a live customer response.

json

{
  "vehicleId": "asset-001",
  "vin": "1TEST000000000001",
  "identity": {
    "status": "available",
    "data": {
      "vin": "1TEST000000000001",
      "year": 2024,
      "make": "Example",
      "model": "Truck",
      "manufacturer": null,
      "trim": null,
      "style": null,
      "body": "Truck",
      "engine": null,
      "drivetrain": null,
      "transmission": null,
      "vinValid": true,
      "checksum": null,
      "ambiguous": false,
      "yearAmbiguous": false
    },
    "source": "auto.dev",
    "adapterVersion": "1.0.0",
    "fetchedAt": "2026-10-01T00:00:00Z",
    "errorCode": null
  },
  "images": {
    "status": "missing",
    "data": null,
    "source": "auto.dev",
    "adapterVersion": "1.0.0",
    "fetchedAt": "2026-10-01T00:00:00Z",
    "errorCode": null
  },
  "specifications": {
    "status": "disabled",
    "data": null,
    "source": "auto.dev",
    "adapterVersion": null,
    "fetchedAt": null,
    "errorCode": null
  },
  "build": {
    "status": "disabled",
    "data": null,
    "source": "auto.dev",
    "adapterVersion": null,
    "fetchedAt": null,
    "errorCode": null
  }
}

Errors and retries

HTTP status	Meaning
`401`	Consumer authentication denied
`404`	Resource missing or connection access denied
`503`	Service or database unavailable

Errors return {"error":"reason_code"}. Honor Retry-After when a 429 includes it. Permission and provider failures never become zero-valued telemetry. Connection health and reading status provide separate signals.

Response schema

{
  "type": "object",
  "properties": {
    "vehicleId": {
      "type": "string"
    },
    "vin": {
      "type": [
        "string",
        "null"
      ]
    },
    "identity": {
      "$ref": "#/components/schemas/IdentityValue"
    },
    "images": {
      "$ref": "#/components/schemas/ImagesValue"
    },
    "specifications": {
      "$ref": "#/components/schemas/SpecificationsValue"
    },
    "build": {
      "$ref": "#/components/schemas/BuildValue"
    }
  },
  "required": [
    "vehicleId",
    "vin",
    "identity",
    "images",
    "specifications",
    "build"
  ]
}

← API overview · Download OpenAPI