Skip to main content
The Geofences API provides CRUD operations for geofence definitions and a real-time check endpoint that determines which geofences a given coordinate falls within.
See the Geofencing feature page for business context, integration patterns, and configuration guidance.

​
Base Path

/api/v1/geofences          # CRUD operations
/api/v1/geofences/check    # Location check

​
GET /api/v1/geofences

List all geofences for the current tenant, ordered by creation date (newest first). Roles: admin, editor, viewer

​
Response 200

{
  "data": [
    {
      "id": "gf_001",
      "tenantId": "t_001",
      "name": "Downtown Flagship Store",
      "description": "200m radius around main retail location",
      "latitude": 47.6062,
      "longitude": -122.3321,
      "radiusMeters": 200,
      "triggerOn": "enter",
      "dwellMinutes": null,
      "cooldownMs": 86400000,
      "action": {
        "type": "recommend",
        "decisionFlowId": "df_store_promo",
        "channel": "push"
      },
      "status": "active",
      "createdAt": "2026-04-01T10:00:00.000Z",
      "updatedAt": "2026-04-01T10:00:00.000Z"
    }
  ]
}

​
Response Fields

FieldTypeDescription
idstringUnique geofence identifier
tenantIdstringTenant identifier
namestringHuman-readable name
descriptionstringOptional description
latitudenumberCenter latitude
longitudenumberCenter longitude
radiusMetersintegerRadius in meters
triggerOnstringTrigger type: enter, exit, or dwell
dwellMinutesinteger or nullMinutes required for dwell triggers
cooldownMsintegerCooldown period in milliseconds
actionobjectAction payload to execute on trigger
statusstringactive or inactive
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 last update timestamp

​
Example

curl https://playground.kaireonai.com/api/v1/geofences \
  -H "X-Tenant-Id: my-tenant" \
  -H "Authorization: Bearer <token>"

​
POST /api/v1/geofences

Create a new geofence. Roles: admin, editor

​
Request Body

FieldTypeRequiredDescription
namestringYesGeofence name
descriptionstringNoOptional description
latitudenumberYesCenter latitude (-90 to 90)
longitudenumberYesCenter longitude (-180 to 180)
radiusMetersintegerNoRadius in meters. Default: 500
triggerOnstringNoenter, exit, or dwell. Default: enter
dwellMinutesintegerNoMinutes for dwell triggers
cooldownMsintegerNoCooldown in ms. Default: 86400000 (24h)
actionobjectNoAction payload
statusstringNoactive or inactive. Default: active

​
Response 201

Returns the created geofence object (same shape as GET response items).

​
Example

curl -X POST https://playground.kaireonai.com/api/v1/geofences \
  -H "X-Tenant-Id: my-tenant" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "Airport Terminal",
    "latitude": 47.4502,
    "longitude": -122.3088,
    "radiusMeters": 1000,
    "triggerOn": "dwell",
    "dwellMinutes": 30,
    "cooldownMs": 43200000,
    "action": {
      "type": "recommend",
      "decisionFlowId": "df_travel",
      "channel": "push"
    }
  }'

​
PUT /api/v1/geofences

Update an existing geofence. The request body must include the id field. All other fields are optional and only provided fields are updated. Roles: admin, editor

​
Request Body

FieldTypeRequiredDescription
idstringYesGeofence ID to update
namestringNoUpdated name
descriptionstringNoUpdated description
latitudenumberNoUpdated latitude
longitudenumberNoUpdated longitude
radiusMetersintegerNoUpdated radius
triggerOnstringNoUpdated trigger type
dwellMinutesintegerNoUpdated dwell time
cooldownMsintegerNoUpdated cooldown
actionobjectNoUpdated action payload
statusstringNoUpdated status

​
Response 200

Returns the updated geofence object.

​
Example

curl -X PUT https://playground.kaireonai.com/api/v1/geofences \
  -H "X-Tenant-Id: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "gf_001",
    "radiusMeters": 300,
    "status": "inactive"
  }'

​
DELETE /api/v1/geofences

Permanently delete a geofence. Roles: admin

​
Query Parameters

ParameterTypeRequiredDescription
idstringYesGeofence ID to delete

​
Response 200

{
  "deleted": true
}

​
Example

curl -X DELETE "https://playground.kaireonai.com/api/v1/geofences?id=gf_001" \
  -H "X-Tenant-Id: my-tenant" \
  -H "Authorization: Bearer <token>"

​
POST /api/v1/geofences/check

Check which active geofences a given coordinate falls within. Uses the Haversine formula for distance calculation. Roles: admin, editor, viewer

​
Request Body

FieldTypeRequiredDescription
latitudenumberYesCurrent latitude
longitudenumberYesCurrent longitude
customerIdstringNoOptional customer identifier (returned in the response for correlation)

​
Response 200

{
  "customerId": "CUST-001",
  "latitude": 47.6065,
  "longitude": -122.3325,
  "matchCount": 1,
  "matches": [
    {
      "geofenceId": "gf_001",
      "geofenceName": "Downtown Flagship Store",
      "distance": 45,
      "radiusMeters": 200,
      "action": {
        "type": "recommend",
        "decisionFlowId": "df_store_promo",
        "channel": "push"
      },
      "triggerOn": "enter"
    }
  ]
}

​
Match Fields

FieldTypeDescription
geofenceIdstringID of the matched geofence
geofenceNamestringName of the matched geofence
distanceintegerDistance in meters from the coordinate to the geofence center
radiusMetersintegerRadius of the geofence
actionobjectAction payload configured on this geofence
triggerOnstringTrigger type (enter, exit, dwell)

​
Example

curl -X POST https://playground.kaireonai.com/api/v1/geofences/check \
  -H "X-Tenant-Id: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "CUST-001",
    "latitude": 47.6065,
    "longitude": -122.3325
  }'

​
Error Codes

StatusCodeDescription
400Bad RequestMissing required fields (name, latitude, longitude for create; id for update/delete; latitude/longitude for check)
401UnauthorizedMissing or invalid authentication
403ForbiddenInsufficient role for this operation
404Not FoundGeofence ID not found (update/delete)
500Server ErrorInternal error

​
See Also