When to use this endpoint

Use the legacy grid’s filter names; select Stocks_getDataTable for named camelCase projections.

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
draw / start / length / orderDataTables valuesYesAll four must be present (order may be an empty native array). start/length integer-convert directly; no handler page-size maximum or negative-range normalization.
order[0][column] / dirNative sort controlsNoSort indices: 0 ID,1 name,2 code,3 description,7 supplier,8 cost,9 price,10 nominal,11 tax,12 in_stock. Others sort name. Only dir exactly asc is ascending; every other value chooses descending.
search[value]TextNoGlobal substring across name,id,supplier,categories,description,meta,code.
fId / fCategoryInteger-compatibleNoTruthy item ID exact match; nonzero category ID tests the encoded category_ids string.
fName / fDescription / fNotes / fCode / fSupplier / fLocationTextNoTrimmed/lowercased contains filters; location matches whole stock.meta text, not only location tags.
fIsTriggeredInteger-compatibleNoNonzero filters in_stock against the numeric threshold before the |email separator in amt_trigger.
fIsArchivedInteger-compatibleNoZero/omission selects unarchived; nonzero selects archived. Both exclude deleted stock.

Example request

$result = FM_api('Stock_getDT', ['draw'=>'1', 'start'=>'0', 'length'=>'25', 'order'=>[['column'=>'1','dir'=>'asc']], 'fIsArchived'=>'0']);

Example response

{
  "draw": 1,
  "recordsTotal": 1,
  "recordsFiltered": 1,
  "data": [
    [
      18,
      "Valve",
      "VALVE-1",
      "Replacement valve",
      "",
      [
        0,
        null
      ],
      12.5,
      20,
      "4000",
      20,
      8,
      2.5,
      "5|stock@example.test",
      0,
      [
        "Heating",
        {
          "Heating": {
            "name": "Heating"
          }
        }
      ],
      "Cabinet A",
      ""
    ]
  ]
}

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: draw"}Required DataTables control is absent/null.
{"error":"missing or invalid parameter: length"}Required DataTables control is absent/null.
{"error":"missing or invalid parameter: order"}Required DataTables control is absent/null.
{"error":"missing or invalid parameter: start"}Required DataTables control is absent/null.
{"error":"invalid stored location tags"}A selected item has an unsupported saved tag shape.

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

Behaviour and edge cases

  • data rows contain 17 cells, in order: ID,name,code,description,notes,[supplierID,supplierName],average_cost,price,nominal_code,tax_rate,in_stock,allocated,amt_trigger,is_archived,[saved categories,category rows keyed by category name],location tags,empty action cell.
  • ID/supplierID/archive are integer-converted; cost/price/tax/warehouse/allocated are float-converted. Supplier is a left join to undeleted suppliers. Allocated is SUM(amt) over every container type, including outbound types.
  • recordsTotal counts all undeleted stock including archives. recordsFiltered includes filters and the selected archive state. Category rows come from undeleted category IDs and are keyed by name, for example {Heating:{name:Heating}}; duplicate category names collapse to one keyed entry and order is unspecified. No categories produces an empty list.
  • Location tags accept saved string or legacy list (presented as newline text), with invalid shapes returning an error. This display conversion does not write metadata.
  • Sort-column indices reflect legacy table controls and do not match the packed response-cell indices for later columns. Use the explicit mapping above rather than assuming array index equals sort index.
  • The triggered filter compares in_stock against the numeric threshold before the |email separator. Existing archive selection, float balances, sort-index mapping and legacy unbounded paging contract are otherwise retained.

Side effects

  • Reads only; unlike Stock_get, does not repair category data.

See it in Fieldmotion

CRM1

Open Stock in CRM1. The legacy grid is Stock_getDT and its editor/inline actions use legacy Stock routes. Inspect the exact function name in the browser Network panel. Open Stock and apply archive/category/minimum-level filters. The browser sends the f-prefixed controls and expects 17 positional cells.

CRM2

The CRM2 main catalogue uses Stocks_getDataTable; no direct current CRM2 Stock_getDT caller was found.

Related endpoints

  • Stocks_getDataTable — Return named stock rows with mapped filters, paging and optional supplier/allocation summaries.
  • Stock_get — Read the full saved stock row, with selected manufacturing metadata flattened for the legacy editor.
  • Stock_getRequestedDetails — Return projected stock rows with optional supplier and allocation summaries.