Fieldmotion API Getting started

Tasks

Create mapped task data

POST /a/Task_createData

Create a task through the mapped CRM2 contract, recording field history and dispatching configured mentions and notifications.

When to use this endpoint

Use Task_createData for CRM2 layout saves or integrations that use Task map field names. It is also the task creator used internally by embedded-form processing.

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
typeInteger-compatibleYesTask type ID. Presence is required, but 0 and unknown IDs are accepted.
customerPicker object or scalarYesCRM2 normally sends ["id"=>1042], which expands to customerID. A scalar satisfies the required-field check but does not itself populate client_id; scalar integrations should also send customerID.
customerIDInteger-compatibleConditionallyDirect stored customer ID alias. Supply it when customer is not a picker object. No customer lookup occurs.
detailsStringYesNonempty task details. Newly added @username tokens can create CRM notices.
user / userIDPicker object / integerNoAssigned user. A picker object expands its id into userID; scalar integrations should send userID as well. Defaults to the schema value 0.
subjectStringNoWhen false-like, derived from details. The wrapper enforces a 128-byte maximum; mentions are scanned in this field too.
dueDateDatetime stringNoDefaults to the current server datetime. Exact value NaN-NaN-NaN NaN:NaN:NaN is also replaced with now; other datetime strings are not format-validated.
assignedDateDatetime stringNoDefaults to the current server datetime.
status / privacyInteger-compatibleNoTask status and privacy integers. Schema defaults are both 0; the mapped helper does not enforce the UI allowlists.
resolutionStringNoResolution text; mentions are scanned when nonempty.
minutesFloat-compatibleNoStored time value; defaults to the schema value 0.
createDate / lastEditedDatetime stringNoMapped creation/edit datetimes. They default to now. Layout read-only flags are not enforced server-side; explicitly supplying lastEdited stores that value instead of appending the default current timestamp.
createdBy / appId / editedIdInteger / integer / stringNoMapped creator, mobile identity, and edit UUID fields. createdBy defaults to the acting user.
meta / customValuesString / JSON-compatible valueNoComplete stored metadata text and custom-values JSON. customValues defaults to an empty object.
metaPreviousUserInteger-compatibleNoWrites meta.previousUser; normally maintained by mapped updates rather than creation.
noRecord / noRecordCustomNative arraysNoLegacy audit-suppression controls. noRecordCustom checks custom keys normally; the create helper incorrectly compares noRecord with its final stored column name for every ordinary field, so it does not reliably hide the named map fields.

Example request

$task = FM_api('Task_createData', [
	'type' => '3',
	'customer' => '1042',
	'customerID' => '1042',
	'user' => '17',
	'userID' => '17',
	'subject' => 'Confirm access details',
	'details' => 'Confirm the site access details with the customer.',
	'dueDate' => '2026-10-02 09:30:00',
	'status' => '1',
	'privacy' => '1',
]);

Example response

{
  "ok": 1,
  "id": 318,
  "user_id": 17,
  "customer_id": 1042
}

user_id and customer_id are computed from the raw user/customer values, not read back from storage. Native picker arrays therefore coerce to legacy integer 1 in these two response fields; use id as the authoritative creation result.

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: type"}The required task type field is absent.
{"error":"missing or invalid parameter: customer"}The required customer picker field is absent, even if customerID is present.
{"error":"missing or invalid parameter: details"}Details are absent or blank.
{"error":"Subject too long. 128 characters max"}An explicitly supplied subject exceeds 128 bytes. A derived subject is truncated first.

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

Behaviour and edge cases

  • Mapped keys are type, details, resolution, userID/user, assignedDate, status, customerID/customer, createDate, lastEdited, createdBy, appId, editedId, privacy, meta, subject, dueDate, minutes, customValues, and metaPreviousUser. Unknown request keys are ignored by persistence.
  • Numeric fields are silently coerced; JSON values are encoded for storage. The endpoint does not verify referenced customer, user, or type IDs.
  • The insert is not idempotent and has no duplicate check. Every successful retry creates another task.

Side effects

  • Writes one field-history entry for each mapped value/default and invalidates the task cache.
  • For new @username tokens in subject, details, or resolution, creates a CRM notice linking to the Task Main page. Unknown names are left as text.
  • Calls the notifications service with both create and time actions. Embedded-form processing can defer these effects until its transaction commits.
  • Does not use block-task-email-notifications or the legacy assignment-mail helper used by Task_create.

See it in Fieldmotion

CRM1

No direct CRM1 source caller was found; CRM1 uses Task_create.

CRM2

Open Tasks in list, calendar, or Kanban view. CRM2’s configured Task Create/Update layouts use the mapped Task_createData, Task_getLayoutDetails, and Task_updateData routes.

Related endpoints