Files
Delete matching files
/a/Files_delete
Delete files matching mapped filters through the complete per-file storage, audit, and parent-resource lifecycle.
When to use this endpoint
Use explicit file ID lists for selected-file deletion. This route selects matching rows then delegates each to File_delete, preserving its content, deletion-log and parent-resource side effects.
Authentication and permissions
Normal API transport requires signed API-key fields or a logged-in CRM session and a tenant context. Session CSRF applies except for the dispatcher’s upload/download exceptions.
These handlers do not add general Files Add/Edit/Delete or file-owner role checks. UI visibility is not that protection. Configured team-scope entry checks are separate and may validate the linked record and its Edit permission before a handler runs; see the route-specific note below. This does not introduce CRM2 role requirements for ordinary CRM1 requests.
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 id/ids values are checked against visible file records. Other filename-only selections or mapped-filter-only bulk mutations can be rejected for lacking an explicit scoped selection.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
Mapped filters | Scalar or native array | Yes | At least one mapped filter from 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. CRM2 normally supplies id as one ID or an array. Filters are AND-combined; text is exact, numeric input is integer-normalized. |
Example request
$result = FM_api('Files_delete', ['id' => ['4821', '4822']]);
Example response
{
"ok": 1
}
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 filter"} | No recognized mapped field key is supplied. |
{"error": "failed to remove file content"} | A delegated File_delete fails content cleanup; earlier deletions and metadata changes may already be complete. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Already deleted rows are excluded. Empty matches return success. Every matching live row is soft-deleted, its stored content is removed, its deletion is logged, and supported parent file lists are rebuilt.
- Because every mapped field is filterable, callers can select by URL, filename, metadata-derived value, type, or other internal field; use an explicit ID list for predictable bulk UI actions.
- No pagination applies to this write. Use a fresh metadata/list read before dependent work; an error after storage, audit or notification work does not imply that earlier steps were rolled back.
- The initial mapped detail reader can collapse database failure to [], which this wrapper treats as an empty successful selection. There is no atomic batch or final re-read.
See it in Fieldmotion
CRM1
No direct production CRM1 caller was found.
CRM2
Select rows on a modern Files table and choose the generic Delete bulk action.
Related endpoints
File_deletecoordinates physical storage and parent state.- File identifiers and downloads explains file ID, resource ID, type enum, stored URL and the different content response shapes.