Share a file with child sites

When to use this endpoint

Use File_setShareWithSites on Customer files. The legacy list route reads a generated share_with_sites column while mapped CRM2 data reads meta.share_with_sites.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session and establish the tenant database context.

The handler performs no record-owner or resource-specific permission check. CRM screens may hide the action, but callers with tenant API/session access can target any matching file ID.

Parameters

Parameter	Type	Required	Description
`id`	Integer-compatible	Yes	Positive file ID.
`val`	Integer-compatible	No	Truthy stores `meta.share_with_sites=1`; false/absent removes it.

Example request

$result = FM_api('File_setShareWithSites', ['id' => '4821', 'val' => '1']);

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 parameter: id"}`	ID is non-positive; this validation occurs before login enforcement.
`{"error":"file not found"}`	The ID does not identify a live file.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

Malformed legacy metadata is normalized before the flag is changed. No last_edited, audit, or notification is written. Customer child-site inclusion is performed later by Files_getDT.

See it in Fieldmotion

CRM1

On Customer Files, toggle share with child sites.

CRM2

Customer, User, Job, Asset, and Asset Type file option dialogs expose this route, even though the legacy inheritance behavior is specific to Customer file listing.

Related endpoints

Files_getDT applies parent-site inheritance.