Fieldmotion API Getting started

Forms

Archive or reactivate a form

POST /a/Form_setArchived

Hide or restore a form in workflows that filter archived forms.

When to use this endpoint

Hide or restore a form in workflows that filter archived forms. This changes the archive flag; it does not delete the definition or its recorded jobs.

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.
valScalar valueYesNon-null value for archived. No trimming or allowed-value validation; zero and blank are accepted. Use 0 or 1 in ordinary clients.

Example request

$result = FM_api('Form_setArchived', [
	'id' => '1042',
	'val' => '1',
]);

Example response

{
  "ok": 1
}

The changed response is ok=1. An unchanged flag adds the warning described below.

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 provided"}The ID is absent or false-like.
{"error":"no val provided"}val 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

  • Normal values are 1=archived and 0=active. Archiving is reversible. It does not establish a universal read-access restriction: Form_get and the other direct detail helpers can still return archived definitions.
  • 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 supplied value is written as quoted text without a boolean/bitmask allowlist. Normal clients send the values described below; arbitrary non-null text is not validated by this handler. The database column’s conversion/range rules still apply.
  • An unchanged value returns {"ok":1,"warning":"value already set"} 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.archived and last_edited, invalidates forms cache, records attributed form/archived, 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 Archived cell. Filter Network for Form_setArchived; the caller sends val. Bulk archive and table-merge paths also use this endpoint.

CRM2

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

Related endpoints