Fieldmotion API Getting started

Forms

Query the CRM2 Forms table

POST /a/Forms_getDataTable

Query selected form fields for CRM2 with mapped filtering, pagination, page permission, and an optional Workflow marker.

When to use this endpoint

Use this for the modern Forms management table or an internal field-selective query. Use Forms_list for lightweight pickers.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session and is tenant-scoped.

For CRM2 requests, the default roleCheck=1 requires view permission on pageForms. CRM1 retains legacy access. Sending roleCheck=0 skips this handler-level page check and is intended only for trusted internal callers.

Parameters

ParameterTypeRequiredDescription
fieldsNative arrayYesMapped fields to return: id, name, fieldsData, template, ownerID, lastEdited, onComplete, autodocs, type, archived, replyTo, reportType, portalVisibility, usesStock, isInvoiceable, autodocsDoc, theme, meta, emailTemplateID, departmentID, selectByDefault, cdate, phpdocxVersion, metaTags, and metaNotes. hasWorkflow is also accepted as an endpoint-computed output marker.
roleCheckBoolean-compatible integerNoDefaults to 1. Exact integer value 0 suppresses the Forms-page permission check.
metaTagsStringNoAdds a case-insensitive raw substring condition against metadata text containing a tags property; it is not a parsed exact-tag comparison.
searchField / searchValueString / stringNoShared mapped search. Special field type accepts exact labels job, job table, quote, quote table, invoice, invoice table, opportunities, opportunities table, or purchase order. Unknown non-empty labels force an empty result.
isTable / draw / start / length / limitInteger-compatibleNoShared table controls. Table mode defaults to offset 0 and length 10; exact isTable=0 returns an unwrapped data set.
orderBy / orderDesc or order[0]Mapped field / DataTables orderNoShared mapped ordering controls.
Mapped filters / referenceDate / dateFrom / dateTo / advanceSearch / groupByMixedNoShared exact, list, search, relative-date, and advanced filters. Raw advanced conditions are trusted-CRM-only.

Example request

$table = FM_api('Forms_getDataTable', [
	'fields' => ['id', 'name', 'type', 'archived', 'hasWorkflow'],
	'archived' => '0',
	'draw' => '2',
	'start' => '0',
	'length' => '25',
]);

Example response

{
  "data": [{"id": "1042", "name": "Service visit", "type": "0", "archived": "0", "hasWorkflow": 1}],
  "draw": 2,
  "recordsTotal": "54",
  "recordsFiltered": "18"
}

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":"permission denied"}A CRM2 caller lacks pageForms_view and role checking is enabled.
{"error":"missing or invalid parameter: fields"}Fields are absent.

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

Behaviour and edge cases

  • hasWorkflow is 1 only when the tenant Workflow feature is enabled and the returned form has a binding to a non-deleted workflow; otherwise it is 0. Bindings are queried once for the returned page.
  • The special type labels map to their canonical numeric types; quote table selects type 6 and purchase order selects type 5.
  • recordsTotal counts all tenant forms, while recordsFiltered applies filters. Forms have archive state rather than a soft-delete column.
  • This endpoint is read-only. Empty stored metadata is returned according to the requested mapped field without being rewritten.

See it in Fieldmotion

CRM1

No production CRM1 caller was found; CRM1 uses Forms_getDT.

CRM2

Open Settings → Forms. Layout columns, Workflow badges, filters, search, sorting, and paging use this endpoint.

Related endpoints