Fieldmotion API Getting started

Forms

Read one form definition

POST /a/Form_get

Fetch a stored local form or a linked outsourcer’s restricted definition.

When to use this endpoint

Use when a form editor or report designer needs one complete definition. Forms_getById is the batch alternative and supports an explicit raw-column allowlist.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. No handler-level Forms page, owner, type, archive or department restriction is applied.

For an outsourced id token, the global user_links table must contain status=1, link_from=source tenant and link_to=authenticated tenant. That branch explicitly routes its form query to the source tenant; ordinary IDs stay in the authenticated tenant.

Parameters

ParameterTypeRequiredDescription
idLocal integer-compatible ID or outsourced tokenYesRequired/non-null. Local values integer-convert (blank becomes zero); outsourced syntax is o<sourceTenantId>i<formId>. The source code permits empty digit groups in that expression, but normal callers must supply both positive IDs.

Example request

$form = FM_api('Form_get', ['id'=>'o1088i1042']);

Example response

{
  "id": 1042,
  "name": "Partner service checklist",
  "fields": "[]",
  "autodocs": "[]",
  "type": "0",
  "archived": "0"
}

The example is the outsourced branch’s complete six-column shape: id, name, fields, autodocs, type and archived. id is replaced with the integer form ID, so the source-tenant token is lost in the reply; retain it in your caller.

Local reads select every stored forms column, including template, owner_id, last_edited, on_complete, replyto, report_type, portal_visibility, uses_stock, is_invoiceable, autodocs_doc, meta, email_template_id, department_id, select_by_default, cdate and phpdocx_version (and any deployment-specific columns). This is raw storage, not mapped camelCase aliases. Stored JSON remains encoded text; nullable columns remain null.

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: id"}id absent/null.
{"error":"you do not have access to that outsourcer"}No active incoming link from the token’s source tenant.
{"error":"form does not exist"}No selected row, or lookup failure.

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

Behaviour and edge cases

  • Returns a single object, never a one-element list. Archived forms are included. There is no fields projection, paging, sorting, enrichment or URL fetch.
  • Local id is integer-converted and returned as an integer. Outsourced replies also overwrite id with an integer, unlike Forms_getById which retains composite identity.
  • The query reads stored fields and does not normalize malformed JSON, repair parent links, resolve Job Table definitions or migrate a form.
  • No direct mobile app/m-service caller for this RPC was found. Mobile form definitions arrive through m’s syncDownloads form channel, not this endpoint.

Side effects

  • Read-only; no history, cache invalidation, file write, URL fetch or report rendering.

See it in Fieldmotion

CRM1

Open Form Edit or a Report PDF/Document editor and filter Network for Form_get. On Complete editors and table-merge workflows also fetch definitions through it.

CRM2

Open Form Edit, On Complete or Report Document editing. Filter for Form_get; related cached/batch lookups also use Forms_getById.

Related endpoints