Fieldmotion API Getting started

Forms

Assign a form department

POST /a/Form_setDepartment

Change the form’s stored department association.

When to use this endpoint

Change the form’s stored department association. Use a department ID obtained from an account lookup, or zero to remove the association.

Use a form ID supplied by the Forms list. Read the current definition before making a narrowly scoped change; this endpoint does not save questions, report templates or existing job answers.

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

ParameterTypeRequiredDescription
idInteger-compatible form IDYesRequired and truthy before integer conversion. Missing/null/blank/zero gives the ID error; a truthy malformed value can convert to zero and then fail the row lookup.
department_idInteger-compatible valueYesNon-null value for department_id. Integer-converted; zero is accepted. Zero removes the association.

Example request

$result = FM_api('Form_setDepartment', [
	'id' => '1042',
	'department_id' => '0',
]);

Example response

{
  "ok": 1,
  "sql": "update user1088_forms set department_id=0, last_edited=\"2026-11-02 14:30:00\" where id=1042"
}

A changed reply includes the executed SQL string, with the authenticated tenant prefix and server-generated timestamp. The example uses placeholder tenant 1088. A no-op omits sql.

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":"form edits are disabled for this account"}Account disableFormEdits is 1 and the actor is not a temporary setup user.
{"error":"no id parameter"}The ID is absent or false-like.
{"error":"no department_id parameter"}department_id is absent/null.
{"error":"form does not exist"}No row for the integer-converted ID, or the initial lookup fails.
{"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.

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 zero department ID clears the association. The endpoint does not verify that a positive department exists or synchronize a department membership list.
  • Requires an existing local form, including an archived one. There is no form-type restriction, active/deleted filter, owner check or automatic migration of saved job answers.
  • The value is integer-converted without an allowlist or linked-record validation. Negative/nonstandard integers are not rejected. Equality uses the stored column converted to an integer.
  • An unchanged value returns {"ok":1,"warning":"no change needed"} before update, history or undo creation.
  • On change, locks the existing row and saves the setting, last_edited, attributed history and an after-change undo snapshot in one checked tenant transaction. Nested callers retain their transaction through a savepoint. Failed data/history/undo operations roll back; uncertain commits are not automatically replayed.
  • No direct mobile app/m-service caller for this RPC was found. Mobile form definitions are downloaded through m’s syncDownloads form channel rather than these CRM calls.

Side effects

  • Updates forms.department_id and last_edited, invalidates forms cache, records attributed form/department_id, inserts a full after-change row snapshot into undos, and commits all three together. A no-op skips these effects. No email, job event or inventory transaction is invoked.

See it in Fieldmotion

CRM1

Open Forms and change the Department cell. Filter Network for Form_setDepartment; the caller sends department_id.

CRM2

Forms exposes the Department setting through its mapped editor. No direct Form_setDepartment caller was found; the standard editor uses Form_updateData/Form_updateField rather than this dedicated setter.

Related endpoints