Batch-update a location and its sub-entities

Updates a location and its associated address, network membership, and specialty records in a single batch operation, using the IDs and fields provided in the request body.

When to use: Use this operation when you need to update multiple aspects of a location in one call — for example, changing address fields, toggling network participation, or managing specialties. To update only the core location fields for a single record use PUT /locations/{id} instead.

Preconditions: The tenant-id header is required. The request body must include locationId and tenantGroupLocationId (both required); all other fields are optional and are preserved if omitted. The networkSelection field controls network update behavior: "all" enrolls the location in all available networks; "selected" updates only the networks listed. If locationSpecialities is provided, specialty records are upserted (not deleted-and-replaced). If locationSpecialities contains a newTenantSpecialtyId (a specialty foreign-key swap), the caller must have the group:correct:specialty permission — otherwise the request returns 403. The userDefinedFields map (persisted to TenantGroupLocation) and groupLocationUserDefinedFields map (persisted to GroupLocation, CP-31476) are each deep-merged into the existing data: omitting the field preserves the existing value, a key omitted from the map is retained, and a key sent as null is ignored (its prior value survives). Only keys present with non-null values are overwritten.

Idempotency: Repeating the same request with the same IDs and field values produces the same state; the operation is safe to retry on transient failures provided locationSpecialities does not include FK swaps that require permission checks.