Update File Placement (Move / Categorize per Entity)

Move or categorize a document on one record only, leaving its copies on other records untouched. Get the placementId from List File Placements (listCompanyFilePlacements). For a file on a single record, Rename, Move, or Categorize File (updateCompanyFile) does the same.

Updates ONE placement’s organization — the folder it sits in (folderId) and/or its free-text category label. Folder location and category are per placement, so this is the way to re-folder or re-categorize a file that is shared across several entities: address the placement to change by its id (from List File Placements or the share response) — the file’s other placements are untouched. The owner-less Rename, Move, or Categorize File endpoint returns 409 Conflict for these fields once a file is shared; it also works on single-placement files, where either endpoint can be used.

Send only the fields you want to change — at least one must be present. Set folderId to a folder id to move the placement into that folder (the folder must belong to the placement’s owner), or to null for the owner’s top level. Set category to any non-blank string (max 255 characters; leading and trailing whitespace is trimmed) or to null to clear it — categories are free-text, there is no configured list to match against. displayName lives on the file itself (one name everywhere) — rename it via the file PATCH.

A placement with placementKind: invoice is a read-only appearance on the invoice’s linked event. Updating it returns 409 Conflict; manage the attachment on its invoice.

Required permission: file.edit