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

Use signed API-key authentication or a logged-in CRM session on the account’s routed host. File IDs and stored URLs normally resolve within that tenant; they are not public or cross-tenant identifiers. Session CSRF applies where required by the dispatcher.

The shared content-read guard denies type 10. For ordinary file types it requires a user session; CRM2 sessions (crmVersion=2) additionally need Files View (pageFiles_view). CRM1 does not receive that CRM2 page permission check.

Types 6, 8 and 16 return before the shared guard’s login/Files-page checks. Types 7 and 9 bypass the CRM2 Files-page check only after a user is established; type 6 is also treated as an app asset. An internal shareable-file context can bypass the remaining ordinary checks. Explicit route login checks still apply, and these exceptions do not override the dispatcher’s configured record-scope guard.

When department/team or Assigned Jobs Only scope is configured for the actor, the dispatcher adds record-scope checks. This is selected by account features/actor flags, separately from the CRM2-only Files View check; the existing TeamAccess entry guard has no CRM-version condition. Explicit supplied id/ids values are checked. Collection entry acceptance does not itself add a file-scope SQL predicate to these legacy mapped/table handlers; confirm the configured-scope collection contract before treating every returned row/count as authorized.

Parameters

ParameterTypeRequiredDescription
id / idsInteger-compatible or native arrayNoOptional file IDs. With neither key, every non-deleted file matching other mapped filters can be returned. Use the tenant file-record ID returned by upload/list/detail calls. This is separate from type_id/typeId (the linked resource ID), and from the random token in a storage URL. id takes precedence. Native lists are supported; JSON-encoded list text is not decoded here. An empty native selection adds no ID restriction; omit neither IDs nor other filters when a bounded read is required.
fieldsNative arrayYesNonempty native list of nonempty string names; omission, empty lists and JSON-encoded field-list text are rejected before mapped reads. Unknown names are omitted; id and typeEnum are always included. Choose narrow metadata fields and avoid data unless inline database bytes are intended.
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": "missing or invalid parameter: fields"}fields is absent, empty, associative, encoded text, or contains a nonstring/empty member.
{"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. Plain selected meta stays encoded JSON text; nested metadata aliases can decode values through the shared processor. Driver scalar types are retained.
  • A per-result read guard runs after the query and forces typeEnum into the output. Any denied row rejects the entire result, rather than quietly omitting it. Empty results are []; read failure can also collapse to [] in the mapped helper.
  • Mapped quoted scalar filters compare case-insensitive trimmed exact text; native lists use IN. order accepts mapped names or {id,dir} descriptors; no default order, stable tie-breaker or pagination is promised. Raw advanced rules are a trusted legacy builder surface, not safe third-party SQL inputs.

Side effects

  • Reads selected database columns only. Unlike content download routes it does not hydrate or restore a missing blob through the storage library.

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