Drivers / API reference

Get driver

Read one driver using its stable normalized driver ID.

GET/v1/connections/{id}/drivers/{driverId}

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

Use a drv_ ID from List drivers. The ID is scoped to the connection and bound source account.
Optional values appear only when valid and available. availability distinguishes missing, invalid and unsupported fields; no assumed names or phone country codes.
metadata.modifiedAt advances for driver changes, reappearance and conservative shared group/config/health or directory consent/publication changes; createdAt/updatedAt remain provider values.
A pending directory returns 409; a driver outside the current complete directory returns 404. Use groupScope=directory for the same group IDs as the directory endpoint, with both current grants and a matching verified account. Add expand=groups for stored objects; check groupMembership. Expanded list/detail responses above 4 MiB return 413; use IDs-only reads or lower the list limit. Raw supplier data and deletion evidence remain unavailable.

Parameters

Name	Where	Required	Type and behavior
`id`	path	Yes	`string`
`driverId`	path	Yes	`DriverId`
`raw`	query	No	`boolean` Raw supplier data is unavailable. raw=true returns 409. Default: `false`
`expand`	query	No	`groups` Expand stored driver groups in the requested groupScope. Directory expansion uses the same IDs/objects as groups?scope=directory and requires both read grants. No supplier calls; check coverage and freshness.
`groupScope`	query	No	`directory` On driver reads, resolve groups through the full stored directory. Requires both current driver and group-directory grants for matching verified accounts; otherwise 404. Omit for approved-ID relationships. Keep unchanged while paging.

Request example

bash

curl "$TELEMATICS_ORIGIN/v1/connections/$CONNECTION_ID/drivers/$DRIVER_ID" \
  --header "Authorization: Bearer $TELEMATICS_CONSUMER_KEY"

Response fields

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

Field	Type	Required
`status`	`available \| stale \| degraded`	Yes
`retrieval`	`"stored"`	Yes
`fetchedAt`	`string \| null`	Yes
`capturedAt`	`string \| null`	Yes
`errorCode`	`null \| provider_auth_required \| provider_config_invalid \| provider_throttled \| provider_unavailable \| provider_response_changed \| provider_scope_mismatch \| driver_persistence_unavailable`	Yes
`driver`	`Driver`	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

{
  "status": "available",
  "retrieval": "stored",
  "fetchedAt": "2026-10-01T00:00:00Z",
  "capturedAt": "2026-10-01T00:00:00Z",
  "errorCode": null,
  "driver": {
    "id": "drv_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "sourceId": "12345",
    "provider": "motive",
    "status": "active",
    "firstName": "Example",
    "metadata": {
      "addedAt": "2026-10-01T00:00:00Z",
      "modifiedAt": "2026-10-01T00:00:00Z",
      "visibility": "visible"
    },
    "groupMembership": {
      "status": "unsupported",
      "scope": "approved_groups_only",
      "sourceScope": "unknown",
      "fetchedAt": null,
      "membershipCapturedAt": "2026-10-01T00:00:00Z",
      "sourceAvailability": "unsupported",
      "inventoryStatus": "disabled"
    },
    "availability": {
      "firstName": "available",
      "middleName": "unsupported",
      "lastName": "missing",
      "displayName": "unsupported",
      "email": "missing",
      "phone": "missing",
      "username": "missing",
      "licenseNumber": "missing",
      "licenseState": "missing",
      "createdAt": "missing",
      "updatedAt": "missing"
    }
  }
}

Errors and retries

HTTP status	Meaning
`400`	Invalid time window, metric or cursor
`401`	Consumer authentication denied
`404`	Resource missing or connection access denied
`409`	Driver directory pending, or raw functionality unavailable
`413`	Expanded driver/group response exceeds 4 MiB; omit expand=groups to use group references
`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": {
    "status": {
      "type": "string",
      "enum": [
        "available",
        "stale",
        "degraded"
      ]
    },
    "retrieval": {
      "type": "string",
      "const": "stored"
    },
    "fetchedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "capturedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "errorCode": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        null,
        "provider_auth_required",
        "provider_config_invalid",
        "provider_throttled",
        "provider_unavailable",
        "provider_response_changed",
        "provider_scope_mismatch",
        "driver_persistence_unavailable"
      ]
    },
    "driver": {
      "$ref": "#/components/schemas/Driver"
    }
  },
  "required": [
    "status",
    "retrieval",
    "fetchedAt",
    "capturedAt",
    "errorCode",
    "driver"
  ]
}

← API overview · Download OpenAPI