Assets
Set asset contacts
/a/Asset_setContacts
Replace the complete encoded contacts value stored on one asset.
When to use this endpoint
Use Asset_setContacts only when the caller owns the complete contacts payload and intends to replace it.
The endpoint does not merge individual contacts or validate their shape. Read the existing value first when unknown entries must be preserved.
Authentication and permissions
The handler requires an authenticated tenant context, established by signed API-key fields or a CRM session. It checks the tenant table prefix but does not separately require a logged-in user ID.
No page, role, or asset permission is checked.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer string | Yes | Positive server-side asset ID. The existence check includes soft-deleted assets. |
val | JSON string | Yes | Complete value written to the JSON contacts column. Omission is rejected, but syntax and object shape are not validated by the handler. Supply encoded JSON rather than a nested request array. |
Example request
$result = FM_api('Asset_setContacts', [
'id' => '4821',
'val' => json_encode([['name' => 'Site Manager', 'phone' => '01234 567890']]),
]);Example response
{
"ok": 1
}A loosely equal stored value returns {"ok":1,"msg":"no change needed"}.
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 or does not convert to a positive integer. |
{"error":"missing or invalid parameter: val"} | val is omitted. A present blank string reaches the database write. |
{"error":"asset does not exist"} | No asset row has the ID. Soft-deleted rows still count as existing. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- The no-change test uses PHP loose equality and returns before timestamps, logs, or events change.
- A nested array value is not serialized by this handler and can cause a runtime type error; encode it before signing the request.
- The endpoint can update archived or soft-deleted assets.
- This is a single-record mutation; it provides no list filtering or pagination.
Side effects
- On the change path, the update attempts to replace
contacts, refreshlast_edited, and setedited_uuidtoAsset_setContacts. It does not explicitly invalidate the asset cache. - Writes an asset audit entry and fires the tenant-configurable
Asset_editevent. Event handlers can perform additional tenant-specific actions, and the operations are not transactional.
See it in Fieldmotion
CRM1
No direct production CRM1 call to Asset_setContacts was found.
CRM2
No direct production CRM2 call to Asset_setContacts was found.