InstaAlert Engine™ — Developer Portal

What is InstaAlert Engine?

The InstaAlert Engine is the orchestration layer that routes events between your systems — not another device or application.

InstaAlert Engine is a programmable orchestration platform for campus and enterprise infrastructure. Register any device — screens, PA systems, door controllers, HVAC, WiFi access points, sensors — and coordinate them based on location and capability.

InstaAlert turns device interactions into programmable APIs so your systems can respond without network reconfiguration.

Start Building Try the Sandbox

✓

No networking changes required

✓

No proprietary hardware

✓

No vendor lock-in

Location-Aware

Hierarchical location model: Tenant → Campus → Building → Floor → Zone → Device. Events route to devices based on where they are.

Capability-Based

Devices register what they can do. The engine routes events to devices that can respond — display alerts, unlock doors, adjust HVAC, announce messages.

Multi-Tenant Isolated

Each organization is completely isolated. API keys control access. No network-level segmentation required.

Vendor Agnostic

Any device with HTTP or webhook capability can integrate. No proprietary protocols. Standard REST APIs.

Before You Begin: Environment Mapping

Set up your location hierarchy before integrating devices

Location Hierarchy

InstaAlert uses a graph-based location model. Before sending alerts or registering devices, map your customer's physical environment:

# Location Hierarchy
Tenant (your customer)
  └── Campus (schoolCode)
        └── Building
              └── Floor (optional but recommended)
                    └── Room/Zone (optional)
                          └── Device
        

What's Required vs Optional?

Planning

Element	Required?	Notes
`schoolCode`	Required	Your customer's unique identifier
Building	Required	At least one building per campus
Floor	Recommended	Enables floor-specific alerts and evacuation maps
Room/Zone	Optional	For granular device placement
Device	Optional	Screens, sensors, alarms mapped to locations

Validation Rules

API Enforcement

The API enforces location consistency with structured error responses:

Building must exist under schoolCode
Floor must belong to the building
Devices must be mapped to valid locations

# Example error when building doesn't exist:
{
  "error": "Not Found",
  "message": "Building \"Unknown\" not found in school \"DEMO\"",
  "code": "BUILDING_NOT_FOUND",
  "field": "buildingCode"
}
          

Quickstart: Your First API Call

Get up and running in under 5 minutes

Step 1: Get Your API Key

Authentication

Use the sandbox API key for testing, or contact us for a production key.

# Sandbox API Key (500 calls/month, demo data)
API_KEY="sk_sandbox_-4VJVTq4Jn5ppP1GXcGsAfCeH-XvpV06"

# Base URL
BASE_URL="https://your-domain.replit.app/api/v1"
          

Step 2: Send an Alert

POST /api/v1/alerts

Send an alert to all screens in a building or across the entire campus.

curl -X POST https://your-domain.replit.app/api/v1/alerts \
  -H "Authorization: Bearer sk_sandbox_-4VJVTq4Jn5ppP1GXcGsAfCeH-XvpV06" \
  -H "Content-Type: application/json" \
  -d '{
    "schoolCode": "DEMO",
    "alertType": "fire",
    "message": "Fire alarm activated - evacuate immediately",
    "buildingCode": "MAIN"
  }'
          

Step 3: Register a Device

POST /api/v1/devices/register

Device setup is a two-step process: Register, then Map to a location.

# Step 3a: Register the device
curl -X POST https://your-domain.replit.app/api/v1/devices/register \
  -H "Authorization: Bearer sk_sandbox_-4VJVTq4Jn5ppP1GXcGsAfCeH-XvpV06" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceType": "screen",
    "deviceName": "Lobby Display",
    "deviceModel": "Samsung 55 inch"
  }'

# Response includes deviceKey for next step:
{ "device": { "deviceKey": "dev_abc123", "status": "pending" } }
          

Step 4: Map Device to Location

POST /api/v1/devices/:deviceKey/map

Map the device to a building (get buildingId from the buildings API first).

curl -X POST https://your-domain.replit.app/api/v1/devices/dev_abc123/map \
  -H "Authorization: Bearer sk_sandbox_-4VJVTq4Jn5ppP1GXcGsAfCeH-XvpV06" \
  -H "Content-Type: application/json" \
  -d '{
    "buildingId": "uuid-from-buildings-api",
    "floorId": "optional-floor-uuid"
  }'

# Then activate:
curl -X POST https://your-domain.replit.app/api/v1/devices/dev_abc123/activate \
  -H "Authorization: Bearer sk_sandbox_-4VJVTq4Jn5ppP1GXcGsAfCeH-XvpV06"
          

OneBadge powered by InstaAlert

Unified visitor and access management for any venue

🎫 One QR. Any Entry Type.

OneBadge turns any venue into a smart entry point. Create QR codes for visitors, parking, concerts, contractors, patients, or any access type you need.

Visitors Parking Concerts Contractors Patients + Custom

Key Features

Photo capture — Visitor photos on digital badges
License plates — Track vehicles for parking programs
Phone verification — Verify badges from any device
Venmo payments — Honor-pay for parking, tickets, events
Real-time alerts — Know who's on-site during emergencies
CSV exports — Activity reports for compliance

