Fieldmotion API Getting started

Forms

Create a reusable form block

POST /a/FormBlock_new

Create an empty named reusable block for report documents or email templates.

When to use this endpoint

Create the block first, then populate its HTML with FormBlock_setCode and optionally upload its preview image.

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 record-owner or page-permission check. Definition writes are blocked when the tenant’s features2.disableFormEdits flag is 1, except for the temporary setup user identified by userdata.meta.is_tmp=1.

Parameters

ParameterTypeRequiredDescription
nameStringYesTrimmed name, at most 64 Unicode characters. Names are checked across both block types.
typeInteger-compatibleNoDefaults to 0 for a report form block. Use 1 for an email-template block. Values above 1 are rejected; legacy negative values are not rejected.

Example request

$block = FM_api('FormBlock_new', [
	'name' => 'Standard footer',
	'type' => '1',
]);

Example response

{
  "ok": 1,
  "id": 4822,
  "name": "Standard footer",
  "type": 1
}

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: name"}The name key is absent.
{"error":"no name entered"}The supplied name is blank after trimming.
{"error":"parameter too long: name. max length 64 characters"}The name exceeds 64 Unicode characters.
{"id":"4822","error":"A form or email block with that name already exists"}A block of either type already has that name; the existing ID is returned.
{"error":"invalid form_block type supplied"}The integer-coerced type is greater than 1.
{"error":"form edits are disabled for this account"}Definition edits are disabled.

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

Behaviour and edge cases

  • The new row starts without code or an image.
  • cdate and last_edited are stored as Unix seconds.
  • The name check and insert are separate operations; the schema has no unique key on name.

Side effects

  • Inserts one tenant form_blocks row. No audit-log row is written.

See it in Fieldmotion

CRM1

The Create button on Form Blocks sends type 0; Email Template Blocks sends type 1.

CRM2

The corresponding two management screens use the same create flow.

Related endpoints