When to use this endpoint

Pass ids as a native list or encoded JSON; fields uses storage names rather than mapped camelCase names.

Authentication and permissions

Authenticate with a signed API key or a logged-in CRM session on the account’s routed host. API keys act as their owner; session calls require dispatcher CSRF protection where configured. IDs address the authenticated tenant.

These stock handlers do not add a Stock page-action or CRM2 role check, and the dispatcher has no Stock/Stocks TeamAccess object mapping. CRM2 screen controls are separate from this shared API contract; their roles must not be assumed to apply to CRM1.

Parameters

ParameterTypeRequiredDescription
idsNative/JSON ID listYesNative or decoded JSON ID lists are validated, then integer-converted and deduplicated, including zero/negative values. Empty lists return no ids in list; malformed JSON, scalars and unsupported list elements return controlled parameter errors.
fieldsNative/JSON field listNoAllowlist: amt_trigger,average_cost,categories,category_ids,cdate,code,description,edited_uuid,id,in_stock,is_archived,last_edited,meta,name,nominal_code,notes,owner_id,price,supplier_id,tax_rate,price_bands. Defaults to all allowed columns. Invalid fields are discarded; an explicit projection with no valid names is rejected. id is not auto-added.

Example request

$result = FM_api('Stocks_getById', ['ids'=>json_encode(['18','21']), 'fields'=>json_encode(['id','name','price'])]);

Example response

[
  {
    "id": "18",
    "name": "Valve",
    "price": "20.0000"
  }
]

Application errors can use HTTP 200. Inspect error/warning fields; database numeric values can be strings unless this handler explicitly converts them.

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 absent/null.
{"error":"no ids in list"}The decoded list is empty.
{"error":"no fields selected"}Explicit projection contains no allowed columns.

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

Behaviour and edge cases

  • Bare row array; deleted rows excluded, archived rows included. Missing IDs are omitted. No order, pagination or input-order reconstruction is applied.
  • Selected storage values retain driver types. category_ids/meta/price_bands are encoded JSON strings; no supplier expansion, category repair or computed allocation fields are added.
  • Unlike Stocks_list, supplying fields=[name] returns name only and does not force id; this distinction matters to client row mapping.
  • ids and fields must be native or decoded JSON lists with supported scalar elements. Malformed structures now return controlled parameter errors. An empty ID list retains no ids in list; empty/unknown-only fields retains no fields selected. Selected storage columns and scalar types are unchanged.

Side effects

  • Read only.

See it in Fieldmotion

CRM1

CRM1 Job bill-of-materials, quote stock pickers and requisition rows fetch selected IDs with Stocks_getById and encoded lists.

CRM2

CRM2 stock model/header cache, exports and Job bill-of-materials use Stocks_getById. Keep the requested id field when the consumer maps results back to objects.

Related endpoints

  • Stocks_list — Stream a bare JSON stock list with warehouse quantities and an optional field projection.
  • Stock_getRequestedDetails — Return projected stock rows with optional supplier and allocation summaries.
  • Stock_get — Read the full saved stock row, with selected manufacturing metadata flattened for the legacy editor.