Files
Get selected file details
/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
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
| Parameter | Type | Required | Description |
|---|---|---|---|
id / ids | Integer-compatible or native array | No | Optional 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. |
fields | Native array | Yes | Nonempty 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 filters | Scalar or array | No | Exact 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
| Response | Condition |
|---|---|
{"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
File_getFilereturns bytes for one selected record.Files_getDataTablesupplies a paginated table.- File identifiers and downloads explains file ID, resource ID, type enum, stored URL and the different content response shapes.