Core Concepts

Venues & Zones

Venues are the top-level entity in GuestNetworks — every zone, integration, and event belongs to a venue. Zones sub-divide a venue into named areas for per-area occupancy and flow tracking. This page covers the full REST API for both.

All endpoints require Authorization: Bearer gn_live_sk_.... Get your key →

Venues

Base URL: https://api.guestnetworks.com/api/venues

GET/api/venues

List all venues belonging to the authenticated operator. Supports limit/offset pagination. Returns a data array plus total count.

Request body / params
// Query parameters (all optional)
?limit=50    // default 50, max 200
?offset=0    // default 0
Response
// 200 OK
{
  "data": [
    {
      "id":            "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name":          "Downtown Hotel",
      "timezone":      "America/New_York",
      "address":       "123 Main St, New York, NY",
      "is_active":     true,
      "zone_count":    4,
      "last_event_at": "2026-06-14T18:30:00.000Z",
      "created_at":    "2026-01-15T08:00:00.000Z"
    }
  ],
  "total":  1,
  "limit":  50,
  "offset": 0
}
cURL
curl https://api.guestnetworks.com/api/venues?limit=10 \
  -H "Authorization: Bearer $GN_API_KEY"
POST/api/venues

Create a new venue. timezone must be a valid IANA string. hardware_type is optional and can be updated later by connecting an integration.

Request body / params
{
  "name":          "string — required",
  "timezone":      "string — required, IANA tz (e.g. 'America/New_York')",
  "address":       "string — optional",
  "lat":           "number — optional, WGS84 latitude",
  "lng":           "number — optional, WGS84 longitude",
  "hardware_type": "string — optional ('meraki'|'unifi'|'aruba'|'mywifi'|...)"
}
Response
// 201 Created
{
  "id":          "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name":        "Downtown Hotel",
  "timezone":    "America/New_York",
  "address":     "123 Main St, New York, NY",
  "is_active":   true,
  "operator_id": "op-uuid",
  "created_at":  "2026-06-15T12:00:00.000Z"
}
cURL
curl -X POST https://api.guestnetworks.com/api/venues \
  -H "Authorization: Bearer $GN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":          "Downtown Hotel",
    "timezone":      "America/New_York",
    "address":       "123 Main St, New York, NY",
    "hardware_type": "meraki"
  }'
GET/api/venues/:id

Retrieve a single venue by UUID, including its zones array and active integrations. Returns 404 if the venue is soft-deleted or belongs to another operator.

Response
// 200 OK
{
  "id":        "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name":      "Downtown Hotel",
  "timezone":  "America/New_York",
  "address":   "123 Main St, New York, NY",
  "lat":       40.7128,
  "lng":       -74.0060,
  "is_active": true,
  "zones": [
    {
      "id":       "z-uuid",
      "slug":     "lobby",
      "name":     "Lobby",
      "type":     "area",
      "capacity": 80,
      "is_active":true
    }
  ],
  "integrations": [
    {
      "id":             "i-uuid",
      "connector_type": "meraki",
      "is_active":      true,
      "created_at":     "2026-06-15T12:00:00.000Z"
    }
  ],
  "created_at": "2026-06-15T12:00:00.000Z"
}
cURL
curl "https://api.guestnetworks.com/api/venues/$VENUE_ID" \
  -H "Authorization: Bearer $GN_API_KEY"
PUT/api/venues/:id

Partially update a venue. Send only the fields you want to change. operator_id is immutable.

Request body / params
// All fields optional — include only what changes
{
  "name":          "string",
  "timezone":      "string — IANA tz",
  "address":       "string",
  "lat":           "number",
  "lng":           "number",
  "hardware_type": "string"
}
Response
// 200 OK — full updated venue object
{
  "id":         "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name":       "Downtown Hotel (Renovated)",
  "timezone":   "America/New_York",
  "is_active":  true,
  "updated_at": "2026-06-15T14:00:00.000Z"
}
cURL
curl -X PUT "https://api.guestnetworks.com/api/venues/$VENUE_ID" \
  -H "Authorization: Bearer $GN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Downtown Hotel (Renovated)"}'
DELETE/api/venues/:id

Soft-delete a venue by setting is_active = false. Historical data is preserved. The venue no longer appears in list results.

Response
// 200 OK
{
  "id":         "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "is_active":  false,
  "deleted_at": "2026-06-15T15:00:00.000Z"
}
cURL
curl -X DELETE "https://api.guestnetworks.com/api/venues/$VENUE_ID" \
  -H "Authorization: Bearer $GN_API_KEY"

Zones

Zone endpoints are nested under a venue. Base URL: https://api.guestnetworks.com/api/venues/:venue_id/zones

GET/api/venues/:venue_id/zones

List all zones for a venue. The ownership chain (zone → venue → operator) is verified — a 403 is returned if the venue belongs to a different operator.

Response
// 200 OK
{
  "data": [
    {
      "id":        "z1-uuid",
      "slug":      "lobby",
      "name":      "Lobby",
      "type":      "area",
      "capacity":  80,
      "is_active": true
    },
    {
      "id":        "z2-uuid",
      "slug":      "entrance",
      "name":      "Front Entrance",
      "type":      "entrance",
      "capacity":  null,
      "is_active": true
    }
  ],
  "total": 2
}
cURL
curl "https://api.guestnetworks.com/api/venues/$VENUE_ID/zones" \
  -H "Authorization: Bearer $GN_API_KEY"
