Fieldmotion API Getting started

Work areas and stock categories

Create a mapped stock category

POST /a/StockCategory_createData

Create a stock-category node and synchronize any supplied stock membership.

When to use this endpoint

Create the category with optional parent and initial membership. Use StockCategories_listByParent for parent choices.

Categories organize stock membership and parent/child navigation; these calls do not transfer physical stock or change quantities. Select the legacy or mapped API that matches your field names.

Authentication and permissions

Authenticate using signed API-key fields or a logged-in CRM session. All object queries use the authenticated tenant. The handler has no additional page, role or feature check unless stated below.

Sign numeric request values as strings, including nested native arrays; only JSON-encode parameters that explicitly accept JSON text. See Getting started.

Creation requires client-admin permission bit 1; lack of permission returns a JSON error.

Parameters

ParameterTypeRequiredDescription
nameStringYesTrimmed nonempty category name, maximum 80 characters; duplicate names are allowed.
parentIDNonnegative integerNo0 is root; supplied positive parent must be active and cannot be this category, a descendant or part of a cyclic ancestor chain. Creation defaults to 0; omitted updates preserve the parent.
stockCSV, JSON array text or native arrayNoReplaces the full membership. Normalizes positive integers, deduplicates and sorts numerically; empty clears membership. Every retained positive ID must identify non-deleted tenant stock.
lastEdited / noRecord / noRecordCustomIgnoredNoCannot override server timestamps or suppress checked field history.

Example request

$result = FM_api('StockCategory_createData', ['name'=>'Parts','parentID'=>'0']);

Example response

{"ok":1,"id":1042}

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: name"}Missing/blank creation name or invalid supplied update name.
{"error":"parameter too long: name. max length 80 characters"}Name exceeds 80 characters.
{"error":"stock category parent does not exist"}Positive parent is missing or deleted.
{"error":"stock category parent would create a cycle"}Changed parent would create or enter a cyclic ancestor chain.
{"error":"stock item does not exist"}Normalized membership contains a missing/deleted stock ID.
{"error":"inventory write failed"}Checked tenant persistence failed and rolled back.
{"error":"no permission to access api"}Authenticated caller is not a client admin.

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

Behaviour and edge cases

  • Requires login and client-admin permission. Uses parentID; id and unrecognized keys are ignored.
  • Initial membership is normalized, validated and synchronized with stock summaries, rather than stored as unverified text. Omitting stock uses the schema default (null).
  • Returns a checked insert ID as a JSON number. Stamps current server datetime; no name uniqueness check.
  • Tenant row changes, membership repairs and required audit writes are checked within one transaction; a failure rolls them back and returns an error. Configured events run only after commit.
  • Only non-deleted categories are read or changed. No quantity, price or accounting-provider availability check is applied.
  • The source search found no direct caller in the mobile JavaScript app or its m/www intermediary for this endpoint.
  • Post-commit event failures on event-producing writes return the committed success plus warning: saved, but a configured event failed; do not repeat creation. Review the saved record before retrying.

Side effects

  • Inserts the category and invalidates stockcategorys cache. Records checked mapped-field creation history.
  • Rebuilds affected active stock items’ category_ids as JSON text containing string IDs and categories as comma-separated names. Advances stock last_edited and sets edited_uuid to the endpoint name; invalidates stocks cache. No stock quantity movement occurs.
  • Fires configured StockCat_new handlers after commit; downstream effects depend on tenant configuration.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found for this endpoint. The legacy Stock Categories screen uses StockCategory_get and StockCategories_listByParent.

CRM2

Stock Categories → Create sends name/parentID through generic createData(table:StockCategory); filter StockCategory_createData. CRM1 uses StockCategory_add instead.

Related endpoints