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 "Authorization: Bearer $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": "gf_abc123xyz",
  "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:

Simplified Example

The example below uses a simplified payload format for readability. The actual API uses a nodes and edges format. See Create Your First Workflow for the full API schema.

curl -X POST https://api.spatialflow.io/api/v1/workflows \
  -H "Authorization: Bearer $SPATIALFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Office Entry Notification",
    "description": "Send webhook when device enters office",
    "active": true,
    "trigger": {
      "type": "geofence_entry",
      "geofence_id": "gf_abc123xyz"
    },
    "actions": [
      {
        "type": "webhook",
        "config": {
          "url": "https://webhook.site/your-unique-url",
          "method": "POST",
          "headers": {
            "Content-Type": "application/json"
          }
        }
      }
    ]
  }'
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.

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

curl -X POST https://api.spatialflow.io/api/v1/devices/{device_uuid}/location \
  -H "Authorization: Bearer $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 like this:

{
  "event": "geofence_entry",
  "geofence": {
    "id": "gf_abc123xyz",
    "name": "My First Geofence"
  },
  "device": {
    "id": "123e4567-e89b-12d3-a456-426614174000"
  },
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "timestamp": "2025-11-09T10:05:00Z"
  },
  "workflow": {
    "id": "wf_xyz789",
    "name": "Office Entry Notification"
  },
  "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?​