Skip to main content

Vehicle–Device associations and location

A Vehicle can have several associated Devices. Each association records one assignment interval. Transferring a Device ends that interval and creates another; history is retained. A Device with assignment history cannot be hard-deleted. Hardware trackers support deletion with retained history after all current assignments end. A Vehicle can also be connected to a connected-car provider that serves its VIN; see Connect a connected-car provider.

Attach and inspect a Device​

POST /api/v2/vehicle-device-associations accepts:

{
"vehicle_id": "00000000-0000-4000-8000-000000000001",
"device_id": "00000000-0000-4000-8000-000000000002",
"association_mode": "portable"
}

fixed means the Device belongs to this Vehicle until deliberately reassigned. Taking a tablet out overnight to charge does not change this. portable means the Device can accompany an agent between Vehicles. Dedicated trackers require fixed.

Creation returns 201 with the association and an absolute Location. Repeating a matching active pair, mode and explicitly requested source flags returns 200. A Device assigned elsewhere, or a contradictory create request, returns 409; use PATCH or transfer to change an existing assignment.

Use GET /api/v2/vehicle-device-associations?vehicle_id=… for current associations (lifecycle=current, the default). lifecycle=all includes history; device_id filters a Device's assignments. The standard items/page envelope uses page and size (1–100), ordered by started_at descending, then id ascending. Each item embeds current Device summary fields (device_natural_id, device_display_name, device_kind, device_model, and device_details_restricted), so callers do not need N+1 /api/v2/devices/{id} requests.

GET /api/v2/vehicle-device-associations/{association_id} remains available after ending. POST …/{association_id}/end ends the interval; repeating it has no additional effect. POST …/{association_id}/transfers requires vehicle_id and association_mode; lock_version is optional. It closes the old interval and returns a new one with 201. The supplied mode applies to the destination Vehicle; the old Vehicle's mode and history are retained, never copied implicitly.

{
"vehicle_id": "00000000-0000-4000-8000-000000000003",
"association_mode": "portable",
"lock_version": 3
}

Transferring to the same Vehicle with its current confirmed mode returns 200 without changing it. A different or unconfirmed same-pair mode returns field-level 422; use PATCH to change or confirm that association. Missing, null or invalid transfer modes also return 422. An ended association or stale version returns 409. An older unclassified association can move to a different Vehicle with an explicit destination mode; its unknown earlier history remains unknown.

These management reads require vehicles:read and devices:read. Writes require vehicles:update and devices:update. Authenticate as a user or service account with those grants.

Choose the location source​

One active association at most has is_location_source: true. Update an association with PATCH /api/v2/vehicle-device-associations/{association_id}:

{
"is_location_source": true,
"lock_version": 3
}

Use Content-Type: application/merge-patch+json. Selecting one Device clears that flag on the previous source atomically. Affected association versions advance. Omitted fields stay unchanged; explicit null is invalid for association_mode, is_location_source and is_preferred_fixed_source. The optional lock_version detects concurrent changes; omit it or send null to skip that check.

The same PATCH supports a narrow phone self-service path. Send the human token as primary bearer, secondary X-Device-Authorization: Bearer <device-token>, and only is_location_source plus optional lock_version. It requires vehicles:device-location:use-self, this exact registered human session, and authority on a readable active Tour using the Vehicle. This path needs no broad vehicles:read or Device/Vehicle management grants. The addressed association must belong to the proven Device. It cannot change mode/preference or mutate another Device's association. Use GET /api/v2/devices/current/vehicle-association to obtain your own episode ID/version; this gives no management list/detail permission. See Device proof.

Source priority is a configured tracker, then a fixed app Device, then a portable phone. The first configured tracker or fixed app Device becomes the source automatically. Adding another of the same kind keeps the existing choice. A portable Device requires explicit selection. Confirm all legacy association modes before making generic source selections.

is_preferred_fixed_source: true chooses the fixed app Device to use when a tracker does not take priority. This preference stays visible when a tracker supplies GPS. It can be changed independently while that tracker remains selected. Selecting a lower-priority Device, or deselecting configured hardware without replacing/ending it, returns 422.

Ending or transferring the selected association clears the source without selecting a replacement. Changing the selected fixed app Device to portable also clears its source and fixed preference. A permitted manager can then select another eligible association. A stale source never causes an automatic switch.

