Fieldmotion API Getting started

Forms

Set a form’s stock flag

POST /a/Form_setUsesStock

Change the form-level stock hint used by job cost interfaces.

When to use this endpoint

Change the form-level stock hint used by job cost interfaces. This does not add stock, move inventory or rewrite existing job stock usage.

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

Example request

$result = FM_api('Form_setUsesStock', [
	'id' => '1042',
	'val' => '0',
]);

Example response

{
  "ok": 1,
  "sql": "update user1088_forms set uses_stock=\"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 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 0/1. This flag is distinct from the form metadata do_not_update_stock_levels control; the latter is not changed here.
  • 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.uses_stock and last_edited, invalidates forms cache, records attributed form/uses_stock, 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 Stock cell. Filter Network for Form_setUsesStock; the caller sends val.

CRM2

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

Related endpoints