Save form tags · Fieldmotion API

When to use this endpoint

Use for the Forms table’s tag editor. Labels are stored as text (the CRM1 editor uses one tag per line), not as a normalized relation or request array.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. The signed key acts as its associated tenant user.

Existing-definition settings writes require Forms Edit (pageForms_edit); client administrators pass the standard permission helper. Roleless/non-edit users fail closed. Temporary setup accounts retain their provisioned Forms Edit permission; the metadata marker alone does not grant that permission.

The account features2.disableFormEdits=1 setting blocks definition writes, except temporary setup users. Writes stay in the authenticated tenant; they do not modify an outsourced source definition.

Parameters

Parameter	Type	Required	Description
`id`	Integer-compatible form ID	Yes	Positive integer-converted ID of an existing local form; the row is locked for saving.
`val`	String	No	Optional HTML-escaped tag text. Omitted/null val leaves existing tags unchanged. Explicit empty text clears tags; literal string 0 is saved as text. No splitting, trimming or deduplication.

Example request

$result = FM_api('Form_setTags', ['id'=>'1042', 'val'=>"Safety\nAnnual service"]);

Example response

{"ok":1}

Errors and unusual responses

Response	Condition
`{"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 missing/null or below 1 after conversion.
`{"error":"form edits are disabled for this account"}`	Account definition edits disabled; temporary setup users bypass the feature.
`{"error":"permission denied"}`	The actor lacks Forms Edit. Client administrators pass the standard permission helper; the temporary marker alone grants no access.
`{"error":"Unable to save form settings. Check the saved state before retrying."}`	A read, primary write, history, undo or transaction acknowledgement failed; do not replay an uncertain save without refreshing.
`{"error":"form does not exist"}`	No selected local form.
`{"error":"Form metadata is invalid. Repair it before saving."}`	Nonempty metadata cannot be safely decoded.

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

Behaviour and edge cases

Explicit changed text, including empty text or 0, updates meta.tags and last_edited, preserving all other metadata keys. An omitted/null val or unchanged value returns ok without writes/history/undo.
Legacy null/empty metadata is initialized when storing a changed value. Invalid nonempty JSON is rejected without discarding it. The target form must exist, including when val is omitted.
Data, attributed history and an after-change undo snapshot are checked and committed together, using a savepoint inside caller-owned transactions. Any data/history/undo failure rolls back the change. Forms cache invalidation is requested for a change.
Stored HTML entities are returned unchanged by Form_getTags. Tags remain text; no tag relation, email, mention notice or inventory action is created.
No direct mobile app/m-service caller for this RPC was found. Changed tags now update the edit timestamp used by incremental form downloads.

Side effects

On a change, updates metadata and last_edited, requests forms cache invalidation, and atomically records history and an after-change undo snapshot. Omitted/null or unchanged values have no write effects.

See it in Fieldmotion

CRM1

Forms → Tags opens Form_getTags, then sends textarea contents to Form_setTags on change. One tag per line is a client convention.

CRM2

No direct Form_setTags caller found. Forms uses mapped metaTags editing through the shared editor.

Related endpoints

Form_getTags reads stored tag text.
Form_setNotes updates a separate metadata path.