Fieldmotion API Getting started

Forms

Set a form-block preview image

POST /a/FormBlock_setImage

Convert an uploaded data URI into the block’s PNG preview and store its download path.

When to use this endpoint

Use this after creating a block when the reusable block chooser needs a visual preview. It is the upload action behind both form-block management screens.

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
idPositive integerYesExisting tenant block ID.
FiledataImage data URI stringYesA base64 data URI declared as PNG, JPEG, GIF, or WebP. The declared type must match decodable image bytes. ImageMagick flattens the image and resizes it within 1024×1024 pixels.

Example request

$result = FM_api('FormBlock_setImage', [
	'id' => '4821',
	'Filedata' => 'data:image/png;base64,iVBORw0KGgoAAA...',
]);

Example response

{
  "ok": 1,
  "now": 1790845200,
  "img": "/f/92442/formblocks/4821.png"
}

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":"invalid or missing parameter: id"}ID is absent or not positive.
{"error":"missing parameter: Filedata"}The upload body is absent.
{"error":"no such form block"}No matching block exists.
{"error":"invalid image data"}The value is not an accepted image data URI, base64 decoding fails, the bytes are not an image, or the declared and detected formats differ.
{"error":"failed to process image"}Temporary-file creation, ImageMagick conversion, or reading the converted PNG fails.
{"error":"failed to store image"}File storage returns no result. A structured storage error is passed through unchanged.
{"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 output is always addressed as formblocks/<id>.png and overwrites the prior preview for that block.
  • The row is updated only after successful validation, PNG conversion, and file storage. Temporary conversion files are removed on both success and handled failure paths.

Side effects

  • Writes a type-19 file through the configured file backends.
  • Sets the row’s image path and Unix-seconds last_edited.

See it in Fieldmotion

CRM1

Click the Image cell for a Form Block or Email Template Block and upload a file.

CRM2

The same Image-tab upload uses this endpoint.

Related endpoints