Fieldmotion API Getting started

Forms

Retrieve forms by ID

POST /a/Forms_getById

Fetch selected local or authorised outsourced form definitions, optionally limiting returned columns.

When to use this endpoint

Use this after another call supplies form IDs, especially before rendering/editing questions, exporting form definitions, or resolving linked tables.

Authentication and permissions

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

The handler performs no form, department, owner, or page-permission check unless the page below says otherwise. CRM navigation may impose additional UI-only access rules.

Parameters

ParameterTypeRequiredDescription
idsNative array or JSON array stringYesLocal integer-compatible IDs and/or outsourced tokens shaped o<sourceTenantId>i<formId>. An empty effective list is rejected.
fieldsNative array or JSON array stringNoOptional raw-column allowlist: id, name, fields, template, owner_id, last_edited, on_complete, autodocs, type, archived, replyto, report_type, portal_visibility, uses_stock, is_invoiceable, autodocs_doc, meta, email_template_id, department_id, select_by_default, cdate, and phpdocx_version. Legacy preferred_type selects report_type.

Example request

$forms = FM_api('Forms_getById', [
	'ids' => ['1042', 'o815i77'],
	'fields' => ['id', 'name', 'fields', 'type'],
]);

Example response

[
  {"id": "1042", "name": "Service visit", "fields": "[{...}]", "type": "0"},
  {"id": "o815i77", "name": "Partner checklist", "fields": "[{...}]", "type": "0"}
]

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: ids"}IDs are absent.
{"error":"no ids in list"}No local or syntactically valid outsourced IDs remain.
{"error":"no fields selected"}A fields list was supplied but contains no allowed names.

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

Behaviour and edge cases

  • Missing local rows and inaccessible outsourced rows are silently omitted. Archived forms are not excluded.
  • An outsourced tenant is queried only when the global user_links table has an active link from that source tenant to the authenticated tenant. Returned outsourced IDs retain the composite token.
  • Local and outsourced groups are queried separately. No stable ordering matching the input list is promised.
  • Stored JSON columns such as fields, meta, and on_complete remain encoded strings.

See it in Fieldmotion

CRM1

Form editors, Quote screens, exports, and bill-of-materials widgets retrieve selected definitions through this endpoint.

CRM2

The Forms page, Form editor, Quote module, exports, and bill-of-materials widget use it.

Related endpoints