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 absentlocationmeans no known position. The API does not classify freshness.vehicle_association_id: the selected active association; omitted when no source is selected.source_status: alwaysselectedorunselected, including before any source has been chosen.source: the currently selected active Device's category (tracker,fixed_device,portable_deviceorunconfirmed_device). It is omitted when no active source is selected.device_idanddevice_display_namerequiredevices:read; otherwise they are omitted anddetails_restrictedis true. The category remains available to Vehicle readers. A selected provider connection has kindproviderand carries itsprovider_connection_id, which requiresconnected-vehicles:read; without it the id is omitted anddetails_restrictedis 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 requiresconnected-vehicles:readand 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.
Consent
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 type | When |
|---|---|
vehicle-provider-connections/authorization-already-requested | Consent is already pending or approved; refresh learns whether that changed. |
vehicle-provider-connections/operation-in-progress | Another authorization operation of the connection has not finished. |
vehicle-provider-connections/connection-ended | The connection has ended. |
vehicle-provider-connections/account-disabled | The account serving the connection is disabled. |
vehicle-provider-connections/request-id-reused | The 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.