Fieldmotion API Getting started

Work areas and stock categories

Load a nested category subtree

POST /a/StockCategories_listByParent

Build the nested category tree consumed by legacy stock pickers and tree controls.

When to use this endpoint

StockCategory_get retrieves a selected node’s CSV membership after the tree has supplied its numeric ID.

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.

Parameters

ParameterTypeRequiredDescription
idInteger-compatibleNoParent ID to enumerate, default 0 for roots. The parent itself is excluded; every descendant is loaded recursively.

Example request

$result = FM_api('StockCategories_listByParent', ['id'=>'0']);

Example response

[{"id":1042,"text":"Parts","state":{"opened":false},"children":[]}]

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: id"}Supplied parent is not a nonnegative integer.
{"error":"inventory read failed"}Active-tree query failed.

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

Behaviour and edge cases

  • Each node has numeric id, text=name, state.opened=false and recursively populated children. Leaves/no children return [].
  • Loads the active category collection once, ordered by parent_id, name and id, then builds the requested subtree in memory; no pagination.
  • Tracks IDs along each recursion path and skips edges back to already visited nodes. Existing cyclic data therefore terminates; cycles unreachable from the requested parent remain absent.
  • Missing parent IDs return [] unless active rows refer to that ID; parent existence itself is not checked.
  • 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.

Side effects

  • Read-only; no object writes, audit entries or notifications are performed.

See it in Fieldmotion

CRM1

Stock Categories tree and stock pickers in Quotes, Invoices, Purchase Orders and Form Edit load StockCategories_listByParent. Filter that name while opening a picker.

CRM2

Form Edit’s stock-category selection uses StockCategories_listByParent; the standalone CRM2 category page instead builds its tree from mapped detail rows.

Related endpoints