---
title: "Batch-update a location and its sub-entities"
method: PUT
path: "/locations/update"
tags: ["Locations"]
---

# Batch-update a location and its sub-entities

`PUT /locations/update`

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.

## Headers

- `tenant-id` string

## Request body

- LocationUpdateRequest
  - `locationId` string, required
  - `crosswalkId` string
  - `entityAddressId` string
  - `groupLocationId` string
  - `tenantGroupLocationId` string, required
  - `networkId` string
  - `networkEffectiveDate` string
  - `effectiveDate` string
  - `name` string
  - `locationType` string
  - `acceptNewPatients` string
  - `suppressSiteFromDirectory` boolean
  - `contacts` unknown[]
    - unknown
  - `serviceAddress` object
  - `officeHours` unknown[]
    - unknown
  - `practiceLimitations` unknown[]
    - unknown
  - `accessibility` unknown[]
    - unknown
  - `networkSelection` string
  - `networks` unknown[]
    - unknown
  - `locationSpecialities` unknown[]
    - unknown
  - `userDefinedFields` object
  - `groupLocationUserDefinedFields` object — Free-form key/value map persisted to GroupLocation.data.userDefinedFields (CP-31476). Deep-merged into existing data; omitted/null keys preserve their prior value.

## Response `200`

Batch executed successfully. Returns a result object with a `message`, the resolved `locationId`/`certifyLocationId`/`entityAddressId`/`locationEntityAddressId`/`groupLocationId`/`tenantGroupLocationId` identifiers, a `batchResponse` summary, and a `locationSpecialties` array of the upserted specialty rows ({id, tenantSpecialtyId, effectiveDate, isPrimary}).

- object

## Other responses

- `400` — Invalid request. JSON-schema validation failure, missing required IDs (`locationId`/`tenantGroupLocationId`), or contact list validation errors. Inspect the error body for the specific field that failed validation.
- `403` — Forbidden — `locationSpecialities` contains a `newTenantSpecialtyId` (a specialty foreign-key swap) and the caller lacks the `group:correct:specialty` permission. Obtain the required permission before retrying.

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)