Connects to Real-Time Alerts

During an emergency, OneBadge data flows into InstaAlert. Staff instantly know who's checked in, where visitors are located, and can account for everyone on campus. One platform. Complete situational awareness.

🏫

Schools

Visitor check-in

🏟️

Stadiums

Ticket scanning

🅿️

Parking

Plate tracking + pay

🏥

Healthcare

Patient intake

API Reference

Core endpoints for device orchestration

Method	Endpoint	Description
POST	`/api/v1/alerts`	Send alert to screens (campus-wide or building-specific)
POST	`/api/v1/alerts/clear`	Clear active alert and restore normal display
GET	`/api/v1/alerts/history/:schoolCode`	Retrieve alert history for a school
POST	`/api/v1/devices`	Register a device with location and capabilities
GET	`/api/v1/devices/:deviceKey`	Get device details and status
GET	`/api/v1/maps/screen/:schoolCode/:screenId`	Get evacuation map for a specific screen location
GET	`/api/v1/buildings`	List all buildings in a campus
GET	`/api/v1/buildings/:id/floors`	Get floors for a building
GET	`/api/v1/beap`	Get Building Emergency Action Plans
GET	`/api/v1/dcp`	Get Department Continuity Plans
GET	`/api/v1/procedures`	Get bundled emergency procedures by location/alert type
POST	`/api/v1/visits`	Record visitor check-in for a building
GET	`/api/v1/visits`	List visitors for a building (with filters)
POST	`/api/v1/visits/:id/checkout`	Record visitor check-out
GET	`/api/v1/visits/building/:id/stats`	Get visitor statistics for a building
OneBadge APIs (Access Programs + Visits)
POST	`/api/v1/access-programs`	Create access program (visitors, parking, tickets, contractors)
GET	`/api/v1/access-programs`	List access programs for a building
GET	`/api/v1/access-programs/:id`	Get program details with stats
PUT	`/api/v1/access-programs/:id`	Update program settings (price, payment, etc.)
POST	`/api/v1/access-programs/:id/toggle`	Enable/disable a program
GET	`/api/v1/access-programs/:id/stats`	Get revenue and usage statistics

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer sk_live_your_api_key

Error Codes Reference

Structured error responses for programmatic handling and AI agents

Consistent Error Format

All API errors return a structured response with error, message, and code. This enables AI agents and automation to reason about next steps.

{
  "error": "Not Found",
  "message": "School with code \"INVALID\" not found",
  "code": "SCHOOL_NOT_FOUND",
  "field": "schoolCode"
}
        

Code	Meaning	Action
`SCHOOL_NOT_FOUND`	schoolCode doesn't exist	Create the school first or check spelling
`BUILDING_NOT_FOUND`	Building doesn't exist in school	Create building or verify names
`CAMPUS_NOT_FOUND`	Campus doesn't exist	Verify campus exists
`DEVICE_NOT_FOUND`	Device key is invalid	Check the device key
`DEVICE_NOT_MAPPED`	Device needs location before activation	Map device to a building first
`MISSING_REQUIRED_FIELDS`	Required fields not provided	Check the `fields` object for details
`ACCESS_DENIED`	No permission for this resource	Check your API key permissions
`INVALID_PIN`	Authentication failed	Verify your API key or PIN
`AUTH_REQUIRED`	No authentication provided	Include API key in Authorization header
`INTERNAL_ERROR`	Server error	Retry or contact support

AI Agent Integration

These structured errors enable AI agents to make intelligent decisions:

# Python example: AI agent handling location validation
response = api.send_alert(school="DEMO", building="Unknown")

if response.code == "BUILDING_NOT_FOUND":
    # AI can automatically list available buildings
    buildings = api.get_buildings(school="DEMO")
    # Then retry with correct building name
    
if response.code == "SCHOOL_NOT_FOUND":
    # AI knows to create the school first
    api.create_school(code="DEMO", name="Demo Campus")
        

Verticals

One platform, many use cases

🔥

Public Safety

Emergency alerts, evacuation coordination, compliance

Fire panel → screens + doors + PA
Lockdown → all doors lock, screens alert
Evacuation maps by floor
BEAP compliance tracking

🏢

Facilities Management

Building automation, space utilization, maintenance

HVAC coordination by zone
Lighting schedules by location
Occupancy-based automation
Maintenance alerts

📡

Network Infrastructure

WiFi, access points, network device coordination

AP registration without VLANs
Logical tenant segmentation
Location-based policies
Multi-site orchestration

🔬

Research & Labs

Equipment monitoring, safety protocols, access control

Equipment alerts → fume hoods + doors
Lab access by authorization
Hazard notifications
Compliance documentation

Samples & Templates

Copy-paste recipes for common integrations

JSON Samples Postman Collection OpenAPI Spec

🔥

Fire Alert to Building

Building-targeted alert

Fire panel triggers alert → all screens in building show evacuation message.

POST /api/v1/alerts
{
  "schoolCode": "CAMPUS01",
  "buildingCode": "MAIN",
  "alertType": "fire",
  "message": "FIRE ALARM - Evacuate immediately"
}

