Geofences

8 operations at https://api.zaitrack.app. Request and response bodies are JSON with camelCase keys; ids are UUIDs; times are RFC 3339 in UTC.

Every operation needs an API key, a personal access token or an OAuth access token unless it says otherwise. An Idempotency-Key is replayed for 24 hours; see Idempotency. Errors are application/problem+json; see Errors.

List geofences

GET /v1/geofences

• Scope: geofences:read or geofences:*
• Rate class: read (100 per second and 360,000 per hour)
• Idempotency-Key: not used
• Audited: no
• Step-up MFA: no

Query parameter	Type	Notes
pageSize	string
cursor	string

Request

No body.

Response

200: fields the handler writes, taken from its source.

Field	Type	Notes
items	array of object
items[].id	—
items[].name	—
items[].description	—
items[].kind	—
items[].category	—
items[].enabled	—
items[].tags	array of string
items[].createdBy	—
items[].createdAt	—
items[].updatedAt	—
items[].version	—
items[].externalRef	—
items[].timeWindow	object
items[].timeWindow.startMinUtc	integer
items[].timeWindow.endMinUtc	integer
items[].timeWindow.daysOfWeek	integer
items[].vertices	—
items[].radiusM	—
items[].bufferM	—
nextCursor	string

Example

curl "https://api.zaitrack.app/v1/geofences" \
  -H "Authorization: Bearer zk_test_…"

Create a geofence

POST /v1/geofences

• Scope: geofences:write or geofences:*
• Rate class: write (50 per second and 36,000 per hour)
• Idempotency-Key: optional
• Audited: no
• Step-up MFA: no

Request

Fields the handler reads, taken from its source.

Field	Type	Notes
name	string
description	string
category	string
kind	string
vertices	array of object
vertices[].lat	number
vertices[].lng	number
center	object
center.lat	number
center.lng	number
radiusM	number
polyline	array of object
polyline[].lat	number
polyline[].lng	number
bufferM	number
timeWindow	object
timeWindow.startMinUtc	integer
timeWindow.endMinUtc	integer
timeWindow.daysOfWeek	integer
tags	array of string

Response

201: fields the handler writes, taken from its source. The service's OpenAPI document describes a different body; this page follows the handler.

Field	Type	Notes
id	—
name	—
description	—
kind	—
category	—
enabled	—
tags	array of string
createdBy	—
createdAt	—
updatedAt	—
version	—
externalRef	—
timeWindow	object
timeWindow.startMinUtc	integer
timeWindow.endMinUtc	integer
timeWindow.daysOfWeek	integer
vertices	—
radiusM	—
bufferM	—

Example

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/geofences" \
  -H "Authorization: Bearer zk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "…", "description": "…", "category": "…", "kind": "…", "vertices": [], "center": {"lat": 0, "lng": 0}, "radiusM": 0, "polyline": [], "bufferM": 0, "timeWindow": {"startMinUtc": 0, "endMinUtc": 0, "daysOfWeek": 0}, "tags": []}'

Get a geofence

GET /v1/geofences/{id}

• Scope: geofences:read or geofences:*
• Rate class: read (100 per second and 360,000 per hour)
• Idempotency-Key: not used
• Audited: no
• Step-up MFA: no

Path parameters: id.

Request

No body.

Response

200: fields the handler writes, taken from its source. The service's OpenAPI document describes a different body; this page follows the handler.

The same fields as the response of Create a geofence.

Example

curl "https://api.zaitrack.app/v1/geofences/$ID" \
  -H "Authorization: Bearer zk_test_…"

Update a geofence

PATCH /v1/geofences/{id}

• Scope: geofences:write or geofences:*
• Rate class: write (50 per second and 36,000 per hour)
• Idempotency-Key: not used
• Audited: no
• Step-up MFA: no
• If-Match: the version you read; a stale one is refused (412 or 409)

Path parameters: id.

Request

Fields the handler reads, taken from its source.

Field	Type	Notes
name	string	optional
enabled	boolean	optional
description	string	optional
category	string	optional
center	object	optional
center.lat	number
center.lng	number
radiusM	number	optional
vertices	array of object
vertices[].lat	number
vertices[].lng	number
polyline	array of object
polyline[].lat	number
polyline[].lng	number
bufferM	number	optional
tags	array of string

Response

200: fields the handler writes, taken from its source. The service's OpenAPI document describes a different body; this page follows the handler.

The same fields as the response of Create a geofence.

Example

Every field is sent with a placeholder value: replace them with yours.

curl -X PATCH "https://api.zaitrack.app/v1/geofences/$ID" \
  -H "Authorization: Bearer zk_test_…" \
  -H 'If-Match: "3"' \
  -H "Content-Type: application/json" \
  -d '{"name": "…", "enabled": false}'

Delete a geofence

DELETE /v1/geofences/{id}

• Scope: geofences:write or geofences:*
• Rate class: write (50 per second and 36,000 per hour)
• Idempotency-Key: not used
• Audited: low risk
• Step-up MFA: no

Path parameters: id.

Request

No body.

Response

204: no body.

Example

curl -X DELETE "https://api.zaitrack.app/v1/geofences/$ID" \
  -H "Authorization: Bearer zk_test_…"

Whether a point lies in a geofence

POST /v1/geofences/{id}/check

• Scope: geofences:read or geofences:*
• Rate class: read (100 per second and 360,000 per hour)
• Idempotency-Key: not used
• Audited: no
• Step-up MFA: no

Path parameters: id.

Request

Fields the handler reads, taken from its source.

Field	Type	Notes
lat	number
lng	number

Response

200: fields the handler writes, taken from its source.

Field	Type	Notes
geofenceId	—
inside	boolean
name	string

Example

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/geofences/$ID/check" \
  -H "Authorization: Bearer zk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"lat": 0, "lng": 0}'

Geofences containing a point (?lat=&lng=)

GET /v1/geofences/containing

• Scope: geofences:read or geofences:*
• Rate class: read (100 per second and 360,000 per hour)
• Idempotency-Key: not used
• Audited: no
• Step-up MFA: no

Query parameter	Type	Notes
lat	string
lng	string

Request

No body.

Response

200: fields the handler writes, taken from its source.

Field	Type	Notes
items	array of object
items[].geofenceId	—
items[].name	—
items[].category	—

Example

curl "https://api.zaitrack.app/v1/geofences/containing" \
  -H "Authorization: Bearer zk_test_…"

Geofence entries and exits

GET /v1/geofences/visits

• Scope: geofences:read or geofences:*
• Rate class: read (100 per second and 360,000 per hour)
• Idempotency-Key: not used
• Audited: no
• Step-up MFA: no

Query parameter	Type	Notes
open	string
pageSize	string
cursor	string
geofenceId	—
deviceId	—
vehicleId	—
from	—
to	—

Request

No body.

Response

200: fields the handler writes, taken from its source.

Field	Type	Notes
items	array of object
items[].id	—
items[].geofenceId	—
items[].geofenceName	—
items[].category	—
items[].deviceId	—
items[].vehicleId	—
items[].enteredAt	—
items[].exitedAt	—
items[].durationSec	—
items[].enter	—
items[].exit	—
nextCursor	—

Example

curl "https://api.zaitrack.app/v1/geofences/visits" \
  -H "Authorization: Bearer zk_test_…"