Fieldmotion API Getting started

Task types

Update one mapped task-type field

POST /a/TaskType_updateField

Update one mapped task-type field for one or several IDs and return the prior physical values.

When to use this endpoint

Use TaskType_updateField for CRM2 inline edits that target one mapped field. Prefer TaskType_updateData when changing several fields together.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler calls the normal login guard but performs no additional Settings-page, role, create, edit, or delete permission check.

All reads and writes use the authenticated tenant. CRM1 and CRM2 decide whether to show task-type controls, but these handlers do not repeat those client-side checks.

Parameters

ParameterTypeRequiredDescription
fieldMapped field nameYesOne of id, name, cDate, or lastEdited. Layout readonly flags are not enforced, so even primary-key id is accepted.
valValue compatible with fieldYesReplacement value. Presence, not nonblank content, is required.
id / idsInteger-compatible or native arrayYesOne ID or several IDs. Scalar input is integer-converted; array members are integer-converted. id takes precedence when both are supplied.

Example request

$result = FM_api('TaskType_updateField', [
	'id' => '3',
	'field' => 'name',
	'val' => 'Priority customer follow-up',
]);

Example response

{
  "ok": 1,
  "oldData": [
    {"id": "3", "name": "Customer follow-up"}
  ]
}

oldData uses physical storage column names such as cdate and last_edited, not mapped response names.

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: field"}field is absent.
{"error":"missing or invalid parameter: val"}val is absent.
{"error":"missing or invalid field"}field is outside the four-key map.
{"error":"missing or invalid parameter: id/ids"}Neither ID parameter exists.
{"ok":"1","warning":"no change required"}No matching row differs from the requested value, including when no row matches.

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

Behaviour and edge cases

  • Only rows whose selected physical value differs by strict PHP comparison are updated. Task types have no deleted-state filter.
  • Any real update also writes current server time to last_edited. Therefore field=lastEdited does not preserve the requested value; the appended current timestamp wins.

Side effects

  • Invalidates the task-type cache and writes one aggregate audit-history entry naming the mapped field and affected IDs.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found.

CRM2

Open Settings → Task Types. CRM2’s shared data widget derives the mapped create, detail, update, single-field update, and table routes from the TaskType/TaskTypes prefixes.

Related endpoints