> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Geofence

> Add a place your mobile app watches

Creates a geofence: a circle the Sequenzy mobile SDKs register with the phone's location services. When a signed-in user enters, leaves or stays in it, Sequenzy records `app.geofence_entered`, `app.geofence_exited` or `app.geofence_dwelled` on their contact. See [Geofences](https://docs.sequenzy.com/concepts/geofences.md).

Apps pick up a new geofence on their next refresh. A workspace holds at most 10,000. Requires the `geofences:write` scope. Unknown fields are ignored.

## Request

**name** `string` *required*

Geofence name, up to 120 characters.

**latitude** `number` *required*

Center latitude, from -90 to 90.

**longitude** `number` *required*

Center longitude, from -180 to 180.

**radiusMeters** `integer` *required*

Radius in meters, from 100 to 10,000. Phones trigger small regions late or not at all, so use 200 or more.

**dwellSeconds** `integer | null` (default: null)

Record `app.geofence_dwelled` once a contact has stayed inside this many seconds, from 60 to 14,400. `null` turns dwell off.

**cooldownSeconds** `integer` (default: 3600)

How long a repeat of the same transition by the same contact is ignored, from 300 to 604,800 seconds.

**group** `string | null`

Optional group label such as `stores`: letters, numbers, spaces, dots, dashes and underscores, up to 64 characters. Triggers and segments can target a whole group.

**externalId** `string | null`

Your own ID for the place, up to 128 characters and unique in your workspace. Imports match rows by it.

**active** `boolean` (default: true)

Paused geofences are not sent to apps and record nothing.

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/geofences" \
  -H "Authorization: Bearer $SEQUENZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Soho store",
    "latitude": 51.5136,
    "longitude": -0.1365,
    "radiusMeters": 200,
    "dwellSeconds": 600,
    "group": "stores",
    "externalId": "store-0042"
  }'
```

## Response

Returns `201` with the geofence.

**geofence** `object`

**properties**

**id** `string`

Geofence ID.

**name** `string`

Name.

**externalId** `string | null`

Your ID for the place.

**group** `string | null`

Group label.

**latitude** `number`

Center latitude.

**longitude** `number`

Center longitude.

**radiusMeters** `integer`

Radius in meters.

**dwellSeconds** `integer | null`

Dwell time, or `null` when off.

**cooldownSeconds** `integer`

Cooldown per contact and transition.

**active** `boolean`

Whether apps watch it.

**createdAt** `string`

ISO 8601 creation time.

**updatedAt** `string`

ISO 8601 time of the last change.

## Errors

| Status | When |
| - | - |
| 400 | A field is out of range or has the wrong type. The message names the field, for example `radiusMeters must be between 100 and 10000`. |
| 401 | The API key is missing or invalid. |
| 403 | The key lacks the required scope or has no company selected. |
| 409 | Another geofence already uses this `externalId`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.