Set an asset home location · Fieldmotion API

When to use this endpoint

Use Asset_setHomeLocation for the classic CRM1 Default Home control.

This changes the default/home metadata only; it does not change current whereabouts or movement history.

Authentication and permissions

The handler requires an authenticated tenant context, established by signed API-key fields or a CRM session. It checks the tenant prefix after validating id and performs no further permission check.

Parameters

Parameter	Type	Required	Description
`id`	Integer string	Yes	Positive asset ID. The row is not checked for existence or deleted state.
`home_location_type / loc_type`	Integer or string	Conditionally	Preferred and legacy names for the type. Accepts `-1..2`; aliases `location`, `area`, `site` → 0, `customer`, `client` → 1, and `asset` → 2, case-insensitively. Preferred key wins.
`home_location_id / loc_id`	Integer or exact name string	Conditionally	Preferred and legacy target keys. Digits are stored without an existence check. Other text must match exactly one eligible current name; preferred key wins. If type is omitted but ID is nonblank, type defaults to customer.

Example request

$result = FM_api('Asset_setHomeLocation', [
	'id' => '4821',
	'home_location_type' => 'site',
	'home_location_id' => 'Dublin Depot',
]);

Example response

null

Success intentionally has no PHP return value, so the dispatcher emits JSON null.

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: id"}`	`id` is absent, zero, or otherwise not positive.
`{"error":"Invalid Home Location Type"}`	The type is not an accepted integer or name.
`{"error":"Could not resolve Home Location"}`	A nonnumeric target name matches zero or more than one eligible row.

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

Behaviour and edge cases

A null response does not prove a row existed. The handler does not check the selected asset or the update result. A nonexistent ID and a successful update both return JSON null.

Blank ID or -1 stores target ID -1. Type -1 stores both type and ID as -1, which CRM1 uses to clear the default.
Named sites are matched without a deleted concept; named customers exclude soft-deleted rows; named assets require archived=0 but do not exclude soft-deleted rows.
If neither type nor ID key is supplied, metadata remains unchanged but last_edited is still refreshed.
Existing unrelated metadata is preserved. This endpoint has no filtering or pagination.

Side effects

Updates asset metadata and last_edited, and invalidates the asset cache. It writes no audit entry, movement, address snapshot, or notification event.

See it in Fieldmotion

CRM1

Edit or clear Default Home on the classic asset edit page and filter Network requests for Asset_setHomeLocation. CRM1 uses loc_type/loc_id.

CRM2

CRM2 source and regression tests align its home-location picker with this route’s type/ID contract, though mapped asset saves can write the metadata directly.

Related endpoints

Asset_setLocation changes current whereabouts and writes movement history.
Asset_updateData accepts mapped homeLocation data without name resolution.