Source selection is separate from the workspace and Device reporting policy, which determines whether a phone is allowed to report location. Selecting a Device does not override that policy.

Disconnect or log out this Device​

Read /api/v2/devices/current/vehicle-association with human plus Device proof, or with the Device token as primary bearer for recovery. The response contains device_id, optional user_association_id, and optional vehicle_association with its id, vehicle_id, mode, source flags and version. It embeds no user profile or Vehicle details. Read permitted Vehicle names and positions separately; missing permission does not mean the association is absent.

A human with devices:vehicles:assign-self can explicitly disconnect the observed episode:

POST /api/v2/devices/current/vehicle-association/end
Authorization: Bearer <human-access-token>
X-Device-Authorization: Bearer <device-access-token>
Content-Type: application/json
{ "expected_vehicle_association_id": "00000000-0000-4000-8000-000000000003" }

This ends portable or deliberately released fixed associations, keeps human and Device credentials, and leaves Tour assignments intact. Ordinary human logout instead ends only expected_user_association_id through /api/v2/devices/current/user-association/end; it retains the Vehicle association. Full Device logout uses the Device token as primary bearer and optional expected IDs (explicit null for absence, or omitted to end the current associations unconditionally) through /api/v2/devices/current/logout.

Each successful end/logout returns 200 with the final current-Device context. Preserve that response: human logout may revoke the caller before it can make another read. On timeout, use Device-primary recovery where necessary and retain the original expected IDs for a retry. Newer context requires fresh intent, never an automatic replacement of those IDs. Clear local Device credentials only after acknowledged Device logout. Plugin work guards still apply.

Read the position​

GET /api/v2/vehicles/{definition_ref}/records/{vehicle_id}/current-location requires vehicles:read. It returns 200 and omits location when no position is known. It includes:

  • location.located_at: observation time, when known. Derive position age as current time minus this timestamp. Imported positions may omit the timestamp; an absent location means no known position. The API does not classify freshness.
  • vehicle_association_id: the selected active association; omitted when no source is selected.
  • source_status: always selected or unselected, including before any source has been chosen.
  • source: the currently selected active Device's category (tracker, fixed_device, portable_device or unconfirmed_device). It is omitted when no active source is selected. device_id and device_display_name require devices:read; otherwise they are omitted and details_restricted is true. The category remains available to Vehicle readers. A selected provider connection has kind provider and carries its provider_connection_id, which requires connected-vehicles:read; without it the id is omitted and details_restricted is true.
  • position_vehicle_association_id: the association that supplied the retained position, when known.
  • position_provider_connection_id: the provider connection that supplied the retained position. It requires connected-vehicles:read and is omitted otherwise.

Changing the source never relabels, clears or refreshes the previous position. The two association IDs can therefore differ until the newly selected Device supplies a new fix. Historical positions with unknown provenance omit position_vehicle_association_id.

For example, this response selects a fixed tablet that has not supplied a position yet:

{
"vehicle_id": "00000000-0000-4000-8000-000000000001",
"vehicle_association_id": "00000000-0000-4000-8000-000000000003",
"source_status": "selected",
"source": {
"kind": "fixed_device",
"device_id": "00000000-0000-4000-8000-000000000002",
"device_display_name": "Van tablet",
"details_restricted": false
}
}

selected describes the source choice, not a live GPS connection. Reporting policy, OS permission and connectivity still govern collection and delivery. A stale selected source is not automatically replaced by another Device.

Only observations within the active assignment and current source-selection intervals can advance the position. Missing/future observation times and older/equal fixes are ignored. Queued observations are checked again when projected. Worker retries preserve accepted updates across delivery failures. GPS updates do not change the Vehicle's human-edit lock_version.

Vehicle records expose this same position in read-only data.location. The former generic /vehicle-connections and Vehicle /location-policy endpoints are removed.

Connect a connected-car provider​

A workspace administrator stores provider accounts (DRVN or High Mobility) under Settings → Integrations → Connected Vehicle. GET /api/v2/connected-vehicle-providers lists them, ordered by name and disabled ones included, with id, name, provider, environment and enabled; their configuration and credentials are not part of it. Listing needs connected-vehicle-providers:read, connected-vehicle-providers:write or connected-vehicles:create.

A provider connection serves the Vehicle's current VIN through one of those accounts, named by its id as provider_account_id. Problem types in this section are given relative to https://problems.tourfold.com/; error types lists them in full. POST /api/v2/vehicle-provider-connections accepts:

{
"vehicle_id": "00000000-0000-4000-8000-000000000001",
"provider_account_id": "00000000-0000-4000-8000-000000000031",
"brand": "bmw",
"data_source": "bmw_b2c_reactive_car_data"
}

brand and data_source are named as the provider names them: brand has at most 64 characters, data_source at most 128 letters, digits, '.', '' or '-', including a letter or digit. High Mobility clears a VIN for one brand, so a connection through it without brand returns field-level 422. Only DRVN keeps a consent per product: a DRVN connection without data_source takes the account's default product and keeps it, so a later change of that default never moves the connection's consent, refresh or revocation, and data_source on another provider's connection returns field-level 422. The Vehicle must have a VIN that provider requests can carry (at most 64 letters, digits, '.', '' or '-'), which the connection records in uppercase as vin when it starts; a Vehicle without one returns field-level 422, as does an unknown or disabled account. Connecting never contacts the provider.

Creation returns 201 with the connection and an absolute Location. Repeating the same active connection returns 200; a repeat without data_source accepts the connection's product. The same account serving that VIN on another Vehicle, or this Vehicle with another brand or data source, returns 409: each cleared VIN is billed by the provider, so a second binding is never created silently.

Use GET /api/v2/vehicle-provider-connections?vehicle_id=… for active connections (lifecycle=current, the default); lifecycle=all includes ended ones. The standard items/page envelope uses page and size (1–100), ordered by started_at descending, then id ascending. GET …/{connection_id} remains available after ending.

An active connection protects the VIN it serves: changing or clearing the Vehicle's VIN returns 409 until the connection has ended, and so does removing the VIN attribute from the Vehicle's definition while any of its Vehicles has an active connection. POST …/{connection_id}/end ends it, releases it as location source and queues the revocation with the provider (see below); repeating it has no additional effect. Connections are never transferred, and a Vehicle with provider connection history cannot be deleted.

Reads require vehicles:read and connected-vehicles:read. Creating requires vehicles:update and connected-vehicles:create; selecting the location source requires vehicles:update and connected-vehicles:update; ending requires vehicles:update and connected-vehicles:delete.

Use a provider as location source​

PATCH /api/v2/vehicle-provider-connections/{connection_id} with Content-Type: application/merge-patch+json selects or releases an active connection as the Vehicle's location source:

{
"is_location_source": true,
"lock_version": 0
}

Selecting it replaces the previously selected Device or connection, and the Vehicle adopts the newest position the connection has already delivered. Its later data requests then advance the position: a fix counts when it was measured after the connection started, no later than it was received, and after the current position. Selecting a connection never asks the provider for data. Selecting an ended connection returns 409 vehicle-provider-connections/connection-ended; a stale lock_version returns 409 resource-conflict; explicit null for is_location_source returns 422. Every source change advances the lock_version of the connection or Device association it selects or displaces and publishes its updated event, so a client holding the earlier version is told. While a plugin's operational Device supplies the location (BW, ÖAMTC), selecting a provider returns 409; releasing or ending a connection is always possible.

GET …/{connection_id}/authorization returns the consent or clearance as the provider last reported it: status is not_requested, pending, approved, rejected, revoking, revoked, error, unknown or not_required, with checked_at and, after the connection ended, revocation_status (pending, confirmed, not_required, failed). DRVN only delivers data for a car it has taken on. Once the consent Tourfold requested is approved, the next authorization operation, data operation or phone-fix prediction takes the car on; an authorization operation that cannot sets reason to what blocks it, and reason is cleared once the car is taken on. A revocation is not_required when nothing was granted, or when the VIN was connected again through the same account and still relies on that consent: for DRVN with the same product, for High Mobility with any brand.

POST …/{connection_id}/authorization-operations queues provider work. It returns 202 Accepted with the operation and its URL in Location, where its progress is read:

{"action":"authorize","request_id":"e39fd6a8-909e-450b-a2cb-a04d65d62a5c"}

authorize asks for consent and can contact the Vehicle's owner; refresh only reads the current state. revoke applies to an ended connection and restarts a failed revocation; on an active connection it returns 409 resource-conflict. request_id is your key for the request: repeating it returns the same operation in its current state, again with 202, so a request whose answer was lost can be sent again safely. The other conflicts return 409 with a type a client can act on:

