How Parklio works

A five-minute mental model: what's in an account, how a command reaches a device, and why results arrive asynchronously.

The pieces

Account structure

Account
├── Account users (Super Admin, Admin, Operator)
├── API tokens
└── Lots
    ├── Gateways
    └── Zones
        ├── Products (barrier, gate, chain, bollard, brain)
        └── LPR cameras

• Account: your organization. Everything below belongs to it.
• Lot: a parking location. A lot holds zones and Gateways.
• Zone: a part of a lot, for example a level or a pricing area. Products and LPR cameras sit in a zone.
• Product: the hardware you control. Products speak only Bluetooth (BLE).
• Gateway: an on-site box that connects to the Parklio cloud (over Ethernet or a mobile network) and to nearby products over Bluetooth. It's how the cloud reaches a product.

More detail in Data model.

Products and Gateways are added to an account with the Parklio Connect app, which pairs each device with your account. The API has no pairing endpoints.

Two ways to reach a product

	Cloud path	Bluetooth path
How	Your backend → Parklio API → Gateway → product over BLE	A phone with your app (built with the Parklio SDK) → product over BLE
Credentials	Your API token	An operation token your backend creates, which the app hands to the product
Needs a Gateway	Yes, online and in range	No
Needs internet at the product	Yes (at the Gateway)	No, once the app has the token
Result	Asynchronous, as a realtime event	Directly in the app
Start with	Quickstart	SDK

Parklio's own tools use the same paths: Zapier and the web app (PMS) go through the cloud, and the Connect app talks to products over Bluetooth.

Why the cloud path is asynchronous

When you send a command, such as POST /v2/products/{id}/state with {"operation": "open"}:

1. The API checks it can run the command, then answers straight away with an event_id. The device hasn't moved yet.
2. The API sends the command through the Gateways that recently saw the product, one at a time, strongest Bluetooth signal first, waiting up to 30 seconds for each.
3. The Gateway relays it to the product over Bluetooth, and the product reports back.
4. The API pushes the result to you over the realtime connection: a lot_change event with your event_id when it worked, or a gateway_error event with your event_id when it didn't.

So a cloud integration needs both the REST API (to send commands) and the realtime connection (to learn the result). Connect to realtime first. Details in Asynchronous operations.

Status flows the other way too

Products advertise their state over Bluetooth all the time: open or closed, battery, errors such as a jammed arm or a dirty sensor, and on a barrier whether a car is on top. Gateways pick these up and send them to the API, which updates the product and pushes a lot_change event (with no event_id, since nobody requested it). A product is online while a connected Gateway can see it, and offline otherwise.

Occupancy

Parklio can track which parking places are free or occupied, using cameras and on-site processing. Each lot is different, so detection is set up by Parklio's technicians: they plan camera coverage from lot photos and blueprints, then map the parking places and tie them to your account. You read the results; you don't configure detection.

From there:

• Lots and zones carry spot_count and occupied_count; read them with GET /v2/lots/{id}.
• Each parking place has an occupancy_status of free, occupied or unknown; list them with GET /v2/parking-places.
• Changes arrive live as realtime events; see Events.

Next

• Choose your path: which integration fits your product.
• What you need: the account, subscriptions and hardware.