Assets / API reference

Vehicle metadata

Read provider-supplied vehicle identity, status and group references through the unified API.

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

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

Stored read only: this endpoint never requests provider data or VIN enrichment. Collection requires a separately approved per-connection vehicleMetadata opt-in; the default is disabled.
Each field reports available, missing, unsupported or invalid. Missing values are unknown; malformed optional fields do not interrupt fault, odometer or location collection.
The snapshot is stale after 24 hours. fetchedAt is our roster persistence time, not a provider event time. Normalized active/inactive status reflects provider state at the last sync, separately from dispatch availability or deletion. createdAt/updatedAt are upstream vehicle-record timestamps, not telemetry freshness.
A record outside the latest completed roster or from an earlier connection generation returns not_in_current_roster with null data. This does not establish physical deletion. Legacy asset listing retains previously seen assets.
Group IDs and optional names are references on this vehicle, not complete group records or hierarchy. fuelType uses the common enum; an unmapped code has a null invalid value while sourceFuelType preserves the source code. Manufacturing information from VIN enrichment is available separately at the identity endpoint.

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/metadata" \
  --header "Authorization: Bearer $TELEMATICS_CONSUMER_KEY"

Response fields

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

Field	Type	Required
`vehicleId`	`string`	Yes
`status`	`disabled \| pending \| not_in_current_roster \| available \| stale`	Yes
`data`	`VehicleMetadata \| null`	Yes
`fetchedAt`	`string \| null`	Yes
`rosterSeenAt`	`string \| null`	Yes
`retrieval`	`"stored"`	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",
  "status": "available",
  "data": {
    "version": 1,
    "source": "samsara:vehicles",
    "fields": {
      "make": {
        "status": "available",
        "value": "Example",
        "source": "samsara:vehicles.make"
      },
      "model": {
        "status": "available",
        "value": "Truck",
        "source": "samsara:vehicles.model"
      },
      "year": {
        "status": "available",
        "value": 2024,
        "source": "samsara:vehicles.year"
      },
      "status": {
        "status": "available",
        "value": "active",
        "source": "samsara:vehicles.gateway"
      },
      "providerStatus": {
        "status": "unsupported",
        "value": null,
        "source": "samsara:vehicles.providerStatus"
      },
      "fuelType": {
        "status": "unsupported",
        "value": null,
        "source": "samsara:vehicles.fuelType"
      },
      "sourceFuelType": {
        "status": "unsupported",
        "value": null,
        "source": "samsara:vehicles.sourceFuelType"
      },
      "createdAt": {
        "status": "missing",
        "value": null,
        "source": "samsara:vehicles.createdAtTime"
      },
      "updatedAt": {
        "status": "missing",
        "value": null,
        "source": "samsara:vehicles.updatedAtTime"
      },
      "licensePlate": {
        "status": "available",
        "value": "EXAMPLE",
        "source": "samsara:vehicles.licensePlate"
      },
      "licensePlateRegion": {
        "status": "unsupported",
        "value": null,
        "source": "samsara:vehicles.licensePlateRegion"
      },
      "serialNumber": {
        "status": "available",
        "value": "synthetic-gateway",
        "source": "samsara:vehicles.serial"
      },
      "groups": {
        "status": "available",
        "value": [
          {
            "id": "group-001",
            "name": "Example group"
          }
        ],
        "source": "samsara:vehicles.tags"
      },
      "activeFrom": {
        "status": "unsupported",
        "value": null,
        "source": "samsara:vehicles.activeFrom"
      },
      "activeTo": {
        "status": "unsupported",
        "value": null,
        "source": "samsara:vehicles.activeTo"
      }
    }
  },
  "fetchedAt": "2026-10-01T00:00:00Z",
  "rosterSeenAt": "2026-10-01T00:00:00Z",
  "retrieval": "stored"
}

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"
    },
    "status": {
      "type": "string",
      "enum": [
        "disabled",
        "pending",
        "not_in_current_roster",
        "available",
        "stale"
      ]
    },
    "data": {
      "oneOf": [
        {
          "$ref": "#/components/schemas/VehicleMetadata"
        },
        {
          "type": "null"
        }
      ]
    },
    "fetchedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "rosterSeenAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "retrieval": {
      "type": "string",
      "const": "stored"
    }
  },
  "required": [
    "vehicleId",
    "status",
    "data",
    "fetchedAt",
    "rosterSeenAt",
    "retrieval"
  ]
}

← API overview · Download OpenAPI