Fieldmotion API Getting started

Files

Get the CRM2 Files table

POST /a/Files_getDataTable

Query named file fields through CRM2’s mapped table engine with resource-type isolation, expiry filtering, search, and pagination.

When to use this endpoint

Use Files_getDataTable for modern Customer, Job, Asset, User, Asset Type, and generic Files tables.

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
fieldsNative arrayYesMapped fields to return; unknown names are ignored. Common table fields are id, cDate, filename, notes, meta, customerReadable, typeEnum, and typeId.
typeEnum / typeIdInteger-compatibleNoExact mapped relationship filters. Both should be supplied by resource-specific tables to prevent same-numbered resources of another type from leaking into results.
expiryStatusNative arrayNoOnly the first value is used: 0 requires no meta.dateExpiry; 1 requires a date. A scalar is treated like zero.
jobDisplayFormFilesBoolean-compatibleNoWhen true with typeEnum=3, returns type 3 Job files and type 8 Job-form photos for the same typeId.
isTable / draw / start / length / limitInteger-compatibleNoShared table controls. Table mode defaults to offset 0 and length 10; exact isTable=0 returns an unwrapped data set with optional positive limit.
orderBy / orderDesc or order[0]Mapped field / DataTables orderNoMapped ordering controls.
searchValue / searchFieldString / string or arrayNoCase-insensitive substring search across selected mapped fields; All searches every searchable mapped field.
referenceDate / dateFrom / dateToMapped date field / integer day offsetsNoTenant-timezone relative range, commonly cDate.
Mapped filters / advanceSearch / groupByMixedNoShared mapped-table filters. Available fields 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. Raw advanced where shapes are trusted-CRM-only.

Example request

$table = FM_api('Files_getDataTable', [
	'fields' => ['id', 'cDate', 'filename', 'notes', 'meta', 'customerReadable'],
	'typeEnum' => '2',
	'typeId' => '1042',
	'draw' => '3',
	'start' => '0',
	'length' => '25',
]);

Example response

{
  "data": [{
    "id": "4821",
    "cDate": "2026-09-20 10:15:00",
    "filename": "asset-photo.jpg",
    "notes": "Service evidence",
    "meta": {"user_id":37,"tags":"service"},
    "customerReadable": "0"
  }],
  "draw": 3,
  "recordsTotal": "240",
  "recordsFiltered": "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: fields"}Fields are absent.
{"error":"permission denied"}The requested type fails the read guard.

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 from data and counts. recordsTotal counts tenant-wide live files, while recordsFiltered applies relationship, expiry, search, and advanced filters.
  • Table results are paginated; non-table mode is unbounded unless limit is positive. The Job-form expansion removes the exact type filter but retains the resource ID.
  • CRM2 pageFiles_view is evaluated using the requested type before the Job/type-8 expansion.

See it in Fieldmotion

CRM1

No production CRM1 caller was found; CRM1 uses Files_getDT.

CRM2

Open Files for a Customer, Job, Asset, User, or Asset Type; layout fields, search, filters, sorting, and paging feed this endpoint.

Related endpoints