Update a geofence
PUT/api/v1/geofences/:geofenceId
Update (modify) a geofence by its internal ID. This will update the geofence with the new data provided in the request body.
ETag Requirement
This endpoint requires the If-Match header with a valid ETag value to prevent
lost updates due to concurrent modifications. Get the current ETag by retrieving
the geofence with a GET request first.
As with all PUT modifications, you
must include the If-Match header
with the current ETag value of the user record or the request will fail with a
"412 Precondition Failed" status code. The ETag value can be obtained by
retrieving the item with a GET request and examining the ETag header in the
response.
Updating Geofence Assignments
To modify geofence assignments, include a complete assignments array in the request
body. The provided assignments will replace all existing assignments:
- To add new assignments: Include existing assignments plus new ones
- To remove assignments: Omit them from the assignments array
- To clear all assignments: Send an empty array:
"assignments": [] - To leave assignments unchanged: Omit the
assignmentsfield entirely
This operation requires the Geofence - Manage ability, or
Authority - Administrator.
The pname field must remain unique across all geofences. Attempting to change
a geofence name to match another existing geofence will result in a 409 Conflict error.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 409
- 412
- 428
- 500
- 503
Successfully updated the geofence. The response includes the complete updated geofence object.
Note: Unlike many REST APIs that return 204 No Content for PUT operations,
this endpoint returns 200 OK with the complete updated geofence object in the response body.
Response Headers
The URL of the updated or modified object.
A 400 Bad Request is returned when the client request was malformed,
invalid, or otherwise could not be processed as-is. Usually, the cause for
the error is included in the error.message field of the response, and the
client should correct the request and try again.
See also Core Concepts#Error Responses.
Not authenticated - you must be signed in to access this resource. Please check the section of the documentation on authentication.
A 403 Forbidden response means that you are not authorized to perform
this action or access this object, or the object does not exist at all.
The client request may have been valid but the client does not have permission to access the requested resource or perform the requested action.
:::tip 403 Forbidden also used when objects don't exist
In most cases, the system will not return a 404 Not Found error response;
it returns 403 Forbidden both when the object doesn't exist at all,
and also when it exists but the client does not have permission to access it.
This is a security measure to prevent unauthorized users from determining
whether an object exists or not.
:::
See also Core Concepts#Error Responses.
Not found - the requested resource could not be found or does not exist. This may also include cases where the resource does exist, but the client does not have permission to access that resource.
:::tip 403 Forbidden also used when objects don't exist
In most cases, the system will not return a 404 Not Found error response;
it returns 403 Forbidden both when the object doesn't exist at all,
and also when it exists but the client does not have permission to access it.
This is a security measure to prevent unauthorized users from determining
whether an object exists or not.
:::
See also Core Concepts#Error Responses.
Conflict - A geofence with the specified name already exists.
The pname field must be unique across all geofences.
Precondition Failed - The ETag provided in the If-Match header does not match
the current ETag of the geofence. This indicates the geofence was modified by
another request since you last retrieved it. Fetch the current version and try again.
Precondition Required - The If-Match header is missing. This header is required
for update operations to prevent lost updates due to concurrent modifications.
Internal server error; an unexpected error occurred on the server. This could be due to a temporary condition or might be the result of a bug in the server software. Also, in some cases, an incorrect client input can trigger this error, and can be resolved by correcting the input.
If the error persists, please contact support along along with the following details when possible:
- any error messages received from the server
- the full request and response details (full headers and body)
- a description of the steps that led to the error
- the time range when it occurred.
Service unavailable - the server is currently unable to handle the request, usually due to maintenance activity on the server. Check if the server's web interface is currently available, or try again later.