---
title: "[beta] Update a place"
method: PATCH
path: "/places"
tags: ["Beta APIs"]
---

# \[beta\] Update a place

`PATCH /places`

## Request

- Base URL: `https://api.samsara.com`
- URL: `https://api.samsara.com/places`
- Auth: HTTP bearer

Updates a place. Provide exactly one of query parameter `placeId` (Samsara id) or `externalId` (key:value). Only fields present in the JSON body are changed; omit a field to leave it unchanged.

 <b>Rate limit:</b> 100 requests/min (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).

To use this endpoint, select **Write Places** under the Places category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>
 

 **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.

## Query parameters

- `placeId` integer
- `externalId` string

## Request body

- PlacesPatchPlaceRequestBody: Partial update for a place.
  - `address` string: Single-line address string.
  - `addressLatitude` number, double: Latitude of the place pin (map marker), stored independently of the geofence. When supplied, updates the pin; omitting it leaves the existing pin unchanged. Provide together with addressLongitude.
  - `addressLongitude` number, double: Longitude of the place pin (map marker), stored independently of the geofence. When supplied, updates the pin; omitting it leaves the existing pin unchanged. Provide together with addressLatitude.
  - `businessContacts` PostPlaceBusinessContactsInputRequestBody: Business contact information for a place.
    - `contacts` PostPlaceBusinessContactInputRequestBody[]: Named contacts with optional phone and email.
      - `email` string: Contact email. Opaque string; max 100 characters.
      - `name` string: Display name. Max 50 characters.
      - `phoneNumber` string: Contact phone. Opaque string; max 15 characters.
    - `email` string[]: Place-level email addresses. Opaque strings; max 100 characters each.
    - `phoneNumbers` string[]: Place-level phone numbers. Opaque strings; max 15 characters each.
  - `cameraRecordingModeType` 'fullRecording' | 'driverPrivacy' | 'completePrivacy' | 'inherit' | 'unknown' | 'unspecified': Camera recording mode: fullRecording, driverPrivacy, completePrivacy, or inherit. Valid values: `fullRecording`, `driverPrivacy`, `completePrivacy`, `inherit`, `unknown`, `unspecified`
  - `externalIds` object: When present, replaces external ids for the place.
  - `geofence` PlaceGeofenceInputRequestBody: Discriminated geofence on write. Exactly one of circle, polygon, or auto must be set.
    - `auto` PlaceGeofenceAutoInputRequestBody: Auto-geofence settings on write. Server geocodes from top-level address when seed coordinates are omitted, then suggests and persists resolved geometry.
      - `fallbackBehavior` PlaceGeofenceAutoFallbackBehaviorInputRequestBody: Action when auto-geofencing finds no matching candidate after filtering.
        - `behaviorType` 'fail' | 'circle': Fallback action: fail (default) or circle. Optional when fallbackBehavior.circle is set; inferred as circle. Valid values: `fail`, `circle`
        - `circle` PlaceGeofenceAutoFallbackCircleInputRequestBody: Circle geometry for circle fallback. When present, behaviorType defaults to circle if omitted.
          - `radiusMeters` integer, required: Fallback circle radius in meters; must be positive.
      - `isSuggestedNameEnabled` boolean: When true, replace the request name with the winning suggestion name when non-empty.
      - `isValidateAddressEnabled` boolean: When true and both top-level address and seed coordinates are present, geocode the address and reject the request when the result does not correlate with the seed.
      - `latitude` number, double: Seed latitude in WGS84 decimal degrees. Supply together with longitude, or omit both to geocode from top-level address.
      - `longitude` number, double: Seed longitude in WGS84 decimal degrees. Supply together with latitude, or omit both to geocode from top-level address.
      - `maxAreaSquareMeters` number, double: Drop candidates with area above this value in square meters.
      - `maxSourceVertices` integer: Drop candidates whose source polygon exceeds this vertex count before simplification.
      - `maxVertices` integer: Simplify the selected polygon to at most this many vertices before persist.
      - `searchBounds` PlaceGeofenceAutoSearchBoundsInputRequestBody: Optional search bounds for geofence suggestion lookup.
        - `maxLatitude` number, double, required: Maximum latitude in WGS84 decimal degrees.
        - `maxLongitude` number, double, required: Maximum longitude in WGS84 decimal degrees.
        - `minLatitude` number, double, required: Minimum latitude in WGS84 decimal degrees.
        - `minLongitude` number, double, required: Minimum longitude in WGS84 decimal degrees.
      - `sizeOrder` 'smallestFirst' | 'largestFirst': Candidate sort order within each type tier. Valid values: `smallestFirst`, `largestFirst`
      - `suggestionTypes` string[]: Candidate types in priority order. Defaults to building, parcel, landUse, boundary.
    - `circle` PlaceGeofenceCircleInputRequestBody: Circle geofence on write.
      - `latitude` number, double: Circle center latitude in decimal degrees. Omit on POST to geocode from top-level address.
      - `longitude` number, double: Circle center longitude in decimal degrees. Omit on POST to geocode from top-level address.
      - `radiusMeters` integer, required: Radius in meters; must be positive.
    - `polygon` PlaceGeofencePolygonInputRequestBody: Polygon geofence on write.
      - `vertices` GeofenceVertexInputRequestBody[], required: Polygon vertices; at least three.
        - `latitude` number, double, required: Latitude in decimal degrees.
        - `longitude` number, double, required: Longitude in decimal degrees.
    - `type` 'circle' | 'polygon' | 'auto': Geofence type: circle, polygon, or auto (write only). When present, must match the populated branch. Valid values: `circle`, `polygon`, `auto`
  - `iftaExemptionTypes` string[]: When present, replaces IFTA exemption types for the place.
  - `isShowAddressesEnabled` boolean: When true, show addresses inside the geofence on the map.
  - `name` string: Place name.
  - `navigation` PostPlaceNavigationInputRequestBody: Navigation metadata for create.
    - `locations` PostPlaceNavigationLocationInputRequestBody[], required: Navigation locations.
      - `driverInstructions` string: Optional instructions for drivers.
      - `latitude` number, double, required: Latitude in decimal degrees.
      - `locationType` 'entrance' | 'exit' | 'twoWay', required: Navigation location type: entrance, exit, or twoWay. Valid values: `entrance`, `exit`, `twoWay`
      - `longitude` number, double, required: Longitude in decimal degrees.
      - `name` string, required: Display name for the navigation location.
  - `notes` string: Notes.
  - `placeTypes` string[]: When present, replaces address-type categories via address metadata. Metadata-derived types (hubLocation, navigation, iftaExemption) must match routing, navigation, and IFTA metadata after this request; conflicting combinations return InvalidArgument.
  - `routing` PlaceRoutingPatchInputRequestBody: Targeted route-planning updates on PATCH.
    - `removeHubIds` string[]: Hub ids to delete. Omitted hubs are unchanged. Removing an unknown hub id is a no-op.
    - `upsert` PlaceRoutingInputRequestBody[]: Rows to create or update by hubId. Each entry requires hubId; (placeId, hubId) must be unique within upsert.
      - `driverInstructions` string: Default instructions for drivers at this stop.
      - `hubId` string, required: Planner hub UUID for this row.
      - `hubNotes` string: Hub-facing notes for this routing row.
      - `isDepot` boolean: Whether this routing row is a depot.
      - `orderServiceTime` PlaceRoutingOrderServiceTimeInputRequestBody: Order service time configuration for a routing row.
        - `capacityServiceTime` PlaceRoutingCapacityServiceTimeInputRequestBody: Per-capacity order service time for a routing row.
          - `capacityId` string, required: Capacity UUID.
          - `quantityPerServiceTime` number, double, required: Quantity units per service time chunk.
          - `serviceTimeSeconds` integer, required: Service time in seconds.
        - `fixedServiceTimeSeconds` integer: Fixed order service time in seconds. Required when modeType is fixed.
        - `isEnabled` boolean: When true, order service time settings apply at this stop; when false, hub/session defaults apply.
        - `modeType` 'fixed' | 'variable', required: Mode: fixed or variable. Valid values: `fixed`, `variable`
      - `position` 'first' | 'last': Stop position preference: first or last. Valid values: `first`, `last`
      - `priority` integer: Route priority from 1 (lowest) to 5 (highest).
      - `requiredSkills` PlaceRoutingRequiredSkillInputRequestBody[]: Required planner skills for this routing row.
        - `id` string, required: Planner skill UUID.
      - `routingExternalId` string: Customer-defined external identifier within the hub.
      - `serviceTime` PlaceRoutingServiceTimeInputRequestBody: Additional service time configuration for a routing row.
        - `isEnabled` boolean, required: Whether additional service time is enabled.
        - `serviceTimeMinutes` integer, required: Whole minutes of additional service time.
      - `serviceWindows` PlaceRoutingServiceWindowInputRequestBody[]: Recurring local-time service windows for this routing row.
        - `days` string[], required: Days this window applies.
        - `endTime` string, required: End time as HH:MM:SS in the org timezone. Overnight windows may have endTime before startTime.
        - `startTime` string, required: Start time as HH:MM:SS in the org timezone.
  - `safetyEventExclusions` string[]: When present, replaces safety event exclusions for the place.
  - `streetView` PlaceStreetViewInputRequestBody: Street view settings on write.
    - `headingDegrees` number: Camera heading clockwise from true north; 0 ≤ headingDegrees < 360.
    - `isEnabled` boolean, required: Whether street view is enabled.
    - `latitude` number, double: Latitude.
    - `longitude` number, double: Longitude.
    - `pitchDegrees` number: Camera pitch relative to the Street View horizon; −90 ≤ pitchDegrees ≤ 90.
    - `zoom` number, double: Zoom level.
  - `tags` PostPlaceTagRefRequestBody[]: When present, replaces all tag associations for the place.
    - `id` string, required: Numeric Samsara tag id.

