Change a job’s vehicle · Fieldmotion API

When to use this endpoint

Store a vehicle identifier and refresh job cost/price calculations.

Read the target job first with Jobs_getSome to obtain the current values and confirm the IDs belong to the intended account.

Authenticate with signed API-key fields or a logged-in CRM session. The request uses the authenticated account’s job IDs, not mobile app IDs.

No extra page, role, assignee, department or client-administrator check is applied by this handler.

Parameter	Type	Required	Description
`id`	Integer string	Yes	Physical job ID in the authenticated account, converted with intval; must be positive.
`value`	String	Yes	Required present value, trimmed and stored as text. Existing numeric vehicle IDs or UUIDs are consumed by cost calculation. Blank/zero can trigger fallback to the assigned user’s default vehicle. No vehicle-existence or format validation occurs here.

$result = FM_api('Job_setVehicleId', ['id'=>'1042', 'value'=>'701']);

{"ok":1}

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: id"}`	id is absent or converts to a nonpositive integer.
`{"error":"missing parameter: value"}`	value is absent or null.
`{"error":"Unable to save job"}`	The primary database write failed. History and dependent effects are not performed for that failed save.
`{"error":"job does not exist"}`	The active target is missing/deleted or the existence lookup failed.
`{"ok":1,"warning":"Job saved, but cost recalculation failed"}`	The field was saved but the cost helper returned an error. Inspect the job’s derived costs before retrying.

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

Requires an active job before writing. A missing/deleted target or failed existence lookup returns job does not exist. The final UPDATE also excludes deleted jobs.
No equality check is applied. The final vehicle may differ from blank input because cost recalculation chooses the user’s default vehicle.
Cost recalculation uses current user wage and vehicle cost_per_distance, work-day-start/end, overtime-multiplier and travel-is-labour-cost, and the configured exclusions for stock tables. It is not a distance-unit conversion or an accounting-system write.
The primary UPDATE is checked before history and dependent effects. There is no transaction combining this field write with later cross-object effects; inspect committed-success warnings before retrying.

Writes last_edited and edited_uuid with the changed fields and invalidates the meetings cache.
Records a job history entry. No mail is sent directly by this setter.
Calls Job_updateCosts after the checked field write; a returned calculation error produces committed success with a warning. That helper can recalculate labour/overtime, mileage, stock, rate and miscellaneous costs; backfill resource costs/prices; choose the user’s default vehicle; and call Job_updatePrices. Pricing can update price_net/price and, when autoupdate-job-value=1, meta.job_value. This is broader than only the edited input.

No direct CRM1 caller was found in the canonical/legacy route search. This is a focused API setter; other edit flows need not use it.

No direct CRM2 caller was found in the canonical/legacy route search. CRM2’s layout-driven updates are a separate contract.

Vehicles_list supplies vehicle choices.
Job_setMileage changes distance and recalculates the related costs.
Jobs_getSome reads selected job records before editing and verifies the stored result afterward.