Fieldmotion API Getting started

Tasks

Set a task assignee

POST /a/Task_setAssignedTo

Change or clear a task assignee, refresh assignment time, and optionally queue configured reassignment email.

When to use this endpoint

Use Task_setAssignedTo for CRM1 assignment edits and CRM2 bulk reassignment. It has assignment-mail behavior that the generic mapped update does not share.

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 does not exclude deleted rows.
assigned_toInteger-compatibleNoNew user ID. Missing input becomes 0, which clears assignment. The user is not validated.

Example request

$assigned = FM_api('Task_setAssignedTo', [
	'id' => '318',
	'assigned_to' => '22',
]);

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"}ID is absent or below 1.
{"error":"missing or invalid task"}No task row, active or deleted, has that ID.
{"error":"No valid Email"}Assignment changed to a nonzero user, reassignment notifications are enabled, but configured recipients produced no email address. The database update has already happened.

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

Behaviour and edge cases

  • When the numeric assignee is unchanged, returns success without changing timestamps or sending mail.
  • When changed, stores the new assignee and current server datetime in both assigned_date and last_edited. Setting zero is supported.
  • The handler does not verify user existence, task privacy, ownership, or deletion state.

Side effects

  • Invalidates the task cache. For a nonzero new user, enabled notification_types.task_change_user configuration can queue template/default email to configured customer, user, creator, or other recipients.
  • The block-task-email-notifications setting is not consulted here. When task-change-user configuration is disabled, reassignment queues no fallback email.

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

On Tasks, select rows and use Change User. CRM2 calls Task_setAssignedTo once per selected ID; ordinary layout saves use Task_updateData.

Related endpoints

  • Task_updateData can change user/userID but does not refresh assigned_date or call this assignment-mail helper.
  • Task_get returns the stored assignee.