Fieldmotion API Getting started

Work areas and stock categories

Retrieve selected raw categories

POST /a/StockCategories_getById

Fetch stored category projections for a known batch of IDs.

When to use this endpoint

StockCategories_list can discover category IDs; this call then fetches only the records needed by an exporter or integration.

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
idsNative array or JSON array textYesInteger-converted and deduplicated; at least one member required. Invalid JSON/non-array/empty list produces no ids in list.
fieldsNative array or JSON array textNoAllowed stored fields: id, name, parent_id, stock, last_edited. Unknown fields are ignored; a supplied list with no valid selections returns an error. Omission selects all allowed fields.

Example request

$result = FM_api('StockCategories_getById', ['ids'=>json_encode(['1042']), 'fields'=>json_encode(['id','name'])]);

Example response

[{"id":"1042","name":"Parts"}]

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: ids"}IDs omitted.
{"error":"no ids in list"}Empty/invalid decoded ID list.
{"error":"no fields selected"}No allowed field remains.

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

Behaviour and edge cases

  • Default fields include all raw columns. Unknown fields ignored, duplicates removed; selected fields need not include id.
  • No ordering/pagination; missing IDs omitted, repeated IDs do not duplicate rows. Uses parent_id rather than mapped parentID.
  • Unlike Locations_getById, an empty ID list is an error. Malformed fields are not robustly validated; send a well-formed array.
  • 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

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

CRM2

No direct CRM2 caller was found for this endpoint. CRM2 Stock Categories uses mapped StockCategory_getRequestedDetails reads and generic create/update/delete helpers.

Related endpoints