Fieldmotion API Getting started

Files

Get selected file details

POST /a/File_getRequestedDetails

Return selected mapped metadata for one or more non-deleted file records, with per-result read-permission enforcement.

When to use this endpoint

Use File_getRequestedDetails for CRM2 detail widgets, photos, email attachments, and related-file summaries. It does not return storage bytes unless the caller explicitly requests the mapped data field.

Authentication and permissions

Normal requests require signed API-key authentication or a logged-in CRM session and are scoped to that tenant. In CRM2, ordinary file types additionally require view permission on pageFiles; CRM1 does not apply that page permission.

File type 10 is always denied by the shared read guard. Types 6, 8, and 16 bypass that guard’s session/page-files checks, while types 6, 7, and 9 bypass only its CRM2 page check after login. Routes that explicitly call the login guard still require login, and download routes still need a resolvable tenant context. A separately established shareable-link context may also bypass the shared read guard.

Parameters

ParameterTypeRequiredDescription
id / idsInteger-compatible or native arrayNoOptional file IDs. With neither key, every non-deleted file matching other mapped filters can be returned.
fieldsNative arrayNoMapped response fields; defaults to every mapped field. Unknown names are ignored. id and typeEnum are always added.
Mapped filtersScalar or arrayNoExact filters using the mapped names. Text comparisons are case-insensitive exact matches; numeric values use equality/IN. Available names are id, filename, typeId, description, cDate, notes, ownerID, meta, name, typeEnum, lastEdited, url, customerReadable, fileLast_Edited, deleted, ddate, storageType, storageInstance, data, filesize, metaUserID, metaDateExpiry, metaTags, metaIncludeInEmail, metaEditNotesInPortal, metaShareWithSites, metaShowInPortal, metaOutsourcing, and metaLinkForm.

Example request

$files = FM_api('File_getRequestedDetails', [
	'id' => ['4821', '4822'],
	'fields' => ['id', 'filename', 'typeEnum', 'typeId', 'meta', 'filesize'],
]);

Example response

[
  {
    "id": "4821",
    "filename": "asset-photo.jpg",
    "typeEnum": "2",
    "typeId": "1042",
    "meta": {"user_id": 37},
    "filesize": "18422"
  }
]

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":"permission denied"}Any returned row fails the read guard. The whole request fails rather than omitting that row.
[]No non-deleted rows match, including an ID value of zero.

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

Behaviour and edge cases

  • Soft-deleted rows are excluded automatically. Numeric database scalars usually remain strings; JSON-mapped values are decoded by the shared data processor.
  • Permission evaluation happens after the query and forces typeEnum into each result even when it was not requested.

See it in Fieldmotion

CRM1

CRM1 has no broad table caller; server helpers use it while assembling related Job data.

CRM2

File off-canvas panels, email composition, photos, Customers, Users, Jobs, Forms, Contracts, Tasks, Assets, Stocks, and Purchase Orders request selected file metadata through this route.

Related endpoints