Skip to content

Geofences

Operations

Create a new geofence

Request

Creates a new geofence for the tenant, defined by its geographic boundary and the device actions to trigger when a device crosses it.

Submit the geofence's geometry (location and radius) along with the desired device actions; on success, returns the created geofence instance.

About Geofences

A geofence is a virtual geographic boundary that triggers device actions — such as locking down or sounding an alert — when a managed device enters or leaves the defined area. Geofences can also be associated with blueprints so that location determines which configuration is applied to a device.

Key Fields / Query Parameters

  • geometry (location and radius) — defines the physical boundary of the geofence
  • device actions — the actions (e.g., lock down, beep) applied to devices crossing the boundary

Common Use Cases

  • Setting up a new location-based restriction, such as locking down devices that leave a warehouse or job site
  • Defining a boundary that later gets tied to blueprint-based configuration changes
Security
geofence_bearerAuth
Headers
X-Esper-Tenant-Idstring, (uuid)required

Esper tenant ID associated with the request

X-Caller-Idstring, [ 1 .. 255 ] charactersrequired

Unique identifier for the caller

Bodyapplication/jsonrequired
namestring, [ 1 .. 255 ] charactersrequired

Name of the geofence

Example:"Geofence 1"
descriptionstring, <= 1000 characters

Optional description of the geofence

Example:"A geofence that is either polygonal or circular."
actionsArray of strings, [ 0 .. 2 ] items

Actions to trigger when geofence conditions are met. Empty array means no actions.

Items Enum:"lockdown""beep"
Example:
[
  "lockdown",
  "beep"
]
geometryanyrequired
cURL
curl -i -X POST \
  https://api.esper.io/_mock/openapi/geofence/v1/geofences \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Caller-Id: string' \
  -H 'X-Esper-Tenant-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '{
    "name": "Warehouse Perimeter",
    "description": "A polygon-shaped geofence",
    "actions": [
      "lockdown"
    ],
    "geometry": {
      "type": "polygon",
      "coordinates": [
        {
          "latitude": 41.8902,
          "longitude": 12.4924
        },
        {
          "latitude": 41.8903,
          "longitude": 12.4925
        },
        {
          "latitude": 41.8904,
          "longitude": 12.4926
        }
      ]
    }
  }'

Responses

Geofence created successfully

Bodyapplication/json
contentobject(geofence_GeofenceResponse)
Response
{
  "content": {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "Warehouse Perimeter",
    "description": "A polygon-shaped geofence",
    "actions": [ … ],
    "geometry": { … },
    "created_at": "2024-06-24T14:00:00Z",
    "updated_at": "2024-06-24T15:00:00Z"
  }
}