This page takes you from a server key to a page of locations, then to a geofence event on your
webhook, with curl and jq. You need a server key (bkserv_…) for your project with these
scopes:
project:readandlocations:readfor the first part;geofences:write,webhooks:write,locations:writeandevents:readfor the second.
Read your locations
Section titled “Read your locations”-
Set your key and region host.
Issue a server key on the console’s API keys page (owners and admins), choosing its scopes.
The region is the second segment of your key:
bkserv_in1_…lives onapi.in1.getbeekon.com.Terminal window export BEEKON_SERVER_KEY='bkserv_in1_REPLACE_WITH_YOUR_SECRET'export BEEKON_API="https://api.$(echo "$BEEKON_SERVER_KEY" \| cut -d_ -f2).getbeekon.com" -
Exchange the key for a session token.
Terminal window export BEEKON_TOKEN=$(curl -sf -X POST "$BEEKON_API/v1/token" \-H "Authorization: Bearer $BEEKON_SERVER_KEY" | jq -r .access_token)The response is
{"access_token":"…","expires_in":3600}. The token lastsexpires_inseconds; mint a new one when it expires or when a call returns401. See Authentication. -
Check which project the key belongs to.
Terminal window curl -s "$BEEKON_API/v1/project" -H "Authorization: Bearer $BEEKON_TOKEN"{"id": "0199b2c4-1f3a-7c11-9d2e-5a6b7c8d9e0f","cell": "in1","created_at": "2026-10-07T06:30:00.000Z","name": "Fleet tracking","status": "active"}A
403 {"error":"insufficient scope"}here means the key lacksproject:read. Issue a new key with the scopes you need. -
Read a day of locations, one page at a time.
Terminal window curl -s -G "$BEEKON_API/v1/locations" \-H "Authorization: Bearer $BEEKON_TOKEN" \--data-urlencode "from=2026-10-06T00:00:00Z" \--data-urlencode "to=2026-10-07T00:00:00Z" \--data-urlencode "limit=500"{"locations": [{"id": "0190…","device": {"install_id": "2bed7f6c-…"},"is_mock": false,"latitude": 12.9716,"longitude": 77.5946,…}],"next_cursor": "lc1_…","retention_floor": null,"schema_version": 1}While
next_cursoris a string, there is more. Repeat the same request with--data-urlencode "cursor=<next_cursor>"added, untilnext_cursorisnull:Terminal window cursor=""while :; dopage=$(curl -sf -G "$BEEKON_API/v1/locations" \-H "Authorization: Bearer $BEEKON_TOKEN" \--data-urlencode "from=2026-10-06T00:00:00Z" \--data-urlencode "to=2026-10-07T00:00:00Z" \--data-urlencode "limit=500" \--data-urlencode "cursor=$cursor") || breakecho "$page" | jq -c '.locations[]| {install_id: .device.install_id, recorded_at, latitude, longitude}'cursor=$(echo "$page" | jq -r '.next_cursor // empty')[ -z "$cursor" ] && breakdone
Your first geofence event
Section titled “Your first geofence event”Create a geofence and a webhook, upload two locations inside the fence from your server, and
read the geofence.enter the server records. No app is needed: locations you send to
POST /v1/ingest are checked against your geofences like the SDK’s.
-
Create a geofence: a 200 m circle.
Terminal window FENCE_ID=$(curl -sf -X POST "$BEEKON_API/v1/geofences" \-H "Authorization: Bearer $BEEKON_TOKEN" \-H "Content-Type: application/json" \-d '{"name": "Quickstart","geometry": {"type": "circle","center": {"latitude": 12.9716, "longitude": 77.5946},"radius_meters": 200},"notify_on_entry": true,"notify_on_exit": true}' | jq -r .geofence.id)echo "$FENCE_ID" -
Add a webhook for geofence events.
endpoint_urlmust be a public HTTPS URL you control; for a first test, a request-inspection service works. The receiver code is on Webhooks.Terminal window curl -sf -X POST "$BEEKON_API/v1/webhooks" \-H "Authorization: Bearer $BEEKON_TOKEN" \-H "Content-Type: application/json" \-d '{"endpoint_url": "https://hooks.example.com/beekon","event_types": ["geofence.enter", "geofence.exit"]}' | tee webhook.jsonThe response’s
secret(whsec_…) signs every delivery. It is shown only once, so keepwebhook.jsonuntil you have stored it. -
Upload two locations inside the fence, 30 seconds apart. The second one confirms the enter (what produces a geofence event).
Terminal window jq -n --arg a "$(uuidgen | tr A-Z a-z)" --arg b "$(uuidgen | tr A-Z a-z)" '{schema_version: 1,device: {install_id: "quickstart-device"},session_id: "quickstart",segments: [{locations: [{id: $a, timestamp: (now - 60 | todate), latitude: 12.9716, longitude: 77.5946,accuracy: 5, trigger: "interval", motion: "stationary", is_mock: false},{id: $b, timestamp: (now - 30 | todate), latitude: 12.9716, longitude: 77.5946,accuracy: 5, trigger: "interval", motion: "stationary", is_mock: false}]}]}' > batch.jsoncurl -s -o /dev/null -w '%{http_code}\n' -X POST "$BEEKON_API/v1/ingest" \-H "Authorization: Bearer $BEEKON_TOKEN" \-H "Content-Type: application/json" \--data-binary @batch.json200means the locations are stored.quickstart-devicenow appears in Devices and counts towards this month’s monthly active users like any device. -
Read the event.
Terminal window curl -s -G "$BEEKON_API/v1/events" -H "Authorization: Bearer $BEEKON_TOKEN" \--data-urlencode "limit=500" \| jq '.events[] | select(.type == "geofence.enter")'{"id": "019e9f61-1400-7000-8000-0000000000e1","type": "geofence.enter","detected_at": "2026-11-01T06:40:12.000Z","device": {"install_id": "quickstart-device", "session_id": "quickstart"},"evidence": "track","geofence": {"id": "0199b2c5-7d10-7a3e-9c44-1e2f3a4b5c6d"},"location": {"accuracy_m": 5,"latitude": 12.9716,"longitude": 77.5946,"recorded_at": "2026-11-01T06:40:10.000Z"},"occurred_at": "2026-11-01T06:40:10.000Z","project_id": "019000b0-0000-7000-8000-0000000000b1"}The same event arrives at your webhook as a signed
POST. In thein1region it follows the upload within seconds; elsewhere it can take longer.
To clean up, delete the fence and the webhook:
curl -s -X DELETE "$BEEKON_API/v1/geofences/$FENCE_ID" \ -H "Authorization: Bearer $BEEKON_TOKEN"curl -s -X DELETE "$BEEKON_API/v1/webhooks/$(jq -r .webhook.id webhook.json)" \ -H "Authorization: Bearer $BEEKON_TOKEN"- Devices and Trips: the rest of the read surface.
- Webhooks: verify signatures, retries, and the delivery format.
- Events: every event type, and the feed for catching up.
- Errors and Rate limits: what to retry, and how.
openapi.yaml: generate a client.