ESesper
geofence_Geofences

List all geofences

Changed on

Retrieves a paginated list of geofences configured for the tenant. Use it to enumerate all geofences, optionally narrowed down by ID or name.

Supports filtering by a list of geofence IDs, an exact name match, or a free-text name search, and can optionally include device summary statistics and/or a total count alongside each geofence in the response. Soft-deleted geofences are excluded unless is_deleted=true.

About Geofences

A geofence is a virtual geographic boundary (defined by a location and radius) that triggers device actions — such as locking down or sounding an alert — when a managed device enters or leaves the area. Geofences can also be tied to blueprints so that specific device configurations apply based on location.

Key Fields / Query Parameters

  • geofence IDs — filter to a specific set of geofences by ID
  • name — exact-match filter on geofence name
  • search — free-text search across geofence names
  • is_deleted — when true, list only soft-deleted geofences
  • include device summary statistics — optionally embed device counts for each geofence in the list response

Common Use Cases

  • Building a geofence management view that lists all configured boundaries
  • Looking up a geofence by name before fetching its device or blueprint details
  • Getting a quick device-count overview per geofence without a separate call
get/geofence/v1/geofences

Request

  • Base URL
    https://develop-api.esper.cloud/api
  • URL
    https://develop-api.esper.cloud/api/geofence/v1/geofences
  • Auth
    HTTP bearer

Query parameters

offsetinteger

Number of items to skip before starting to collect the result set

limitinteger

Maximum number of items to return

idsstring

Comma-separated list of geofence UUIDs to filter by. When provided, only geofences with matching IDs will be returned.

include_summaryboolean

Whether to include device summary and blueprint usage statistics with each geofence. When true, adds device_summary and blueprints fields to each result.

include_countboolean

Whether to include the total count of geofences in the response. When true, adds a count field to the response.

searchstring

Search string to filter geofences by name (case-insensitive partial match).

namestring

Exact geofence name to filter by (case-sensitive exact match).

is_deletedboolean

When true, returns only soft-deleted geofences. When omitted or false, returns only live geofences.

Response

A list of geofences

Example response

{
  "content": {
    "next": "/v1/geofences?offset=10&limit=10",
    "count": 42,
    "results": [
      {
        "id": "11111111-1111-1111-1111-111111111111",
        "name": "Warehouse Perimeter",
        "description": "A polygon-shaped geofence",
        "actions": [
          "lockdown",
          "beep"
        ],
        "geometry": {
          "type": "polygon",
          "coordinates": [
            {
              "latitude": 41.8902,
              "longitude": 12.4924
            },
            {
              "latitude": 41.8903,
              "longitude": 12.4925
            },
            {
              "latitude": 41.8904,
              "longitude": 12.4926
            }
          ]
        },
        "created_at": "2024-06-24T14:00:00Z",
        "updated_at": "2024-06-24T15:00:00Z",
        "device_summary": {
          "total_devices": 100,
          "inside_count": 60,
          "outside_count": 35,
          "unknown_count": 5
        },
        "blueprints": [
          {
            "blueprint_id": "550e8400-e29b-41d4-a716-446655440000",
            "blueprint_version_number": 1,
            "device_count": 25
          }
        ]
      }
    ]
  }
}

Changes