Fieldmotion API Getting started

Vehicles

Update one mapped vehicle field

POST /a/Vehicle_updateField

Apply one mapped vehicle field to one or more numeric vehicle IDs.

When to use this endpoint

Use Vehicle_updateField for deliberate single-field bulk changes. Prefer Vehicle_updateData for ordinary form saves because this generic route exposes hidden mapped fields.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler requires login but performs no additional Vehicles-page, create, edit, delete, or role-permission check.

All reads and writes use the authenticated tenant’s tables. CRM1 and CRM2 may hide controls through client-side permissions; these routes do not repeat those UI checks.

Parameters

ParameterTypeRequiredDescription
id / idsInteger-compatible or native arrayYesOne numeric ID or an array. id takes precedence; all values are integer-converted and UUIDs become 0.
fieldStringYesOne exact mapped key from id, uuID, name, reg, description, costPerDistance, location, lastEdited, editedUUID, pricePerDistance, meta, cDate, and customValues. This includes normally hidden identifiers, timestamps, metadata, and even id.
valValue compatible with fieldYesReplacement value. Numeric types are converted; arrays/objects are JSON-encoded where stored. The route does not enforce the map’s required flags or layout-only minimum values.

Example request

$result = FM_api('Vehicle_updateField', [
	'ids' => ['30124', '30125'],
	'field' => 'description',
	'val' => 'Service fleet',
]);

Example response

{
  "ok": 1,
  "oldData": [
    {"id":"30124","description":"Service van"},
    {"id":"30125","description":"Support van"}
  ]
}

Errors and unusual responses

ResponseCondition
{"error":"not logged in"}No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
{"error":"missing or invalid parameter: field"}field is absent.
{"error":"missing or invalid parameter: val"}val is absent; an explicit blank value is accepted for text fields.
{"error":"missing or invalid field"}The field name is not in the vehicle map.
{"error":"missing or invalid parameter: id/ids"}Neither ID parameter is present.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • Rows already holding the same value are skipped. When every ID is missing or unchanged, the response is {"ok":"1","warning":"no change required"}.
  • Changing name or reg can set a blank registration because update-field does not enforce the required flag.
  • Changing customValues updates only meta.custom_values, preserving other metadata keys.
  • For a multi-ID nested customValues update, all matching rows are changed, but the shared logger retains only the last changed ID in its single history event.

Side effects

  • Changed rows receive the current last_edited datetime, invalidate the vehicle cache, and produce one Core history event naming the field and affected IDs.
  • edited_uuid is unchanged unless it is itself the selected field.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found. CRM1 uses dedicated setters for inline cells.

CRM2

No direct production caller was found; normal CRM2 vehicle forms submit Vehicle_updateData.

Related endpoints