Fieldmotion API Getting started

Assets

Set an asset serial number

POST /a/Asset_setCode

Replace an asset’s serial number after applying the tenant’s optional uniqueness rule.

When to use this endpoint

Use Asset_setCode for an inline serial-number edit on a known asset.

The endpoint accepts a blank serial number; integrations that require a value must enforce that rule themselves.

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

ParameterTypeRequiredDescription
idInteger stringYesServer-side asset ID after integer conversion. A present zero or invalid value reaches the not-found response. The existence check includes soft-deleted assets.
valStringYesNew serial number after trimming; blank is accepted.

Example request

$result = FM_api('Asset_setCode', [
	'id' => '4821',
	'val' => 'CMP-004',
]);

Example response

{
  "ok": 1
}

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":"no ID provided"}id is omitted.
{"error":"no val provided"}val is omitted. A present blank value is accepted.
{"error":"asset does not exist"}No asset, including a soft-deleted one, has the converted ID.
{"error":"An asset with that Serial Number already exists"}The tenant setting asset-unique-code is enabled and another non-deleted asset has the same trimmed value.

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 uniqueness check excludes the addressed ID and soft-deleted rows but includes archived rows.
  • The endpoint can update a soft-deleted asset and has no no-change shortcut.
  • This is a single-record mutation; it provides no list filtering or pagination.

Side effects

  • Updates code and last_edited, sets edited_uuid to Asset_setCode, invalidates the asset cache, and writes an asset audit entry.

See it in Fieldmotion

CRM1

Edit Serial Number in the Assets table, customer Assets tab, or asset edit page and filter Network requests for Asset_setCode. CRM1 surfaces uniqueness errors and restores the prior inline value.

CRM2

No direct production CRM2 call to Asset_setCode was found; CRM2 uses its broader update contract.

Related endpoints

  • Asset_get returns the stored serial number as code.
  • Asset_new accepts a serial number during creation and uses the same uniqueness setting.
  • Asset_setName applies the corresponding optional name-uniqueness rule.