Fieldmotion API Getting started

Files

Set one mapped file field

POST /a/File_setField

Set one mapped file field across one or more non-deleted file IDs and record a generic file audit event.

When to use this endpoint

Use File_setField for CRM2 inline switches and single-field edits. File_updateField is an equivalent wrapper around the same shared helper.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session and establish the tenant database context.

The handler performs no record-owner or resource-specific permission check. CRM screens may hide the action, but callers with tenant API/session access can target any matching file ID.

Parameters

ParameterTypeRequiredDescription
fieldStringYesMapped field name. Available names are id, filename, typeId, description, cDate, notes, ownerID, meta, name, typeEnum, lastEdited, url, customerReadable, fileLast_Edited, deleted, ddate, storageType, storageInstance, data, filesize, metaUserID, metaDateExpiry, metaTags, metaIncludeInEmail, metaEditNotesInPortal, metaShareWithSites, metaShowInPortal, metaOutsourcing, and metaLinkForm.
valMixedYesReplacement value converted according to the field map. Date values must be valid SQL dates.
id / idsInteger-compatible or native arrayYesOne file ID or multiple IDs. id takes precedence.

Example request

$result = FM_api('File_setField', [
	'id' => '4821',
	'field' => 'customerReadable',
	'val' => '1',
]);

Example response

{
  "ok": 1,
  "oldData": [{"id": "4821", "customer_readable": "0"}]
}

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: field"}Field is absent.
{"error":"missing or invalid parameter: val"}Value is absent.
{"error":"missing or invalid field"}Field is not mapped.
{"error":"missing or invalid parameter: id/ids"}Neither ID key is present.

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

Behaviour and edge cases

  • Soft-deleted rows are excluded. Missing IDs or already-equal values return {"ok":"1","warning":"no change required"}.
  • Changes set last_edited, preserve JSON siblings for metadata fields, and write one generic files audit log. They do not rebuild parent resource file lists or move storage when relationship/URL fields change.

See it in Fieldmotion

CRM1

No primary CRM1 caller was found; legacy pages use dedicated setters.

CRM2

Modern file option dialogs use this route for customerReadable and inline mapped fields.

Related endpoints