Fieldmotion API Getting started

Tasks

Set a task subject

POST /a/Task_setSubject

Replace a task subject using the legacy <code>val</code> field and report exact no-op saves.

When to use this endpoint

Use Task_setSubject for CRM1’s focused subject editor. Use Task_updateData when mention notices and mapped audit/notification behavior are required.

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
idInteger-compatibleYesTask ID. The lookup includes deleted rows.
valStringYesReplacement subject, including an empty string if deliberately clearing it. Maximum 128 bytes.

Example request

$changed = FM_api('Task_setSubject', [
	'id' => '318',
	'val' => 'Confirm revised access details',
]);

Example response

{
  "ok": 1
}

An exact no-op returns {"ok":1,"warning":"No change made"}.

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: val"}The val parameter is absent. Blank is allowed when explicitly supplied.
{"error":"missing or invalid parameter: id"}ID is absent or below 1.
{"error":"Task does not exist"}No active or deleted task has that ID.
{"error":"Subject too long. 128 characters max"}Subject is longer than 128 bytes.

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

Behaviour and edge cases

  • Comparison is exact and case-sensitive before writing. A change refreshes last_edited.
  • The row lookup has no deletion filter, so deleted task subjects can be changed.

Side effects

  • Invalidates the task cache. It does not process @username mentions, write mapped field history, or call notifications.

See it in Fieldmotion

CRM1

Open Tasks, edit a task, and change the corresponding field. CRM1’s task dialog and Task Main page load Task_get and save changed fields through the focused Task_set* routes.

CRM2

No direct production CRM2 caller was found; mapped task layouts save subject through Task_updateData.

Related endpoints