Fieldmotion API Getting started

Reusable document and recurrence templates

Query reusable templates with mapped fields

POST /a/Templates_getDataTable

Query reusable templates using mapped fields and shared table filtering

When to use this endpoint

Use for named-field table rows or a filtered unpaged data wrapper. Unlike Templates_get and Templates_getDT, there is no required object-type filter: supply objType explicitly to restrict the result.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Template_get, Template_new, Template_setObj and Templates_get require an authenticated tenant context; Template_delete and both table handlers also call the login guard. There is no handler-level administrator, page, role, creator or ownership check.

Templates are shared within the authenticated tenant, not private to created_by. There is no user, department, feature-setting or active/deleted filter. The dispatcher also applies its normal account, authentication and team-access checks; the shared table predicate adds no template-specific row restriction.

Parameters

ParameterTypeRequiredDescription
fieldsRequest arrayYesMapped aliases: id, cDate, lastEdited, obj, objType, name, createdBy, objCopyUser, objCopyCustRef, objCopyJobRef, objOnArr, objSkipWeekends, objSchedule, objActive, objEvery, objNotes. Unknown fields are ignored; id is always appended, even for an empty array. Use native arrays/bracket form fields, not the JSON text required by Templates_get.
isTableIntegerNoDefault table mode; integer zero switches to unpaged mode with only data in the envelope. Does not return a bare array.
start / length / drawIntegersNoTable defaults: offset 0, length 10, draw 0. Limits are integer-converted without clamping/cap. Unpaged mode ignores these and has no count queries.
limitIntegerNoUnpaged mode only: positive row cap; default 0 means no SQL limit. Does not override table length.
objType / id / createdBy / cDate / lastEditedScalar or request arrayNoNumeric equality filters; arrays become IN lists. objType is the actual type filter here; type and obj_type are ignored. These filters need not be selected in fields.
name / obj / objCopyUser / objCopyCustRef / objCopyJobRef / objOnArr / objSkipWeekends / objSchedule / objActive / objEvery / objNotesScalar or request arrayNoMapped text filters: scalar values are trimmed/lowercased LIKE substrings, arrays use IN equality. % and _ are SQL wildcards. The obj-prefixed aliases read keys from the JSON payload (copy_user, copy_cust_ref, copy_job_ref, on_arr, skip_weekends, schedule, active, every, notes).
orderBy / orderDescStringsNoTable mode: supply both to sort a mapped alias (case-insensitive fallback). Use asc/desc for direction. Otherwise order[0][column] is interpreted as selected-field index minus one, clamped to zero, with exact desc selecting descending. Default is first valid selected field ascending, falling back to id. No ID tiebreaker.
searchValue / searchFieldString / scalar or request arrayNoNonblank searchValue adds a trimmed/lowercased LIKE substring search across selected searchField aliases, default All (all mapped fields, not just projected fields). Unknown search fields contribute no predicate. Search predicates are OR-combined, then AND-combined with other filters. % and _ retain wildcard meaning.
groupByRequest arrayNoMapped aliases for SQL grouping; this does not add aggregate projections or change count queries to group counts.
advanceSearch / referenceDate / dateFrom / dateTo / timeRangeFrom / timeRangeTo / offsetFrom / offsetToUnsupported query controlsDo not sendA non-null supplied control returns Unsupported template filter: followed by its name before any data query. These generic controls previously ignored clauses or treated bigint timestamps incorrectly. Use explicit mapped field filters instead; no replacement date-range syntax is implied.

Example request

$table = FM_api('Templates_getDataTable', [
	'fields' => ['id', 'name', 'objType'],
	'objType' => '3',
	'draw' => '1',
	'start' => '0',
	'length' => '10',
]);

Example response

{"data":[{"id":"1042","name":"Standard quote","objType":"3"}],"draw":1,"recordsTotal":"6","recordsFiltered":"1"}

Returns named rows under data. Counts are database scalars (often strings); recordsTotal counts all tenant templates, not only the supplied objType; recordsFiltered applies request filters. No matches means data=[]. obj stays encoded JSON, and extracted obj keys use SQL JSON unquoting rather than server-side object decoding. cDate/lastEdited remain raw bigint Unix seconds.

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: fields"}fields missing/null; a string instead of an array is not a supported replacement.
{"error":"Unsupported template filter: referenceDate"}Any unsupported query control was supplied; the suffix identifies the first rejected control.
{"error":"error in database query"}The shared row query returns false, including incompatible legacy filters.

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

Behaviour and edge cases

  • All supplied mapped filters combine with AND; there is no type restriction unless objType is sent. Supplying a native empty fields array still selects id. No deleted, owner or department filter is added for templates.
  • Table mode always returns counts; unpaged mode returns only data and has no guaranteed ordering. SQL grouping does not change count queries to distinct-group counts. Neither mode imposes an application-level maximum.
  • No direct mobile-app or m-service caller for this template family was found in the source search. The CRM2 widget’s payload is client-defined; storing it does not validate that another document endpoint will accept every field.

Side effects

  • Reads rows/counts only. No preset application, cache write, message or document mutation is invoked.

See it in Fieldmotion

CRM1

No direct production CRM1 caller for Templates_getDataTable was found. Its recurrence-template settings table uses Templates_getDT instead.

CRM2

No direct production CRM2 caller for Templates_getDataTable was found. The template widget and recurrence picker use Templates_get. The endpoint API test exercises mapped id/name/objType fields, not a production table screen.

Related endpoints