Fieldmotion API Getting started

Display-layout groups

Create a display-layout header

POST /a/LayoutGroup_createData

Create a display-layout header before adding its field tree

When to use this endpoint

Create a named layout or table-list configuration for a mapped object type. This stores the group/header only: field positions, cards, tabs and custom-field definitions are saved separately through Layouts_saveField. Use LayoutGroup_copy when starting from another complete field tree.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Mutations require the client-administrator bit checked by Core_isClientAdmin (including the tenant-owner fallback), not merely access to the Display Layout Dashboard screen. The handlers also require login; create/update/delete check administrator status before their login guard, while copy checks login first.

Groups belong to the authenticated tenant. No per-group ownership, userID, department or page-role restriction is added. userID is a stored field, not an authorization boundary. No tenant feature toggle is consulted by these handlers.

Parameters

ParameterTypeRequiredDescription
name / tableNameStringsFor createGroup name and main-table map key (for example customer). Creation requires non-null, nonempty strings, but does not trim whitespace; update validates a supplied empty value, not omitted fields. No table-key allowlist, uniqueness check or explicit length bound is configured in the map, although the representative schema has 100-character columns.
userIDIntegerNoInteger-converted stored user_id; defaults to 0 on creation. Not automatically set to the acting user and not used to restrict getList.
metaModalSize / metaTypeText valuesNoIndividual keys modalSize and type within meta. CRM2 uses modal-lg or modal-xl and type 0 (Layout) or 1 (Table List); the server does not allowlist these values. Keys are merged into the stored metadata object rather than replacing the other keys.
metaJSON object or JSON textNoWhole metadata column, not a merge. A request array/object is serialized; when sending text, supply valid encoded JSON. No metadata schema validation is performed. Map order matters when combined with individual keys: metaModalSize runs before whole meta and can be overwritten; metaType runs after it. Prefer one complete meta object or individual keys, not a mixture.
createdate / lastEditedUnix seconds or parseable datetimeNoMapped timestamp fields. Creation defaults both to now; numeric values are used directly and nonnumeric datetime strings use PHP server-timezone parsing. Blank maps to 0. Readonly map labels are UI hints, not write protection. A changed updateData/updateField stamps last_edited automatically; do not use lastEdited as a concurrency token.

Example request

$group = FM_api('LayoutGroup_createData', [
	'name' => 'Customer details',
	'tableName' => 'customer',
	'metaModalSize' => 'modal-lg',
	'metaType' => '0',
]);

Example response

{"ok":1,"id":1042,"cdate":"2026-10-24"}

id is the insert-helper result. cdate is a newly formatted PHP server-date string (Y-m-d), not the stored Unix timestamp and not the timestamp shape returned by copy.

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":"you are not an admin"}Acting user lacks client-administrator status.
{"error":"Unable to complete layout group operation. Check the saved state before retrying."}A transaction/read/write/commit failure prevents confirmed completion; inspect saved state before retrying an uncertain response.
{"error":"missing or invalid parameter: name"}Required name missing/null/empty.
{"error":"missing or invalid parameter: tableName"}Required main-table key missing/null/empty.
{"error":"Unable to create record"}Insert fails or returns no positive ID.

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

Behaviour and edge cases

  • Unknown request keys and a supplied id are ignored by creation. Duplicate names, arbitrary tableName values and whitespace-only required text are not explicitly rejected. The map does not verify that the chosen main table has supported fields.
  • There is no group assignment to a screen/default setting, automatic layout tree, email or background conversion. Existing page/default selectors are configured independently. Optional null parameters are treated as absent.
  • No direct mobile-app or m-service caller for this family was found. These groups configure CRM display layouts; they are not reusable document presets, form definitions, or a tenant-wide change to existing business-object data.

Side effects

  • Inserts the tenant layout_groups row, requests its cache invalidation and writes Core_log entries for supplied/defaulted mapped fields. No Undo snapshot is created for this table. The row write and history writes are not wrapped in a transaction by this handler.

See it in Fieldmotion

CRM1

No production CRM1 caller for this layout-group family was found in client source. The administration workflow described here is CRM2; API tests and fixture setup are not evidence of a CRM1 screen.

CRM2

Open CRM2 Settings → Display Layout Dashboard (pageSettingsDisplayLayouts). Its create/edit/delete helpers resolve the layoutGroup map to the corresponding LayoutGroup route; filter browser developer tools for that exact function name. Screen visibility is not a substitute for the API administrator check. Click Create, choose name/main table/modal size/type and save; the request sends name, tableName, metaModalSize and metaType. The client adds a dashboard card from the returned ID/date.

Related endpoints