# Geofences

> List, create, read, replace and delete geofences over the server API: circles and polygons, notifications, the pass-through and lost-contact policies, and how events are produced.

Source: https://docs.getbeekon.com/api/geofences/

These endpoints create and manage your project’s geofences from your backend. A geofence is a circle or polygon. The server checks every device’s uploaded locations against it and records [`geofence.enter`, `geofence.exit` and `geofence.dwell` events](https://docs.getbeekon.com/api/events/#geofence-events); devices receive the fences automatically. For the SDK side, see [Geofencing](https://docs.getbeekon.com/guide/geofencing/).

## POST `/v1/geofences`

**Scope:** `geofences:write` · Creates a geofence.

```sh
curl -s -X POST https://api.in1.getbeekon.com/v1/geofences \
  -H "Authorization: Bearer $BEEKON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HQ",
    "geometry": {
      "type": "circle",
      "center": {"latitude": 12.9716, "longitude": 77.5946},
      "radius_meters": 150
    },
    "notify_on_entry": true,
    "notify_on_exit": false
  }'
```

**Body**

| Member            | Type    | Required | Rule                                                                                 |
| ----------------- | ------- | -------- | ------------------------------------------------------------------------------------ |
| `name`            | string  | yes      | 1 to 200 bytes, not only whitespace, no control characters.                          |
| `geometry`        | object  | yes      | See [Geometry](#geometry).                                                           |
| `notify_on_entry` | boolean | yes      |                                                                                      |
| `notify_on_exit`  | boolean | yes      |                                                                                      |
| `notification`    | object  | no       | See [Notifications](#notifications). `null` is the same as leaving it out.           |
| `pass_through`    | string  | no       | `off` or `on`; absent or `null` is `off`. See [Fence policies](#fence-policies).     |
| `on_unreachable`  | string  | no       | `none` or `exit`; absent or `null` is `none`. See [Fence policies](#fence-policies). |

No other member is accepted. **Response** `201`: `{"geofence":{…}}`, identical to what a following `GET` returns.

## GET `/v1/geofences`

**Scope:** `geofences:read` · Lists the project’s geofences, [paged](https://docs.getbeekon.com/api/pagination/), ordered by `id`.

```sh
curl -s -G https://api.in1.getbeekon.com/v1/geofences \
  -H "Authorization: Bearer $BEEKON_TOKEN" \
  --data-urlencode "limit=100"
```

| Parameter | Required | Meaning                                            |
| --------- | -------- | -------------------------------------------------- |
| `limit`   | no       | 1–500, default 100.                                |
| `cursor`  | no       | The previous page’s `next_cursor` (prefix `gf1_`). |

**Response** `200`: `{"geofences":[{…}],"next_cursor":null}`.

## GET `/v1/geofences/{fence_id}`

**Scope:** `geofences:read`

```sh
curl -s \
  https://api.in1.getbeekon.com/v1/geofences/0199b2c5-7d10-7a3e-9c44-1e2f3a4b5c6d \
  -H "Authorization: Bearer $BEEKON_TOKEN"
```

**Response** `200`: `{"geofence":{…}}`.

## PUT `/v1/geofences/{fence_id}`

**Scope:** `geofences:write` · **Replaces** the geofence: the body is the same as for `POST`, and every member is set from it. Leaving `notification` out removes the fence’s notification, and leaving `pass_through` or `on_unreachable` out resets it to `off` or `none`.

```sh
curl -s -X PUT \
  https://api.in1.getbeekon.com/v1/geofences/0199b2c5-7d10-7a3e-9c44-1e2f3a4b5c6d \
  -H "Authorization: Bearer $BEEKON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HQ (north gate)",
    "geometry": {
      "type": "circle",
      "center": {"latitude": 12.9721, "longitude": 77.5946},
      "radius_meters": 200
    },
    "notify_on_entry": true,
    "notify_on_exit": true
  }'
```

**Response** `200`: `{"geofence":{…}}`. The body is validated before the id is looked up, so a bad body is a `400` even for an unknown id.

## DELETE `/v1/geofences/{fence_id}`

**Scope:** `geofences:write` · Deletes the geofence. Devices drop it when they next receive geofence updates.

```sh
curl -s -X DELETE \
  https://api.in1.getbeekon.com/v1/geofences/0199b2c5-7d10-7a3e-9c44-1e2f3a4b5c6d \
  -H "Authorization: Bearer $BEEKON_TOKEN"
```

**Response** `204`, no body. Deleting it again is `404 not found`.

## The geofence object

```json
{
  "id": "0199b2c5-7d10-7a3e-9c44-1e2f3a4b5c6d",
  "created_at": "2026-10-07T06:30:00.000Z",
  "geometry": {
    "type": "circle",
    "center": {"latitude": 12.9716, "longitude": 77.5946},
    "radius_meters": 150
  },
  "name": "HQ",
  "notification": {
    "delivery": "local",
    "on_enter": {"body": "Welcome to HQ.", "title": "Arrived"}
  },
  "notify_on_entry": true,
  "notify_on_exit": false,
  "on_unreachable": "none",
  "pass_through": "off",
  "updated_at": "2026-10-07T06:30:00.000Z"
}
```

| Member            | Type    | Presence | Meaning                                                                                                                                                   |
| ----------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | string  | always   | The geofence id, a UUID. Events name the fence by this id.                                                                                                |
| `name`            | string  | always   | Your label.                                                                                                                                               |
| `geometry`        | object  | always   | The area, in its stored form (see [Geometry](#geometry)).                                                                                                 |
| `notify_on_entry` | boolean | always   | Whether devices notify on entering.                                                                                                                       |
| `notify_on_exit`  | boolean | always   | Whether devices notify on leaving.                                                                                                                        |
| `notification`    | object  | when set | The notification devices show on a crossing (see [Notifications](#notifications)).                                                                        |
| `pass_through`    | string  | always   | `off` or `on`. Whether a device that passes through the fence between two locations produces an enter and an exit. See [Fence policies](#fence-policies). |
| `on_unreachable`  | string  | always   | `none` or `exit`. What happens when a device inside the fence becomes unreachable. See [Fence policies](#fence-policies).                                 |
| `created_at`      | string  | always   | When it was created.                                                                                                                                      |
| `updated_at`      | string  | always   | When it was last replaced.                                                                                                                                |

Only live geofences are served. A deleted geofence is gone from every endpoint (`404`), but past events keep its id.

## Geometry

Send one of three shapes. Coordinates are WGS 84 degrees.

```json
{
  "type": "circle",
  "center": {"latitude": 12.9716, "longitude": 77.5946},
  "radius_meters": 150
}
```

```json
{
  "type": "polygon",
  "coordinates": [
    [
      [77.5940, 12.9710],
      [77.5952, 12.9710],
      [77.5952, 12.9722],
      [77.5940, 12.9722],
      [77.5940, 12.9710]
    ]
  ]
}
```

```json
{
  "type": "multipolygon",
  "coordinates": [
    [
      [
        [77.5940, 12.9710],
        [77.5952, 12.9710],
        [77.5952, 12.9722],
        [77.5940, 12.9710]
      ]
    ]
  ]
}
```

* `polygon` and `multipolygon` use GeoJSON coordinates: **`[longitude, latitude]`** order, an outer ring first, then any holes.
* `radius_meters` is a number greater than 0.

The server stores a normalised form and returns it from then on. It makes only these changes: a `polygon` becomes a one-part `multipolygon`; an unclosed ring is closed; consecutive duplicate vertices are collapsed; rings are rewound so outer rings run counter-clockwise and holes clockwise. Coordinate values are never rounded or moved. A circle is returned as sent.

Invalid geometry is **refused, never repaired**:

| `error` (400)             | When                                                                                                                 |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `shape_unknown`           | `type` is not `circle`, `polygon` or `multipolygon`.                                                                 |
| `coordinate_out_of_range` | A latitude outside −90…90 or a longitude outside −180…180, or a circle without a usable centre.                      |
| `radius_not_positive`     | A circle’s `radius_meters` is 0, negative or not a finite number.                                                    |
| `ring_too_few_vertices`   | A ring has fewer than 3 distinct vertices.                                                                           |
| `self_intersection`       | A ring crosses itself, rings of one polygon cross each other, or two parts of a multipolygon overlap.                |
| `hole_outside_shell`      | A hole is not inside its outer ring.                                                                                 |
| `antimeridian_span`       | The geometry’s longitudes span more than 180°. Split it into fences on each side of the antimeridian.                |
| `invalid_geometry`        | `geometry` is not a geometry document at all (for example, a string, or coordinates that are not arrays of numbers). |

## Notifications

A geofence may carry a `notification` that the SDK shows as a native OS notification at the crossing, even offline or with the app closed.

```json
{
  "delivery": "local",
  "on_enter": {
    "title": "Arrived",
    "body": "Welcome to HQ.",
    "importance": "high",
    "deep_link": "myapp://site/hq",
    "data": {"site": "hq"}
  }
}
```

| Member         | Required       | Rule                                                                                  |
| -------------- | -------------- | ------------------------------------------------------------------------------------- |
| `delivery`     | yes            | `local` (the device shows it) or `cloud` (reserved; the device shows nothing).        |
| `on_enter`     | one of the two | Content for entering. Needs `notify_on_entry: true`.                                  |
| `on_exit`      | one of the two | Content for leaving. Needs `notify_on_exit: true`.                                    |
| `….title`      | yes            | A string of at most 100 characters.                                                   |
| `….body`       | yes            | A string of at most 500 characters.                                                   |
| `….importance` | no             | `high` or `default`. Left out, devices treat it as `high`.                            |
| `….deep_link`  | no             | A string of at most 2048 characters, handed to your app on tap.                       |
| `….data`       | no             | A flat object of string values: at most 10 entries and 2048 bytes of keys and values. |

Anything that breaks these rules is `400 invalid_notification`. Send `null` or leave `notification` out for no notification.

## Fence policies

Two members set how the server judges a fence in the two cases where a device’s locations alone can’t show a crossing. Both are optional on input and always present on output.

| Member           | Values         | Default | What it does                                                                                                                                                                                                                                                                                                                                 |
| ---------------- | -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pass_through`   | `off`, `on`    | `off`   | With `on`, a device that crosses the fence between two locations, with neither location inside, still produces a `geofence.enter` and a `geofence.exit`, both with `evidence: interpolated`. Use it for small fences on roads, where a vehicle can be inside for less time than between two locations.                                       |
| `on_unreachable` | `none`, `exit` | `none`  | What happens when a device confirmed inside the fence becomes [unreachable](https://docs.getbeekon.com/api/events/#device-presence-events). `none`: nothing is sent, and the device’s visit becomes **unverified**. `exit`: Beekon sends a `geofence.exit` with `evidence: unreachable`, no `location`, and `occurred_after` set to the device’s last location inside. |

Absent or `null` means the default. On a `PUT`, leaving one out resets it to the default. Any other value is `400 invalid_body`. The fence’s policies stay on the server: devices never receive them.

**A device’s state in a fence** is `outside`, `inside` or `unverified`, the same words the console uses. Under `on_unreachable: none`, a visit becomes unverified when the device becomes unreachable, and stays unverified until the device’s next location: it is still counted as inside, but no dwell is sent for it, and it does not count as something in progress for [presence events](https://docs.getbeekon.com/api/events/#device-presence-events). The device’s next location settles it. A location clearly inside sends nothing, and the visit continues. A location clearly outside is judged as an exit by the usual rules. A `device.reachable` alone does not settle it, because it carries no location. After an `unreachable` exit, the device’s next confirmed inside location starts a new visit with a new `geofence.enter`.

A fence that keeps both defaults never produces `interpolated` or `unreachable` events, so every event for it has a `location`.

## Limits

Each plan sets three geofence limits for a project:

| `error` (409)    | When                                                                                                        |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `quota_fences`   | A create would exceed the plan’s number of geofences per project. Deleting a geofence frees a slot.         |
| `quota_vertices` | The geometry has more distinct vertices (all rings of all parts, after normalisation) than the plan allows. |
| `quota_area`     | The geometry’s area (holes subtracted; a circle is πr²) is larger than the plan allows.                     |

A `PUT` is checked against the vertex and area limits, never the count.

The values depend on your plan. The default vertex limit is 1,000.

The vertex limit is checked **before** the self-intersection and hole checks, which are the expensive part of validation. A geometry over the limit is `409 quota_vertices` even if it also crosses itself; the cheaper checks (shape, coordinate range, ring size, antimeridian) still come first and answer `400`. On a `PUT` to an unknown id, `404 not found` still comes before `quota_vertices`.

## What produces a geofence event

The server is the only judge of a crossing. It reads each device’s admitted locations in recorded order, per geofence, and needs clear evidence before it says the device crossed. [Gated](https://docs.getbeekon.com/api/locations/#admitted-and-gated-locations) locations (mock, inaccurate or impossible) are never evaluated.

**Which side a location is on.** A location counts only when it is clearly on one side: its distance from the fence’s boundary must be at least **20 m** or its own reported accuracy, whichever is larger (the location’s *required distance*). A location closer to the boundary than that is ignored for this fence: it neither enters, exits, nor cancels anything. A location with no accuracy needs the 20 m alone.

**When a crossing is confirmed.**

| Rule                                               | What it means                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **A moving device confirms on one location.**      | A location is *moving* when the device reports a moving activity (walking, running, cycling or driving), or when each of the device’s last two steps covered at least 25 m (or twice the larger accuracy of its two locations, if that is more) at 1 m/s or faster. An enter confirms on the first clear inside location that is moving. An exit is stricter: it confirms on a moving location at least **twice** its required distance outside (40 m with the 20 m floor).                                                                                                               |
| **Otherwise, a second location 10 seconds later.** | The first clear location on the new side starts the crossing; the next clear location on the same side, recorded at least **10 seconds** after it, confirms it. A clear location back on the old side in the meantime cancels it. The 10 seconds only rule out a repeated location; there is no other wait.                                                                                                                                                                                                                                                                               |
| **The device’s own report can confirm at once.**   | When the SDK reports a crossing in the same upload, an admitted location within **120 seconds** of it (on the device’s clock) that does not contradict it confirms the crossing there, with `evidence: corroborated`. For an enter, that is the earliest such location not clearly outside, and only if no later one in the window is clearly outside; for an exit, the latest location in the window, and only if it is not clearly inside. A device report never confirms anything alone, never overrides a location clearly on the other side, and never makes a gated location count. |
| **A device starts outside every fence.**           | Its first confirmed inside is a `geofence.enter`, even when the device was already inside when it began sending locations.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

A confirmed enter or exit has `evidence: track` (or `corroborated`), its `occurred_at` is the confirming location’s recorded time, and that location is the event’s `location`.

**Pass-through** (`pass_through: on` only). When two consecutive locations at most **60 seconds** apart are both clearly outside, and the straight line between them runs through the fence at least **10 m** deeper than the larger of their two required distances, the server sends a `geofence.enter` and a `geofence.exit` with `evidence: interpolated`. Their `occurred_at` values are the instants the line goes in and comes out (sampled every 100 ms), and both carry the second location as `location`.

**Lost contact.** When a device confirmed inside becomes [unreachable](https://docs.getbeekon.com/api/events/#device-presence-events), the fence’s `on_unreachable` decides: an unverified visit and no event (`none`), or a `geofence.exit` with `evidence: unreachable` (`exit`). See [Fence policies](#fence-policies).

**Dwell.** A dwell fires once per visit, **5 minutes** after the confirmed enter, while the device is still inside (`dwell_seconds: 300`): on the device’s next location after that time, or within about a minute without one, so a device that went quiet inside a fence still dwells. It does not fire by itself for a visit that is unverified, or for a device that became unreachable before the 5 minutes were up.

**Late locations.** A location recorded before the newest one already evaluated for the device never changes its current state. Late locations up to 72 hours behind can still produce a complete visit, sent with `late: true`. See [late locations](https://docs.getbeekon.com/api/events/#late-locations).

**Every source is evaluated alike.** Locations from the SDK and locations uploaded through [`POST /v1/ingest`](https://docs.getbeekon.com/api/ingest/) are evaluated the same way. Lost contact applies only to devices running the SDK, because only they have presence.

**How soon an event arrives.** The server evaluates each upload right after accepting it, so in the `in1` region the event follows the upload that carries the confirming location within seconds. In other regions the evaluation can wait until the region next handles traffic. Beekon’s target for a healthy device, tracking and online, is under 2 minutes from the crossing to the event. SDK 0.6.0 and later upload at once when a location crosses a fence or comes near one, and when the OS raises a geofence alert (see [Near a fence](https://docs.getbeekon.com/guide/geofencing/#near-a-fence-beekon-cloud)). With SDK 0.5.0 only the OS alert does that; otherwise the event follows the crossing by up to the [upload interval](https://docs.getbeekon.com/api/remote-config/#sync): 5 minutes by default (`sync.interval_seconds: 300`, never shorter than 60 seconds), on screen or in the background. Set `sync.sync_threshold` to upload sooner. Each event’s `detected_at` shows when the server produced it.

**Known limits.**

* **A dead or force-stopped phone can’t be located.** No design can say where a phone is once it stops sending. The server’s answer is that the device is [unreachable](https://docs.getbeekon.com/api/events/#device-presence-events), once its deadline passes (minutes for a moving device on SDK 0.6.0 or later, 12 hours by default otherwise), and the fence’s `on_unreachable` decides what you hear.
* **An iOS app the user force-quits may send nothing.** iOS does not relaunch it for a fence, so there may be no location to judge, and the decision falls to presence as above.
* **A faked location on a rooted or jailbroken device** can pass the mock-location gate and is judged like any other track. `evidence: track` says what the server concluded from the locations it received, not that they are genuine. A location’s `trust_tier` says whether it came from an install that passed [device attestation](https://docs.getbeekon.com/guide/integrity/), and [Require attestation](https://docs.getbeekon.com/guide/integrity/#require-attestation) refuses uploads from installs that haven’t, rooted Android phones among them.

These values are the same for every project today, and may be tuned. A test drive that wants an event should go well inside the fence (more than the required distance past the boundary), and a slow one should record two locations at least 10 seconds apart on each side.

## Errors

| Status | `error`                                                   | When                                                                                                                                                                                                                     |
| ------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 400    | `invalid_body`                                            | Not one JSON object; a required member missing or `null`; a member of the wrong type; an unknown member; a repeated key; a `pass_through` or `on_unreachable` value that is not one of its tokens; or a body over 1 MiB. |
| 400    | `invalid_name`                                            | `name` empty, only whitespace, over 200 bytes, or containing a control character.                                                                                                                                        |
| 400    | `invalid_geometry`, a geometry reason above               | Bad geometry.                                                                                                                                                                                                            |
| 400    | `invalid_notification`                                    | A notification that breaks the rules above.                                                                                                                                                                              |
| 400    | `limit must be an integer in [1, 500]` · `invalid_cursor` | Bad paging on the list.                                                                                                                                                                                                  |
| 401    | `missing bearer token` · `invalid session token`          | No valid session.                                                                                                                                                                                                        |
| 403    | `server credentials required`                             | The token was minted from an SDK key.                                                                                                                                                                                    |
| 403    | `insufficient scope`                                      | The key lacks `geofences:read` (reads) or `geofences:write` (writes).                                                                                                                                                    |
| 404    | `not found`                                               | Unknown, deleted, foreign or malformed id.                                                                                                                                                                               |
| 409    | `quota_fences` · `quota_vertices` · `quota_area`          | A plan limit.                                                                                                                                                                                                            |
| 500    | `internal error`                                          | A failure on our side.                                                                                                                                                                                                   |