Problem typeWhen
vehicle-provider-connections/authorization-already-requestedConsent is already pending or approved; refresh learns whether that changed.
vehicle-provider-connections/operation-in-progressAnother authorization operation of the connection has not finished.
vehicle-provider-connections/connection-endedThe connection has ended.
vehicle-provider-connections/account-disabledThe account serving the connection is disabled.
vehicle-provider-connections/request-id-reusedThe request_id was already used for another action.

Operations run in the background and retry transient provider failures; an answer lost in transit is reconciled by reading the provider's state rather than asking the owner again. Read them with GET …/authorization-operations and …/authorization-operations/{authorization_operation_id}. Queuing needs vehicles:read and connected-vehicles:authorizations:write; reading needs vehicles:read and connected-vehicles:read.

Data requests and observations​

POST …/{connection_id}/data-operations reads the Vehicle's data from the provider. Like an authorization operation it returns 202 with the operation and its Location:

{"request_id":"5b0d2f61-3c7e-4b5a-9f39-0f6f2f6c1d22","contents":["status"],"refresh":false}

contents holds status (location, odometer, levels, range, speed, ignition) and/or diagnostics (fault codes and dashboard lights) and defaults to status. refresh: true first asks the vehicle for fresh data; it is billed by the provider, can wake the vehicle and is sent at most once, so the operation then waits (waiting) before reading. Content or a refresh the provider cannot serve, or a document named twice, returns 422. Repeating a request_id with the same content returns the same operation; with other content it returns 409 vehicle-provider-connections/request-id-reused. Another open data request returns 409 vehicle-provider-connections/operation-in-progress, and an ended connection or a disabled account the connection-ended and account-disabled types. A data operation's status is queued, running, waiting, succeeded, partial or failed, and lists the observation_ids it stored.

Each provider answer is stored as an observation: GET …/observations lists them newest first. GET …/measurements combines the latest value of each signal, each with its own observed_at; a signal the provider did not deliver is absent. The raw provider answer and the HTTP exchange behind an observation or data operation, with secrets redacted, are at …/observations/{observation_id}/evidence and …/data-operations/{data_operation_id}/evidence. Requesting data needs vehicles:read and connected-vehicles:data-operations:write; reading needs vehicles:read and connected-vehicles:read; evidence needs vehicles:read and connected-vehicles:raw-data:read.

Phone-fix predictions​

A DRVN connection can be asked how likely a reported breakdown is to be resolved over the phone. POST …/{connection_id}/phone-fix-predictions queues the question and returns 202 with the prediction and its Location:

{"request_id":"c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f","symptom":"wont_start"}

symptom is one of DRVN's symptom values (wont_start, battery_flat, fuel_starvation, …; the VehiclePhoneFixSymptom schema lists them all). The prediction is computed from the data the provider already holds: nothing is read from the vehicle and nothing is billed. Once it succeeded, the prediction carries probability (0 to 1) and baseline_probability, the provider's prior for that symptom across its fleet; read the vehicle's number against the baseline. A provider that offers no prediction (High Mobility) returns 422 on symptom; an ended connection or a disabled account returns 409 vehicle-provider-connections/connection-ended or account-disabled. Repeating a request_id with the same symptom returns the existing prediction, again with 202; with another symptom it returns 409 vehicle-provider-connections/request-id-reused. A prediction the provider refused ends failed with a failure_code (VehicleProviderRequestFailureCode, shared with authorization and data operations), such as provider_rejected, or provider_unavailable once transient failures used up the attempts.

A workspace plugin that receives breakdown cases (ÖAMTC) asks on its own: when a roadside case arrives for a VIN that an active DRVN connection serves, the case's fault classification is mapped to a symptom and queued once per case and symptom, and the prediction then carries reporting_case. It names the case's id; a reader who also holds cases:read sees the case's external_id, the reported_fault classification and the mapping_rule that chose the symptom. Read predictions with GET …/phone-fix-predictions (newest first) and …/phone-fix-predictions/{prediction_id}; the provider's raw answer is at …/phone-fix-predictions/{prediction_id}/evidence. Asking needs vehicles:read and connected-vehicles:data-operations:write; reading needs vehicles:read and connected-vehicles:read; evidence needs vehicles:read and connected-vehicles:raw-data:read.

Receive assignment and source changes​

