When to use this endpoint

Use this for the CRM2 catalogue table. Unlike Stock_getDT it returns named mapped fields, not positional cells.

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
fieldsNative arrayYesMapped names: id,name,averageCost (alias cost),cDate,ownerID,inStock,categories,categoryIDS,lastEdited,code,isArchived,amtTrigger,description,supplierID,price,notes,nominalCode,taxRate,meta,editedUUID,priceBands. Metadata projections: metaManufacturer,metaBarcode,metaManufacturerPartNo,metaSupplierPartNo,metaSuppliers,metaUnit,metaTaxRateID,metaNominalCodeID,metaNominalID,metaNominalName,customValues,metaReferrenceType. taxType is a composite picker with id,taxRate,nominalID,nominalName,nominalCode. Preserve the misspelling metaReferrenceType. Special computed fields: suppliers,allocated,container.
isTable / start / length / drawInteger-compatibleNoisTable defaults 1; start=0,length=10,draw=0. Table mode returns data/draw/recordsTotal/recordsFiltered. isTable=0 returns data only; limit>0 can cap that non-table result.
orderBy / orderDescMapped field / directionNoPaired explicit field/direction or DataTables order[0].column/dir. DataTables column is offset by one before resolving a selected field. Use trusted asc/desc; main.id ascending provides a stable tie-breaker.
searchField / searchValueField(s) / textNoMapped substring search; omitted searchField searches All. searchField=metaUnit translates pcs/length/weight to 0/1/2 and an unknown nonblank label matches nothing.
categoryIDSScalar/native listNoOR membership via JSON_SEARCH; handled specially before mapped filters. Use the numeric selections sent by the UI, not arbitrary SQL text.
suppliersPositive integer or native listNoPositive numeric scalar/native ID list. Filters stock_suppliers through EXISTS, avoiding duplicate rows/counts.
locationTagsFilter / batchTextNoLocation searches stored meta.location_tags text. batch joins undeleted stock_inventories by reference substring.
hasFilesNative selection listNoNative selection list: 0 has current file; 1 no current file; both means unrestricted. Uses undeleted file type 20.
Mapped filters / advanceSearchMapped values / native filter structuresNoKnown mapped scalar text filters use contains matching; numeric filters use the shared numeric coercion and native lists form membership filters. No implicit isArchived=0. advanceSearch is a native list, for example [{id:stock_categoryIDS,condition:equal,value:""}]. Conditions: equal,contains,notEqual,greaterThan,greaterThanOrEqual,lesserThan,lesserThanOrEqual. Raw where rules are rejected.

Example request

$result = FM_api('Stocks_getDataTable', ['fields'=>['id','name','inStock','allocated'], 'start'=>'0', 'length'=>'25', 'draw'=>'1', 'isArchived'=>'0']);

Example response

{
  "data": [],
  "draw": 1,
  "recordsTotal": "0",
  "recordsFiltered": "0"
}

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: suppliers"}A supplier ID is not a positive digit string/integer.
{"error":"invalid advanced search"}Raw advanceSearch SQL is rejected.
{"error":"invalid stored location tags"}Projected metadata contains an unsupported 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

  • container begins with {id:0,type:0,qty:warehouseQuantity}, followed by {id,type,qty} allocation entries. allocated is the floating-point sum of the non-outbound allocations, excluding warehouse quantity. Known type-2 vehicle rows retain uuid alongside their local id.
  • Supplier link entries contain numeric id,cost,price,onHold plus name. A fallback has an empty id, item cost/price and the default supplier name, without onHold.
  • Deleted catalogue items are excluded; archives are included unless isArchived=0 is requested. recordsTotal counts all undeleted stock; recordsFiltered counts each matching stock item once. Native table paging defaults to start=0,length=10.
  • There is no account setting or schema feature check here to turn the raw quantities into reservations/available stock. The warehouse and allocated figures describe different balances.
  • Unset category choice filtering treats an empty category selection separately from zero; advanceSearch stock_categoryIDS equal empty string matches uncategorized items. metaReferrenceType=2 is No Reference and 0 is Batch, as verified by the existing unset-choice regression.
  • Allocated/container quantities remain floating-point values, including warehouse quantity. Both mapped readers exclude outbound types 14,18,20 from allocation totals. Type-2 vehicle UUID mapping retains uuid alongside the local vehicle ID when known.
  • Supplier entries use stock_suppliers values. With no explicit link, the fallback uses the default supplier’s name and item cost/price, with an empty supplier-link ID.
  • Automatically appended supporting fields are removed unless requested; id remains included. Native fields must be a nonempty list of strings. Explicit empty ID selections in Stock_getRequestedDetails return [] rather than broadening the query.
  • Supplier and batch selections use EXISTS predicates, so multiple matching links/inventories do not duplicate rows or recordsFiltered. Category OR membership predicates are grouped with other filters.
  • categoryIDS accepts positive numeric scalar/native selections; blank/empty selection means no restriction. batch/location filters must be strings. Unsafe sort directions and malformed paging/file controls return parameter errors.
  • Attachment filtering uses type_enum=20 and excludes deleted file references. Legacy location-tag lists are still presented as newline text without rewriting saved metadata.

Side effects

  • Read only; no category repair or persisted metadata normalization.

See it in Fieldmotion

CRM1

The CRM1 main Stock grid uses Stock_getDT. No direct current CRM1 caller of this mapped table was found.

CRM2

Open Stocks in CRM2. Stock layouts derive Stock_createData, Stock_updateData and Stock_getLayoutDetails through the shared helpers; the grid calls Stocks_getDataTable. Inspect the exact function name in Network requests. moduleStocks requests configured fields/filter selections for Stocks_getDataTable; its QR selection workflow uses the same filters.

Related endpoints

  • Stock_getDT — Return positional cells and DataTables counts for the CRM1 catalogue grid.
  • Stock_getRequestedDetails — Return projected stock rows with optional supplier and allocation summaries.
  • Stocks_list — Stream a bare JSON stock list with warehouse quantities and an optional field projection.