Fieldmotion API Getting started

Tasks

Update one mapped task field

POST /a/Task_updateField

Set one mapped field across one or many active tasks and return the prior storage values.

When to use this endpoint

Use Task_updateField for CRM2 inline/bulk mapped edits that need one common value and do not need Task-specific mentions or notification-service events.

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 task, page, role, ownership, or privacy-permission check.

All reads and writes use the authenticated tenant. CRM1 and CRM2 apply task visibility and editing permissions in their interfaces, but these handlers do not repeat those client-side rules.

Parameters

ParameterTypeRequiredDescription
fieldStringYesExact Task map key. Supported field keys are id plus type, details, resolution, userID/user, assignedDate, status, customerID/customer, createDate, lastEdited, createdBy, appId, editedId, privacy, meta, subject, dueDate, minutes, customValues, and metaPreviousUser. Layout readonly/hidden flags are not enforced; callers must never use this route to change id.
valValue compatible with fieldYesCommon new value. Numeric fields are coerced, JSON-compatible arrays/objects are encoded, and scalar picker fields such as user/customer should receive an ID rather than an object.
id / idsInteger or native integer arrayYes (one name)One target or a batch. Every value is integer-coerced; only active rows found by the initial lookup can be changed.

Example request

$updated = FM_api('Task_updateField', [
	'ids' => ['318', '319'],
	'field' => 'status',
	'val' => '2',
]);

Example response

{
  "ok": 1,
  "oldData": [
    {"id": "318", "status": "1"},
    {"id": "319", "status": "0"}
  ]
}

Rows already holding a strictly equal raw value are omitted from the update ID list, but oldData contains every active row returned by the lookup.

oldData uses physical storage-column names rather than necessarily repeating the map alias; for example, field user returns assigned_to.

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"}Value is absent; an explicit empty string is allowed and may become SQL null for datetime/JSON fields.
{"error":"missing or invalid field"}Field is not an exact map key.
{"error":"missing or invalid parameter: id/ids"}Neither target parameter is present.
{"ok":"1","warning":"no change required"}No active row was found or every raw value already strictly equals val.

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

Behaviour and edge cases

  • Initial selection excludes soft-deleted tasks. The update applies only to active IDs returned by that selection and refreshes last_edited for changed rows.
  • One value is applied to the whole batch. There is no pagination, per-row result, user/customer/type lookup, or status/privacy allowlist.
  • JSON subpaths such as metaPreviousUser are updated row-by-row; ordinary fields are updated in one batch query.

Side effects

  • Invalidates the task cache and writes one generic task history event naming the map key, value, and changed IDs.
  • Does not create mention notices, assignment email, or generic notification-service events.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found.

CRM2

CRM2’s shared inline autosave and modal table machinery can derive Task_updateField from the Task prefix. Full Task layout saves use Task_updateData.

Related endpoints