Subscribe to vehicle_device_association.created and vehicle_device_association.updated for assignment episodes. Their data.object includes the association id, vehicle_id, device_id, started_at, optional ended_at and association_mode, lock_version, and the boolean is_location_source and is_preferred_fixed_source flags. The flags reflect the coordinated transaction result. An ended episode has both flags set to false. An unknown legacy mode is omitted, rather than inferred as portable.

Provider connections publish vehicle_provider_connection.created and vehicle_provider_connection.updated (ending it, or changing is_location_source), and their queued work publishes vehicle_provider_connection.authorization_operation.created/.updated, vehicle_provider_connection.data_operation.created/.updated and vehicle_provider_connection.phone_fix_prediction.created/.updated; a prediction a case asked for is published like one an operator asked for.

vehicle.location_source.updated describes a change of the Vehicle's selected source. Its data.object contains the Vehicle id, the selected association_id and source_kind, and the server's effective_at time. data.previous_attributes holds the references that changed: the previous association in association_id, explicitly null for an initial selection, and the previous provider connection in provider_connection_id, null if there was none. On deselection, association_id and source_kind are omitted from data.object. When a provider connection is selected, data.object.provider_connection_id names it.

For example, the data portion of a source switch looks like this:

{
"object": {
"id": "00000000-0000-4000-8000-000000000001",
"association_id": "00000000-0000-4000-8000-000000000004",
"source_kind": "fixed_device",
"effective_at": "2023-02-14T10:00:00Z"
},
"previous_attributes": {
"association_id": "00000000-0000-4000-8000-000000000003"
}
}

These are source-selection events, not reporting-policy or GPS-update notifications. They do not expose internal policy revisions or age thresholds. See Webhooks for delivery, subscription and envelope conventions.

Plugin compatibility​

BW and ÖAMTC retain their operational-Device behavior. Their operational Device is always also the GPS source; attempting to choose another source or deselect it returns 409. Clearing the operational Device retains the last position. ÖAMTC forwards eligible observations from that same Device to ELOG with the captured branch and driver attribution.

For those plugins, POST /api/v2/vehicle-device-associations with "operational": true selects or replaces the operational Device, GET /api/v2/vehicle-device-associations?vehicle_id=…&operational=true reads the active operational assignment episode, and POST /api/v2/vehicle-device-associations/{id}/end clears it. No-op selections remain accepted during active Tours; actual changes retain plugin restrictions. Passing "operational": true is rejected for generic tenants.

Generic assignment and source webhooks use the canonical names documented above, including for Vehicles used by a plugin; this does not change BW's external EBA API.

Plugin location responses​

BW and ÖAMTC expose vehicle locations as values belonging to the surrounding Vehicle. Use the Vehicle's id for identity. Locations have no separate public database ID or audit/version fields. BW keeps coordinates and observation timestamp under location, with address fields under location.address. ÖAMTC tour vehicle entries keep coordinates and address fields together under location, with address_timestamp for the observation time.

The location cleanup removes id from ÖAMTC locations and id, created_at, updated_at, and lock_version from BW vehicle addresses, including the retained frontend-v2 Vehicle GET alias. Update generated clients with this backend release. Other address fields and observation timestamps keep their existing names. The separately specified BW EBA contract is unchanged.

Named Location attributes​

Vehicle definitions can also declare ordinary Location fields such as home_depot or meeting_point. They use the same fixed/tracking value shape as Objects and are written in record data. They are independent of the intrinsic data.location.

A named field can store a fixed position/address or track a declared Location on another Object or Vehicle. Vehicle references use object: "vehicle" and the native Vehicle UUID, with attribute identifying location or a named field. Object references use the Object definition's slug. Vehicle and Object definitions have distinct slugs; location identity still uses the owning family and record UUID.

{
"data": {
"home_depot": { "lat": 48.2, "lon": 16.3 },
"meeting_point": {
"tracking": {
"object": "vehicle",
"record_id": "00000000-0000-4000-8000-000000000012",
"attribute": "location"
}
}
}
}

PATCH omission preserves the value; null clears an optional field. Required fields cannot be cleared. An equivalent value does not advance the Vehicle version. A tracked source moving does not change the tracking Vehicle's version or source selection. Cycles, missing sources and unreadable targets resolve without coordinates while retaining the tracking reference. Reads, snapshots and ordinary-field live updates apply the reader's target permissions; possessing Vehicle read access does not expose a private Object.