Assets / API reference

Vehicle profile

Read an independently authorized stored vehicle by normalized vcl ID with scope=directory.

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

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

Shares stable identity with trip vehicle references. Separate current profile-purpose consent/read access is required; core asset permission is insufficient.
Optional unavailable attributes are omitted; unknown required status returns 503. No upstream call is made. Membership refreshes use an independently approved collection plan; inspect capture/fetch timestamps and health rather than assuming exact refresh timing.
Current visibility applies. hidden=true reveals only authorized cached filtered profiles; it cannot grant new vehicles.
groups contains shared directory IDs when current profile, membership and group-directory read permissions/account proof match. expand=groups returns those stored group objects; unavailable access returns409. groupMembership reports pending, missing, invalid, partial, stale or degraded source/directory evidence. Devices/raw/deletion remain unavailable409; current metadata is not a historical vehicle snapshot.

Parameters

Name	Where	Required	Type and behavior
`id`	path	Yes	`string`
`vehicleId`	path	Yes	`TripVehicleId`
`scope`	query	Yes	`directory` directory selects independently authorized account-bound normalized profiles; omitted on lists retains core assets
`hidden`	query	No	`boolean` Include authorized profiles hidden by current configured include/exclude/status filters; does not grant new access Default: `false`
`raw`	query	No	`boolean` Requested true raw/deleted returns409 until independently implemented and authorized Default: `false`
`deleted`	query	No	`boolean` Requested true raw/deleted returns409 until independently implemented and authorized Default: `false`
`expand`	query	No	`groups \| devices \| groups,devices \| devices,groups` groups resolves stored normalized group objects under current profile/membership/directory grants; unavailable relationship access or device expansion returns409

Request example

bash

curl "$TELEMATICS_ORIGIN/v1/connections/$CONNECTION_ID/vehicles/$VEHICLE_ID?scope=directory" \
  --header "Authorization: Bearer $TELEMATICS_CONSUMER_KEY"

Response fields

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

Field	Type	Required
`id`	`TripVehicleId`	Yes
`sourceId`	`string`	Yes
`provider`	`samsara \| motive \| geotab`	Yes
`status`	`active \| inactive`	Yes
`name`	`string`	No
`vin`	`string`	No
`make`	`string`	No
`model`	`string`	No
`year`	`integer`	No
`fuelType`	`gasoline \| diesel \| propane \| electric \| hybrid_gasoline \| hybrid_diesel \| biodiesel \| compressed_natural_gas \| liquefied_natural_gas \| ethanol \| hydrogen \| plug_in_hybrid`	No
`licensePlate`	`object`	No
`createdAt`	`string`	No
`updatedAt`	`string`	No
`groups`	`string \| GroupEntity[]`	No
`groupMembership`	`object`	No
`metadata`	`object`	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

{
  "id": "vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC",
  "sourceId": "example-source",
  "provider": "samsara",
  "status": "active",
  "name": "Example vehicle",
  "vin": "SYNTHETIC",
  "metadata": {
    "addedAt": "2026-10-01T00:00:00Z",
    "modifiedAt": "2026-10-01T00:00:00Z",
    "visibility": "visible"
  }
}

Errors and retries

HTTP status	Meaning
`400`	Invalid directory query or cursor
`401`	Consumer authentication denied
`404`	Resource missing or connection access denied
`409`	Profile detail pending, raw/deletion/group/device expansion unavailable
`413`	Profile response exceeds4MiB; lower list limit
`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",
  "additionalProperties": false,
  "properties": {
    "id": {
      "$ref": "#/components/schemas/TripVehicleId"
    },
    "sourceId": {
      "type": "string"
    },
    "provider": {
      "type": "string",
      "enum": [
        "samsara",
        "motive",
        "geotab"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "inactive"
      ]
    },
    "name": {
      "type": "string",
      "maxLength": 1024
    },
    "vin": {
      "type": "string",
      "maxLength": 1024
    },
    "make": {
      "type": "string",
      "maxLength": 1024
    },
    "model": {
      "type": "string",
      "maxLength": 1024
    },
    "year": {
      "type": "integer",
      "minimum": 1886,
      "maximum": 2200
    },
    "fuelType": {
      "type": "string",
      "enum": [
        "gasoline",
        "diesel",
        "propane",
        "electric",
        "hybrid_gasoline",
        "hybrid_diesel",
        "biodiesel",
        "compressed_natural_gas",
        "liquefied_natural_gas",
        "ethanol",
        "hydrogen",
        "plug_in_hybrid"
      ]
    },
    "licensePlate": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "number": {
          "type": "string"
        },
        "state": {
          "type": "string"
        }
      },
      "required": []
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    },
    "groups": {
      "type": "array",
      "maxItems": 1000,
      "uniqueItems": true,
      "items": {
        "oneOf": [
          {
            "type": "string",
            "pattern": "^group_[0-7][0-9A-HJKMNP-TV-Z]{25}$"
          },
          {
            "$ref": "#/components/schemas/GroupEntity"
          }
        ]
      }
    },
    "groupMembership": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "available",
            "not_authorized",
            "pending",
            "missing",
            "invalid",
            "partial",
            "stale",
            "degraded"
          ]
        },
        "scope": {
          "type": "string",
          "const": "credential_visible_directory"
        },
        "sourceScope": {
          "type": "string",
          "const": "credential_visible_reported_memberships"
        },
        "capturedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "directoryFetchedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "status",
        "scope",
        "sourceScope",
        "capturedAt",
        "directoryFetchedAt"
      ]
    },
    "metadata": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "addedAt": {
          "type": "string",
          "format": "date-time"
        },
        "modifiedAt": {
          "type": "string",
          "format": "date-time"
        },
        "visibility": {
          "type": "string",
          "enum": [
            "visible",
            "hidden_by_include_list",
            "hidden_by_exclude_list",
            "hidden_by_status"
          ]
        }
      },
      "required": [
        "addedAt",
        "modifiedAt",
        "visibility"
      ]
    }
  },
  "required": [
    "id",
    "sourceId",
    "provider",
    "status",
    "metadata"
  ]
}

← API overview · Download OpenAPI