Fieldmotion API Getting started

Tasks

Set task details

POST /a/Task_setDetails

Replace task details using the legacy <code>val</code> parameter, with explicit no-change reporting.

When to use this endpoint

Use Task_setDetails for CRM1’s focused details editor. Pay particular attention to its parameter name: it does not read a parameter named details.

Authentication and permissions

The request must establish an authenticated tenant context with signed API credentials or a logged-in CRM session. The handler checks for the tenant database prefix rather than calling the normal login guard.

It performs no additional task, page, role, ownership, or privacy-permission check. A caller that knows an active task ID in its tenant can address it regardless of the CRM screens’ visibility rules.

Parameters

ParameterTypeRequiredDescription
idInteger-compatibleYesTask ID. The lookup includes deleted rows.
valStringNoReplacement details; defaults to an empty string when omitted. There is no length or nonempty validation.

Example request

$changed = FM_api('Task_setDetails', [
	'id' => '318',
	'val' => 'Confirm the revised site access details.',
]);

Example response

{
  "ok": 1
}

If the stored text already matches, the response is {"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.
["invalid or missing parameter: id"]ID is absent or below 1. This endpoint’s legacy error is an unkeyed JSON array rather than an error object.
{"error":"Task does not exist"}No task row, active or deleted, has that ID.

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

Behaviour and edge cases

  • On change, replaces details and refreshes last_edited. It does not exclude deleted rows.
  • Comparison is exact and case-sensitive under PHP before the write.

Side effects

  • Invalidates the task cache. It does not create mention notices, generic field history, or notification-service events.

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. CRM2 saves details through Task_updateData, which does process mentions and notifications.

Related endpoints