Copy to clipboard →

🔒

Campus-Wide Lockdown

All screens campus-wide

Lockdown command → all screens across entire campus show lockdown warning.

POST /api/v1/alerts
{
  "schoolCode": "CAMPUS01",
  "alertType": "lockdown",
  "message": "LOCKDOWN - Secure in place immediately"
}

Copy to clipboard →

📺

Register a Display

Device onboarding

Register a new screen — returns pairing code for campus admin to map location.

POST /api/v1/devices/register
{
  "deviceType": "display_screen",
  "deviceName": "Lobby Display",
  "deviceModel": "Samsung QM55R"
}

Copy to clipboard →

🗺️

Fetch Evacuation Map

Location-aware content

Retrieve floor-specific evacuation map for a screen during emergencies.

GET /api/v1/maps/screen/CAMPUS01/lobby-1

// Response includes:
{
  "mapUrl": "/maps/main-floor-1.png",
  "floor": 1,
  "buildingName": "Main Building"
}

Copy to clipboard →

🎫

Visitor Check-In

OneBadge

Record visitor arrival with photo capture, digital badge, and real-time notifications.

POST /api/v1/visits
{
  "token": "bldg_abc123",
  "visitor_name": "John Smith",
  "company": "Acme Corp",
  "host_name": "Jane Doe",
  "purpose": "Meeting"
}

Copy to clipboard →

🅿️

Parking with License Plates

OneBadge

Parking program with license plate capture and Venmo honor-pay. QR scan, pay, check in.

POST /api/v1/access-programs
{
  "building_id": 1,
  "name": "Visitor Parking",
  "type": "parking",
  "is_paid": true,
  "price_cents": 500,
  "payment_method": "venmo",
  "payment_handle": "@YourVenmo",
  "auto_timeout_hours": 8
}
// Returns QR code URL for public intake

Copy to clipboard →

🎟️

Concerts & Events

OneBadge

Ticketed events with QR entry. Game days, concerts, fundraisers, or any paid event.

POST /api/v1/access-programs
{
  "building_id": 1,
  "name": "Fall Festival",
  "type": "ticket",
  "is_paid": true,
  "price_cents": 1500,
  "payment_handle": "@SchoolEvents",
  "welcome_message": "Welcome to Fall Festival!",
  "badge_message": "Show this badge at entry"
}
// Public QR: /access/start?token=...

Copy to clipboard →

💡

Want more templates?

Check the Multi-Endpoint Guide for complete orchestration scenarios with multiple device types.

Sandbox

Try the API with live requests — no production impact

Interactive API Explorer

Test endpoints against our demo environment. All data is sandboxed.

Request

Endpoint

School Code

Message (for alerts)

Response

{ "status": "ready", "message": "Select an endpoint and click Send Request" }

What you can try:

GET Buildings - Returns 3 demo buildings (Main Building, Science Hall, Library)
POST Alerts - Sends a test alert (no real notifications)
POST Clear Alert - Clears the active alert
POST Register Device - Registers a new display device
GET Access Programs - Returns visitor, parking, and contractor entry types
POST Visits - Creates a check-in record for an access program

Sandbox Limits: 500 API calls/month using the DEMO school. For production access with your own school, contact us.

Documentation & Guides

Deep-dive resources for different audiences

Business

API Value Guide

Business-focused overview of what each API solves and why vendors should integrate. Share with partners and prospects.

View Guide →

Technical

Vendor Integration Guide

Complete technical guide with architecture, APIs, authentication, and end-to-end fire panel integration example.

View Guide →

Advanced

Multi-Endpoint Orchestration

How InstaAlert Engine orchestrates screens, PA systems, door controllers, HVAC, and more from a single API call.

View Guide →

CIO / IT

Network Architecture Guide

Before/after network diagrams, Campus Graph, and where InstaAlert fits in your infrastructure.

View Guide →

Network

Network Provisioning Guide

For network engineers: How to set up devices and achieve segmentation without VLANs and ACLs.

View Guide →

InstaAlert Engine Developer Platform

What is InstaAlert Engine?

Location-Aware

Capability-Based

Multi-Tenant Isolated

Vendor Agnostic

Before You Begin: Environment Mapping

Location Hierarchy

What's Required vs Optional?

Validation Rules

Quickstart: Your First API Call

Step 1: Get Your API Key

Step 2: Send an Alert

Step 3: Register a Device

Step 4: Map Device to Location

OneBadge powered by InstaAlert

🎫 One QR. Any Entry Type.

Key Features

Connects to Real-Time Alerts

API Reference

Authentication

Error Codes Reference

Consistent Error Format

AI Agent Integration

Verticals

Public Safety

Facilities Management

Network Infrastructure

Research & Labs

Samples & Templates

Fire Alert to Building

Campus-Wide Lockdown

Register a Display

Fetch Evacuation Map

Visitor Check-In

Parking with License Plates

Concerts & Events

Sandbox

Interactive API Explorer

Documentation & Guides

API Value Guide

Vendor Integration Guide

Multi-Endpoint Orchestration

Network Architecture Guide

Network Provisioning Guide