Fieldmotion API Getting started

Tasks

Import task rows

POST /a/Tasks_import

Create or destructively overwrite tasks from positional import rows and create missing task types by name.

When to use this endpoint

Use Tasks_import only through the CRM import widgets, which build aligned map and rows JSON. Prefer mapped create/update endpoints for ordinary integrations.

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 rows come from the authenticated tenant. Unless the page says otherwise, IDs, creator, assignee, and privacy do not restrict the result at handler level.

Parameters

ParameterTypeRequiredDescription
mapJSON array stringYesColumn descriptors aligned by index with each row. The implementation reads only each descriptor’s to. Recognized destinations are id, assigned_to, assigned_date, cdate, client_id, created_by, details, due_date, notes, privacy, resolution, status, subject, and type.
rowsJSON array-of-arrays stringYesImport rows whose positions match map. Presence is checked, but successful JSON decoding and row shapes are not validated before iteration.
filenameStringNoNonblank source filename stored as JSON metadata on the import-log row.

Example request

$result = FM_api('Tasks_import', [
	'filename' => 'tasks.csv',
	'map' => json_encode([
		['to' => 'subject'],
		['to' => 'type'],
		['to' => 'client_id'],
		['to' => 'details'],
		['to' => 'due_date'],
	]),
	'rows' => json_encode([
		['Confirm access details', 'Customer follow-up', '1042', 'Confirm the site access details.', '2026-10-02 09:30:00'],
	]),
]);

Example response

{
  "ok": 1,
  "errors": []
}

Per-row errors are pairs containing the zero-based row index and an array of {"msg":...,"val":...} objects. Successful created/edited IDs are not returned.

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: map"}map is absent.
{"error":"missing or invalid parameter: rows"}rows is absent.
Runtime error rather than a row errorMalformed JSON/row shapes or an invalid date reaches unchecked array iteration or DateTime construction.
{"ok":1,"errors":[[0,[...]]]}A row cannot create its task/type or overwrite the requested task ID. Other rows continue.

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

Behaviour and edge cases

  • A missing/zero ID creates through Task_create, then immediately calls Task_edit. Creation requires customer and nonblank details. Existing IDs are not scoped by deleted state, so a known soft-deleted row can be overwritten without restoring it.
  • Type text is looked up by exact stored name. A missing name creates a new task type through TaskType_new; duplicates and races are not prevented.
  • Status text recognizes New, Open, Closed, and the exact legacy import token Archive. The exported/displayed value Archived is not recognized and silently becomes status 0 (New), as does any unknown status.
  • cdate and created_by are ignored. notes is collected but neither task create nor edit stores it. Existing-task subject and imported assigned date are also not updated by Task_edit.
  • There is no transaction or batch-size limit. A generated import ID identifies one imports_log row with created/edited counts and import type 9.

Side effects

  • Creates or overwrites task rows and invalidates task caches. These legacy writes do not create mapped field-history entries.
  • New task creation can send the configured assignment email unless block-task-email-notifications is enabled; the later overwrite does not send another.
  • Can permanently create task-type rows and always writes an import-log record, including when row errors occur.

See it in Fieldmotion

CRM1

Open Tasks and choose Import. CRM1’s import widget builds these map/row JSON values and refreshes the table after completion.

CRM2

Choose Import from the Tasks module. CRM2 uses the same endpoint and includes v=2, which this handler ignores.

Related endpoints