Platform Concepts

Understanding the core data models and logic that power Flock product experiences will make it easier to navigate our more in-depth guides. Whether you are building a simple script or a commercial application, these concepts are the foundation of every integration.

The Hierarchy

Data in Flock is organized into a strict hierarchy to ensure security, logical grouping, and proper access control.

1. Organization

The Organization is the top-level entity representing a customer (e.g., "Main Street PD" or "Tech Corp HQ").

Access: Your API credentials unlock the door to the specific Organization you are integrating with.
Scope: All data, devices, networks, and users belong to an Organization. A user cannot belong to more than one Organization.

2. Networks

A Network is a logical grouping of devices within an Organization.

Use Cases: Networks often represent physical locations (e.g., "North Precinct", "Parking Garage A") or functional groups (e.g., "Mobile Trailers").
Role: Networks act as the primary container for configuration. More advanced concepts like search filters and granular role permissions are layered on top of this foundational construct.

3. Devices

A Device represents physical hardware capturing data. The API interacts with both Flock-manufactured hardware and third-party sensors:

LPR (License Plate Recognition): Cameras optimized for capturing vehicle attributes and license plates (e.g., Flock LPR or third-party IP cameras via the Vehicle Detections Ingest API.
Audio Detection: Acoustic sensors designed to detect specific sound signatures like gunshots (e.g., Flock Audio Detection).
Video: Live-streaming or recording cameras for real-time situational awareness (e.g., Flock Video).
Drones: Aerial assets providing live telemetry and video feeds (e.g., Flock Aerodome/DFR).

Identity & Access

Users, Roles, and Permissions

The Flock permissions model is granular. When using User-Level OAuth, your app inherits the specific restrictions of the user who logged in.

Sensor Data Permissions: Operational actions on sensor data (e.g., "Search LPR Reads" or "View Live Video") are typically scoped to Networks. If a user does not have access to the "East Side" network, your app will not receive data from devices in that network either.
Product Entitlements: Access to specific product features (like "CAD Integration" or "Hotlist Management") are Organization-level entitlements. These reflect the subscriptions the customer has purchased. Customers might not all have access to all of the functionality available in Flock's APIs based on their purchases.

Device Ownership: Owned vs. Shared

In the Flock ecosystem, devices are either Owned or Shared.

Owned Devices: Assets directly managed by the Organization.
Shared Devices: Assets owned by another Organization (e.g., a commercial business) that have been shared with an Organization.
API Access: Generally, our APIs prioritize access to customer data from Owned Flock devices. This ensures that sharing workflows remain compliant with the strict guardrails and audit requirements enforced by the Flock product experience.

Hotlists

Hotlists are the "memory" of the system - lists of vehicles that are of interest to the customer.

1. State and National Hotlists

These are regulated lists managed by state or federal authorities (e.g., NCIC, Amber Alerts).

Source: Government databases.
Management: Customers subscribe to these lists but cannot edit them directly. They are ingested securely by Flock through automated integrations with approved government agencies.

2. Custom Hotlists

These are user-defined lists created specifically for the Organization by its users.

Use Cases: "Banned Visitors," "Stolen Assets," "Investigative Targets."
Management: You can create and manage these programmatically via the Custom Hotlist API.
Audience: Custom hotlists have an Audience feature to specify visibility. A list can be available to the entire organization, or restricted to specific roles/users (e.g., for internal investigations).
Sharing: Custom hotlists can be shared from one organization to another. When shared, the recipient organization can view and subscribe to alerts, but only the "owning" organization can make edits.

Operational Data

This section covers the dynamic, real-time data that flows through the Flock platform.

Vehicle Detections (LPR)

A "Vehicle Detection" is the fundamental unit of LPR data. It represents a single event where a camera observed a vehicle in the real world.

Attributes: Flock's proprietary AI extracts the License Plate Label, License Plate State, and Vehicle Fingerprint (Make, Color, Body Type, and other Special Identifiers).
It also includes a Context Image (the vehicle and nearby surroundings for context) and a Plate Crop.
Normalization (O vs 0): To avoid confusion, the system treats the letter O and the number 0 as interchangeable. All API responses normalize these characters to 0. Do not implement your own fuzzy matching; simply rely on the platform's standard.

Alerts

An "Alert" is generated when an important event happens that requires end-user attention.

LPR Hotlist Alerts: Generated when a vehicle detection matches a hotlist entry.
Inbound Outdoor Alerts: External triggers from third party sources integrated into the Flock product experience (e.g., "Livestreaming Started" on a third party body-worn camera, "Device Launched" on a third party GPS tracker, or "Alarm Active".

CAD Events (Calls for Service)

A CAD Event represents a call for service (e.g., a 911 call) originating from a Computer-Aided Dispatch system.

Data: Includes location, priority, call type (e.g., "Burglary"), and narrative updates.
Integration: These events are ingested into Flock to visualize active incidents alongside device locations, enhancing situational awareness.

Geolocation & Telemetry

Flock product experiences can help end-users track the real-time location of mobile assets for situational awareness and dispatch operational effectiveness.

First Responder Location (AVL): Telemetry from patrol vehicles (dashcams), officer devices (body cameras), or Drone as First Responder (DFR) assets.
Sensor Geolocation: The static or dynamic location of sensors unrelated to first responders (e.g., a portable trailer).

Policies & Preferences

System behavior is often dictated by organization-wide policies that customers control. Your Flock App must be resilient to these customer-specific configurations.

Retention Policy: Most vehicle detection data is retained for 30 days by default. After this period, it is hard-deleted. The API will not return data older than the retention period.
Search Policies: Many organizations enforce personalized policies on how LPR data can be searched. This may include mandatory Case Numbers, moderation of search reasons to comply with state regulations, or the use of pre-determined reason codes. These policies are enforced by the API, and your app must handle them gracefully.