POST/api/venues/:venue_id/zones

Create a zone within a venue. slug must be URL-safe and unique within the venue. type determines how occupancy counting is performed.

Request body / params
{
  "slug":     "string — URL-safe ID, e.g. 'main-floor' — unique per venue",
  "name":     "string — display name",
  "type":     "'area' | 'entrance' | 'exit' | 'counter'",
  "capacity": "number — optional, max occupancy for this zone"
}
Response
// 201 Created
{
  "id":         "z-uuid",
  "venue_id":   "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "slug":       "main-floor",
  "name":       "Main Floor",
  "type":       "area",
  "capacity":   120,
  "is_active":  true,
  "created_at": "2026-06-15T12:00:00.000Z"
}
cURL
curl -X POST "https://api.guestnetworks.com/api/venues/$VENUE_ID/zones" \
  -H "Authorization: Bearer $GN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug":     "main-floor",
    "name":     "Main Floor",
    "type":     "area",
    "capacity": 120
  }'
PUT/api/venues/:venue_id/zones/:id

Update a zone. All fields are optional — send only what changes. slug cannot be changed after creation.

Request body / params
// All fields optional
{
  "name":     "string",
  "type":     "'area' | 'entrance' | 'exit' | 'counter'",
  "capacity": "number | null"
}
Response
// 200 OK
{
  "id":        "z-uuid",
  "venue_id":  "venue-uuid",
  "slug":      "main-floor",
  "name":      "Main Floor (Updated)",
  "type":      "area",
  "capacity":  150,
  "is_active": true
}
cURL
curl -X PUT "https://api.guestnetworks.com/api/venues/$VENUE_ID/zones/$ZONE_ID" \
  -H "Authorization: Bearer $GN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Main Floor (Updated)", "capacity": 150}'
DELETE/api/venues/:venue_id/zones/:id

Soft-delete a zone. Historical data is preserved.

Response
// 200 OK
{
  "id":         "z-uuid",
  "is_active":  false,
  "deleted_at": "2026-06-15T15:00:00.000Z"
}
cURL
curl -X DELETE "https://api.guestnetworks.com/api/venues/$VENUE_ID/zones/$ZONE_ID" \
  -H "Authorization: Bearer $GN_API_KEY"

Integrations

Connect hardware to a venue. Nested under the venue. Base URL: https://api.guestnetworks.com/api/venues/:venue_id/integrations

GET/api/venues/:venue_id/integrations

List all hardware integrations for a venue. Sensitive config fields (API keys, passwords) are redacted — value replaced with "gn_redacted".

Response
// 200 OK
{
  "data": [
    {
      "id":             "i-uuid",
      "venue_id":       "v-uuid",
      "connector_type": "meraki",
      "is_active":      true,
      "config": {
        "api_key":        "gn_redacted",
        "org_id":         "553998",
        "webhook_secret": "gn_redacted"
      },
      "created_at": "2026-01-15T08:00:00.000Z"
    }
  ],
  "total": 1
}
cURL
curl "https://api.guestnetworks.com/api/venues/$VENUE_ID/integrations" \
  -H "Authorization: Bearer $GN_API_KEY"
POST/api/venues/:venue_id/integrations

Connect a hardware system to a venue. The request body is a discriminated union on connector_type. Credentials are encrypted at rest with AES-256-GCM.

Request body / params
// Meraki
{ "type": "meraki", "api_key": "string", "org_id": "string", "webhook_secret"?: "string" }

// UniFi
{ "type": "unifi", "controller_url": "https://...", "username": "string",
  "password": "string", "site"?: "string" }

// Aruba
{ "type": "aruba", "client_id": "string", "client_secret": "string",
  "base_url": "https://...", "customer_id": "string" }

// MyWiFi
{ "type": "mywifi", "api_key": "string", "location_id": "string" }

// Square
{ "type": "square", "access_token": "string", "location_id": "string" }

// Density
{ "type": "density", "api_key": "string" }

// Verkada
{ "type": "verkada", "api_key": "string", "org_id": "string" }
Response
// 201 Created
{
  "id":             "i-uuid",
  "venue_id":       "v-uuid",
  "connector_type": "meraki",
  "is_active":      true,
  "created_at":     "2026-06-15T12:00:00.000Z"
}
cURL
curl -X POST "https://api.guestnetworks.com/api/venues/$VENUE_ID/integrations" \
  -H "Authorization: Bearer $GN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type":    "meraki",
    "api_key": "'$MERAKI_API_KEY'",
    "org_id":  "553998"
  }'
DELETE/api/venues/:venue_id/integrations/:id

Remove an integration from a venue. The connector config (credentials) is deleted; historical event data is retained.

Response
// 200 OK
{
  "id":         "i-uuid",
  "is_active":  false,
  "deleted_at": "2026-06-15T16:00:00.000Z"
}
cURL
curl -X DELETE "https://api.guestnetworks.com/api/venues/$VENUE_ID/integrations/$INTEGRATION_ID" \
  -H "Authorization: Bearer $GN_API_KEY"

Next steps