Skip to main content

Quick Start

Get started with SpatialFlow in under 5 minutes. This guide will walk you through creating your first geofence, setting up a workflow, and receiving your first webhook event.

Prerequisites​

Before you begin, you'll need:

  • A SpatialFlow account (sign up here)
  • An API key or JWT token
  • Basic knowledge of REST APIs
  • A tool to make HTTP requests (curl, Postman, or your favorite HTTP client)

Step 1: Get Your API Credentials​

  1. Log in to your SpatialFlow Dashboard
  2. Navigate to Settings → API Keys
  3. Click Generate New API Key
  4. Copy your API key (you won't see it again!)
export SPATIALFLOW_API_KEY="your-api-key-here"
# Login to get a JWT token
curl -X POST https://api.spatialflow.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password"
  }'

# Response includes access_token
export SPATIALFLOW_TOKEN="your-jwt-token-here"

Step 2: Create Your First Geofence​

Let's create a polygon geofence around a location (a simple square in this example):

curl -X POST https://api.spatialflow.io/api/v1/geofences/ \
  -H "X-API-KEY: $SPATIALFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Geofence",
    "description": "A test geofence around my office",
    "geometry": {
      "type": "Polygon",
      "coordinates": [[
        [-122.4200, 37.7745],
        [-122.4200, 37.7753],
        [-122.4188, 37.7753],
        [-122.4188, 37.7745],
        [-122.4200, 37.7745]
      ]]
    },
    "metadata": {
      "location": "San Francisco Office"
    }
  }'

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My First Geofence",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [-122.4200, 37.7745],
      [-122.4200, 37.7753],
      [-122.4188, 37.7753],
      [-122.4188, 37.7745],
      [-122.4200, 37.7745]
    ]]
  },
  "created_at": "2025-11-09T10:00:00Z"
}

Save the id value - you'll need it for the next step!

Step 3: Create a Workflow​

Now let's create a workflow that triggers when a device enters your geofence:

curl -X POST https://api.spatialflow.io/api/v1/workflows \
  -H "X-API-KEY: $SPATIALFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Office Entry Notification",
    "description": "Send webhook when device enters office",
    "nodes": [
      {
        "id": "trigger-1",
        "type": "trigger",
        "data": {
          "triggerType": "geofence_enter",
          "label": "Geofence Entry",
          "config": {
            "geofence_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
          }
        }
      },
      {
        "id": "action-1",
        "type": "action",
        "data": {
          "actionType": "webhook",
          "label": "HTTP Request",
          "config": {
            "url": "https://webhook.site/your-unique-url",
            "method": "POST",
            "headers": {"Content-Type": "application/json"},
            "body": {
              "event_type": "{{trigger.event_type}}",
              "device": "{{trigger.device_name}}",
              "geofence": "{{trigger.geofence_name}}",
              "timestamp": "{{trigger.timestamp}}"
            }
          }
        }
      }
    ],
    "edges": [
      {"id": "edge-1", "source": "trigger-1", "target": "action-1"}
    ]
  }'
Use webhook.site for Testing

Go to webhook.site to get a free test webhook URL. It lets you inspect incoming webhook payloads in real-time!

Step 4: Test with a Device Location​

Before sending a location update, you must first register a device via POST /api/v1/devices/ to obtain a device UUID. See Devices for full registration details.

Then start a tracking shift on the device (location updates require an active shift):

curl -X POST https://api.spatialflow.io/api/v1/devices/{device_uuid}/start-shift \
  -H "X-API-KEY: $SPATIALFLOW_API_KEY"

Send a device location update to trigger your workflow using the device UUID (id) returned from POST /api/v1/devices/:

curl -X POST https://api.spatialflow.io/api/v1/devices/{device_uuid}/location \
  -H "X-API-KEY: $SPATIALFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 37.7749,
    "longitude": -122.4194,
    "timestamp": "2025-11-09T10:05:00Z",
    "accuracy": 10
  }'

Step 5: Receive Your First Webhook​

Check your webhook.site URL — you should see a payload matching the body template, with template variables resolved:

{
  "event_type": "entry",
  "device": "My Device",
  "geofence": "My First Geofence",
  "timestamp": "2025-11-09T10:05:00Z"
}

🎉 Congratulations! You've successfully:

  • ✅ Created a geofence
  • ✅ Set up a workflow
  • ✅ Received a webhook event

Next Steps​

Now that you've completed the basics, explore more advanced features:

  • Geofences - Create complex polygons and manage geofence groups
  • Workflows - Build multi-step automations with conditional logic
  • Webhooks - Configure retries, authentication, and error handling
  • Devices - Track and manage location-enabled devices
  • API Reference - Explore the full API documentation

Common Use Cases​

Ready to build something real? Check out these guides:

More use case guides coming soon!

Need Help?​