Create a mapped vehicle · Fieldmotion API

When to use this endpoint

Use Vehicle_createData for CRM2’s create form or an integration that needs mapped vehicle fields, custom values, and the new numeric ID. Use Vehicle_update only when reproducing the older CRM1 UUID workflow.

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

Parameter	Type	Required	Description
`id`	Integer-compatible or native array	No	Ignored for creation; the database assigns the numeric ID.
`uuID`	String	No	Vehicle UUID. Creation generates a random 32-character hexadecimal value when omitted. The unusual capitalisation is the exact mapped field name.
`name`	String	Yes	Registration value used by CRM2 layouts. It maps to the same database column as `reg`; creation requires a nonempty `name` even when `reg` is also supplied.
`reg`	String	No	Legacy alias for the registration column. If both `name` and `reg` are supplied, the later `reg` mapping wins. Duplicate and blank values are not rejected on update.
`description`	String	No	Free-text vehicle description.
`costPerDistance`	Numeric-compatible	Yes	Internal cost per mile or kilometre, converted with `floatval()`. The layout declares a minimum of zero, but the shared server-side converter does not enforce that layout minimum.
`pricePerDistance`	Numeric-compatible	Yes	Customer charge per mile or kilometre, converted with `floatval()`. Negative values are accepted despite the layout’s zero-minimum metadata.
`location`	String	No	Legacy free-text location stored directly on the vehicle.
`lastEdited`	Datetime string	No	Mapped edit time. Ordinary mapped writes set `last_edited` to the current server datetime when a change is made.
`editedUUID`	String	No	Legacy edit-source marker. Mapped updates do not populate it automatically.
`meta`	JSON-compatible value	No	Complete vehicle metadata value. Arrays are JSON-encoded for storage; a blank string stores SQL `NULL`.
`cDate`	Unix timestamp or date string	No	Creation time stored as a Unix timestamp. Creation defaults to the current server time; mapped reads format it as a datetime.
`customValues`	Object or associative array	No	Custom vehicle values stored below `meta.custom_values`. Supplying this field replaces that nested object.

Example request

$vehicle = FM_api('Vehicle_createData', [
	'name' => '241-D-12001',
	'description' => 'Service van',
	'costPerDistance' => '0.42',
	'pricePerDistance' => '0.75',
]);

Example response

{"ok":1,"id":30124}

Errors and unusual responses

Response	Condition
`{"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: name"}`	`name` is absent or serialises as an empty string.
`{"error":"missing or invalid parameter: costPerDistance"}`	The required mapped cost is absent.
`{"error":"missing or invalid parameter: pricePerDistance"}`	The required mapped price is absent.

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

Behaviour and edge cases

name is stored in the reg column. Registration values are not normalised and need not be unique.
The generated uuID is 32 hexadecimal characters. cDate defaults to the current Unix timestamp, while last_edited is written as the current server datetime.
The table has no active, archived, or soft-delete field.

Side effects

Inserts a tenant vehicles row, invalidates the vehicle cache, and writes Core history for mapped values supplied or defaulted during creation.

See it in Fieldmotion

CRM1

CRM1 creates vehicles with Vehicle_update, not this mapped route.

CRM2

Open Stock → Vehicles in CRM2 and filter browser developer tools for the exact function name. Choose Create; the display widget derives Vehicle_createData from its Vehicle API prefix.

Related endpoints

Vehicle_getRequestedDetails reads mapped fields and custom values.
Vehicle_updateData applies later mapped changes.