Fieldmotion API Getting started

Saved views and configuration

Update a configurable picklist choice

POST /a/CommonList_updateData

Patch list labels, metadata or other mapped fields by physical row ID.

When to use this endpoint

Use CRM2 inline editing to rename a choice without changing the value stored on customer/job records. Supply the physical ID from the table, not the value-based ID returned by the detail reader.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. The handler requires login, without an additional list-management/page/role permission check. Lists belong to the authenticated tenant, not an individual user.

Parameters

ParameterTypeRequiredDescription
idInteger string or native arrayYesPhysical row ID(s), integer-coerced. Multiple IDs are updated sequentially.
Mapped changesScalars or native JSON valuesNoMutable fields: type, name, value, required, meta, metaColor, metaOrgName, cdate, lastEdited. Unknown/null values ignored. Type/name cannot be blank when supplied; other fields are not required for a partial update.
noRecordNative arrayNoLegacy audit visibility control marking matching changed keys hidden in history. External callers should omit it.

Example request

$result = FM_api('CommonList_updateData', ['id' => '1042', 'name' => 'Primary site contact']);

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":"missing or invalid parameter: id"}Selector omitted.
{"error":"missing or invalid parameter: name"}Blank required name; blank type has the equivalent type error.
{"error":"Unable to update record"}Primary update failure.
{"warning":"No data."}No physical row matched for a scalar ID.
{"warning":"No Change."}Existing values compare equal; no update needed.

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

Behaviour and edge cases

  • Mapped keys: id (physical row ID), type (list namespace), name, value (business choice ID), required (integer), meta (JSON), metaColor (meta.color), metaOrgName (meta.orgName), cdate, lastEdited. Integer fields are coerced; JSON meta replaces the whole value, while metaColor/metaOrgName patch their respective keys.
  • Readonly/hidden map layout flags do not block direct writes. There is no configured text-length limit; schema limits still apply.
  • ID alone returns ok without an existence check; unknown-only changes return {"warning":"no updated fields."}. Arrays return final ok unless an error stops the loop, in which case updatedIds/failedId identify partial progress. Warnings do not stop the batch.
  • No transaction, duplicate-name/value check, relationship repair or page permission. No tenant feature flag is consulted.

Side effects

  • Updates mapped columns and stamps last_edited to current Unix seconds on a change, requests the common_lists cache marker and writes generic change history. A supplied lastEdited does not override the final automatic stamp.
  • No customer/job row update, notification or email. App list-sync checkpoints use the new last_edited value.

See it in Fieldmotion

CRM1

No direct CRM1 caller to this CommonList route was found in the source search. CRM2 uses these generic list endpoints for configurable customer contact types, job sub-statuses, purchase statuses and contract stages.

CRM2

Open CRM2 customer settings → Contact Types. pageSettingsContactTypes.js uses CommonList/CommonLists widget prefixes and shared create/detail/edit helpers. Filter the Network panel for this endpoint. Inline name edits and shared bulk updateData helpers resolve to this route.

Related endpoints