## Response `200`

OK response.

- PlacesPatchPlaceResponseBody
  - `data` PlaceResponseObjectResponseBody, required: A place (geofence / location) in the organization.
    - `address` string, required: Address string.
    - `addressLatitude` number, double: Latitude of the place pin (map marker), stored independently of the geofence. Omitted when no pin is set.
    - `addressLongitude` number, double: Longitude of the place pin (map marker), stored independently of the geofence. Omitted when no pin is set.
    - `businessContacts` PlaceBusinessContactsResponseResponseBody: Business contact information for a place.
      - `contacts` PlaceBusinessContactResponseResponseBody[]: Named contacts.
        - `email` string: Contact email.
        - `name` string: Display name.
        - `phoneNumber` string: Contact phone.
      - `email` string[]: Place-level email addresses.
      - `phoneNumbers` string[]: Place-level phone numbers.
    - `cameraRecordingModeType` string: Camera recording mode: inherit, fullRecording, driverPrivacy, completePrivacy, or unknown.
    - `createdAtTime` string, date-time, required: Created timestamp in RFC 3339 format.
    - `externalIds` object: External ids when includeExternalIds=true.
    - `geofence` PlaceGeofenceResponseResponseBody, required: Discriminated place geofence. GET returns circle, polygon, or unknown when stored geometry cannot be mapped.
      - `circle` PlaceGeofenceCircleResponseResponseBody: Circle geofence geometry.
        - `latitude` number, double, required: Circle center latitude in decimal degrees.
        - `longitude` number, double, required: Circle center longitude in decimal degrees.
        - `radiusMeters` integer, required: Radius in meters; must be positive.
      - `polygon` PlaceGeofencePolygonResponseResponseBody: Polygon geofence geometry.
        - `vertices` PlaceGeofenceVertexResponseResponseBody[], required: Polygon vertices; at least three.
          - `latitude` number, double, required: Latitude in decimal degrees.
          - `longitude` number, double, required: Longitude in decimal degrees.
      - `type` 'circle' | 'polygon' | 'unknown', required: Geofence type: circle, polygon, or unknown. Valid values: `circle`, `polygon`, `unknown`
    - `id` string, required: Samsara place id.
    - `iftaExemptionTypes` string[]: IFTA exemption labels.
    - `isAutoDismissRolledStopsEnabled` boolean: Auto-dismiss rolled stops.
    - `isShowAddressesEnabled` boolean: Show addresses inside geofence.
    - `name` string, required: Place name.
    - `navigation` PlaceNavigationResponseResponseBody: Navigation metadata.
      - `locations` PlaceNavigationLocationResponseResponseBody[], required: Navigation locations.
        - `driverInstructions` string: Driver instructions.
        - `latitude` number, double, required: Latitude.
        - `locationType` string, required: Navigation location type.
        - `longitude` number, double, required: Longitude.
        - `name` string, required: Location name.
    - `notes` string: Notes.
    - `placeTypes` string[]: Assigned place types.
    - `routing` RoutingResponseResponseBody[]: Route-planning rows when present.
      - `driverInstructions` string: Default instructions for drivers.
      - `hubId` string, required: Hub (planner) UUID.
      - `hubNotes` string: Hub-facing notes.
      - `isDepot` boolean, required: Whether this routing row is a depot.
      - `orderServiceTime` RoutingOrderServiceTimeResponseResponseBody: Order service time configuration for a routing row.
        - `capacityServiceTime` RoutingCapacityServiceTimeResponseResponseBody: Per-capacity order service time entry.
          - `capacityId` string, required: Capacity UUID.
          - `quantityPerServiceTime` number, double, required: Quantity units per service time chunk.
          - `serviceTimeSeconds` integer, required: Service time in seconds.
        - `fixedServiceTimeSeconds` integer: Fixed order service time in seconds.
        - `isEnabled` boolean, required: Whether order service time settings apply at this stop.
        - `modeType` string, required: Mode: unknown, unspecified, fixed, or variable.
      - `position` string: Stop position preference: first or last.
      - `priority` integer: Route priority from 1 (lowest) to 5 (highest).
      - `requiredSkills` RoutingRequiredSkillResponseResponseBody[]: Required planner skills.
        - `id` string, required: Planner skill UUID.
        - `name` string: Skill display name when resolved on GET.
      - `routingExternalId` string: Customer-defined external identifier within the hub.
      - `serviceTime` RoutingServiceTimeResponseResponseBody: Additional service time at a routing row.
        - `isEnabled` boolean, required: Whether additional service time is enabled.
        - `serviceTimeMinutes` integer, required: Whole minutes of additional service time.
      - `serviceWindows` RoutingServiceWindowResponseResponseBody[]: Configured service windows.
        - `days` string[], required: Days this window applies.
        - `endTime` string, required: End time as HH:MM:SS in the org timezone.
        - `startTime` string, required: Start time as HH:MM:SS in the org timezone.
    - `safetyEventExclusions` string[]: Configured safety exclusions.
    - `streetView` PlaceStreetViewResponseResponseBody: Street view settings for a place.
      - `headingDegrees` number, double: Camera heading clockwise from true north; 0 ≤ headingDegrees < 360 on write, normalized mod 360 on GET.
      - `isEnabled` boolean, required: Whether street view is enabled.
      - `latitude` number, double: Latitude.
      - `longitude` number, double: Longitude.
      - `pitchDegrees` number, double: Camera pitch relative to the Street View horizon; −90 ≤ pitchDegrees ≤ 90.
      - `zoom` number, double: Zoom level.
    - `tags` PlaceTagResponseResponseBody[]: Tags when includeTags=true.
      - `id` string, required: Samsara tag id.
      - `name` string: Tag name when resolved.
      - `parentTagId` string: Parent tag id when present.
    - `updatedAtTime` string, date-time, required: Updated timestamp in RFC 3339 format.

## Other responses

- `401`: Unauthorized response.
- `404`: Not Found response.
- `405`: Method Not Allowed response.
- `413`: Content Too Large response.
- `429`: Too Many Requests response.
- `500`: Internal Server Error response.
- `501`: Not Implemented response.
- `502`: Bad Gateway response.
- `503`: Service Unavailable response.
- `504`: Gateway Timeout response.
- `default`: Bad Request response.

---

[API](https://skmtc.dev/samsara/apis/samsara-api.md) - [All operations](https://skmtc.dev/samsara/apis/samsara-api/llms.txt) - [OpenAPI document](https://skmtc.dev/samsara/apis/samsara-api/revisions/a9e35d4999be?raw)