Geofences

Geofences define geographic boundaries for time tracking. Users can be required to clock in/out within geofenced areas, and automatic actions can be triggered when users exit.

Endpoints

Method	Endpoint	Description
GET	/time-clock/v1/time-clocks/{timeClockId}/geofences	Get all geofences
POST	/time-clock/v1/time-clocks/{timeClockId}/geofences	Create geofences
GET	/time-clock/v1/time-clocks/{timeClockId}/geofences/{fenceId}	Get a geofence
DELETE	/time-clock/v1/time-clocks/{timeClockId}/geofences/{fenceId}	Delete a geofence

Geofence Properties

Property	Type	Description
id	string	Unique identifier
name	string	Display name (required, min 1 character)
isEnabled	boolean	Whether the geofence is active (default: true)
fenceSize	integer	Radius in meters (75-1524)
jobIds	array	Associated job IDs (max 100)
onGeofenceExitAction	string	Action when user exits
location	object	GPS coordinates and address

Exit Actions

Action	Description
`noAction`	No automatic action (default)
`sendNotification`	Send notification to user/admin
`autoClockOut`	Automatically clock out the user

Get All Geofences

curl --request GET \
  --url https://api.connecteam.com/time-clock/v1/time-clocks/12345/geofences \
  --header 'X-API-KEY: YOUR_API_KEY'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "geofences": [
      {
        "id": "fence-abc123",
        "name": "Main Office",
        "isEnabled": true,
        "fenceSize": 150,
        "jobIds": ["job-123", "job-456"],
        "onGeofenceExitAction": "sendNotification",
        "location": {
          "address": "123 Main St, New York, NY 10001",
          "latitude": "40.7128",
          "longitude": "-74.0060"
        }
      },
      {
        "id": "fence-def456",
        "name": "Warehouse",
        "isEnabled": true,
        "fenceSize": 300,
        "jobIds": [],
        "onGeofenceExitAction": "autoClockOut",
        "location": {
          "address": "456 Industrial Blvd, Brooklyn, NY 11201",
          "latitude": "40.6892",
          "longitude": "-73.9857"
        }
      }
    ]
  }
}

Create Geofences

Create one or more geofences for a time clock.

⚠️
Constraints

Max 1000 geofences per request

Max 100 job IDs per geofence

Fence size: 75-1524 meters

Latitude/longitude must be numeric strings

Request Body

Field	Type	Required	Description
name	string	Yes	Geofence name (min 1 char)
location	object	Yes	GPS coordinates with address
isEnabled	boolean	No	Whether active (default: true)
fenceSize	integer	No	Radius in meters (75-1524)
jobIds	array	Conditional	Job IDs (required if job enforcement is enabled)
onGeofenceExitAction	string	No	Exit action (default: noAction)

Location Object

Field	Type	Required	Description
address	string	Yes	Street address
latitude	string	Yes	Latitude as string (e.g., "40.7128")
longitude	string	Yes	Longitude as string (e.g., "-74.0060")

Example: Create Single Geofence

curl --request POST \
  --url https://api.connecteam.com/time-clock/v1/time-clocks/12345/geofences \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "geofences": [
      {
        "name": "Client Site A",
        "location": {
          "address": "789 Business Park, Chicago, IL 60601",
          "latitude": "41.8781",
          "longitude": "-87.6298"
        },
        "fenceSize": 200,
        "onGeofenceExitAction": "sendNotification"
      }
    ]
  }'

Example: Create with Job Association

curl --request POST \
  --url https://api.connecteam.com/time-clock/v1/time-clocks/12345/geofences \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "geofences": [
      {
        "name": "Construction Site",
        "location": {
          "address": "100 Build Ave, Houston, TX 77001",
          "latitude": "29.7604",
          "longitude": "-95.3698"
        },
        "fenceSize": 500,
        "jobIds": ["job-construction-001"],
        "onGeofenceExitAction": "autoClockOut"
      }
    ]
  }'

Example: Bulk Create

async function createGeofences(timeClockId, sites) {
  const geofences = sites.map(site => ({
    name: site.name,
    location: {
      address: site.address,
      latitude: String(site.lat),
      longitude: String(site.lng)
    },
    fenceSize: site.radius || 150,
    jobIds: site.jobIds || [],
    onGeofenceExitAction: 'sendNotification'
  }));

  const response = await fetch(
    `https://api.connecteam.com/time-clock/v1/time-clocks/${timeClockId}/geofences`,
    {
      method: 'POST',
      headers: {
        'X-API-KEY': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ geofences })
    }
  );

  return response.json();
}

// Usage
await createGeofences(12345, [
  { name: 'Site A', address: '123 A St', lat: 40.7128, lng: -74.0060, radius: 200 },
  { name: 'Site B', address: '456 B Ave', lat: 40.7145, lng: -74.0055, radius: 150 }
]);

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "geofences": [
      {
        "fenceId": "fence-new123",
        "name": "Client Site A"
      }
    ]
  }
}

Delete Geofence

Remove a geofence from a time clock.

curl --request DELETE \
  --url https://api.connecteam.com/time-clock/v1/time-clocks/12345/geofences/fence-abc123 \
  --header 'X-API-KEY: YOUR_API_KEY'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {}
}

Error Responses

400 Bad Request

Invalid coordinates:

{
  "detail": ["GeoFence 'Site A' has invalid latitude or longitude values. They must be numeric strings."]
}

Jobs not in time clock:

{
  "detail": ["jobs: ['job-invalid'] not in the required time clock"]
}

Jobs required but missing:

{
  "detail": ["Job IDs are required based on the account configuration."]
}

404 Not Found

{
  "detail": "Geofence not found"
}

API Reference