Drivers / API reference

List drivers

Read the last complete driver directory without contacting a provider.

GET/v1/connections/{id}/drivers

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

Requires separate driver-directory consent and a consumer read grant. An existing vehicle key alone cannot expose driver PII.
Use next as cursor; keep time/expansion/groupScope filters fixed. Driver or group/config/health publication, and directory consent/publication/health changes, expire the cursor (410). Modified times include a conservative shared group relationship clock; they are not provider update times.
Pending and empty are distinct. Failed imports preserve the last good directory with degraded status. Disappearance is not physical deletion.
groups contains approved group IDs by default. Use groupScope=directory to resolve the same IDs/objects as groups?scope=directory; this requires both current read grants and matching verified accounts (otherwise 404). Add expand=groups for stored objects. groupMembership explains missing, unsupported, pending, stale or partial relationships; sourceScope distinguishes credential-visible memberships from a selected source-group capture. A known-empty result is scoped to that capture. Raw/deletion requests remain unavailable (409). Awaiting rollout and fleet/provider acceptance.

Parameters

Name	Where	Required	Type and behavior
`id`	path	Yes	`string`
`limit`	query	No	`integer` Page size, from 1 to 100. Duplicate query parameters are rejected. Default: `100`
`cursor`	query	No	`string` Opaque next cursor; keep time/expansion filters unchanged. Snapshot or approved-scope changes expire it.
`modifiedAfter`	query	No	`string` Exclusive ingestion change-time bound, explicit RFC3339 seconds with offset and at most six fractional digits.
`modifiedBefore`	query	No	`string` Exclusive ingestion change-time bound; must be after modifiedAfter.
`raw`	query	No	`boolean` Raw supplier data is unavailable. raw=true returns 409. Default: `false`
`deleted`	query	No	`boolean` No physical-deletion evidence. deleted=true returns 409; absence is not deletion. 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" \
  --header "Authorization: Bearer $TELEMATICS_CONSUMER_KEY"

Response fields

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

Field	Type	Required
`status`	`available \| pending \| 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
`results`	`Driver[]`	Yes
`next`	`string`	No

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": "pending",
  "results": [],
  "retrieval": "stored",
  "fetchedAt": null,
  "capturedAt": null,
  "errorCode": null
}

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`	Raw/deletion functionality unavailable; pending lists return 200 with status=pending
`410`	Driver or group relationship cursor expired; restart pagination
`413`	Expanded driver/group response exceeds 4 MiB; lower the list limit or omit expand=groups
`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",
        "pending",
        "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"
      ]
    },
    "results": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "$ref": "#/components/schemas/Driver"
      }
    },
    "next": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]+$"
    }
  },
  "required": [
    "status",
    "retrieval",
    "fetchedAt",
    "capturedAt",
    "errorCode",
    "results"
  ]
}

← API overview · Download OpenAPI