Flow API Documentation

Flow Reporting API – Integration Guide

1. Overview

This guide explains how to retrieve store data using the Flow Reporting API.

The API provides:

Traffic (by entrance)
Demographics (age and gender)
Sales
Transactions
Items sold

The data follows the same logic as the Flow platform and can be used directly for reporting purposes.

2. Available APIs

Current endpoint: /kpis/hourly
Returns hourly traffic, demographics, and sales data.

Additional endpoints may be introduced following the same structure.
If you require a different data structure or additional APIs, please contact:
[email protected]

3. Quick Start

To retrieve data:

Get API key
https://app.flow-insight.com/general
Settings > General > Integrations > Flow API
Obtain store codes
Provided by Flow
Send request
POST https://reporting-api.flow-insight.com/rest/kpis/hourly
Receive response and process data

This is sufficient to begin integration.

4. Authentication

Headers:

Content-Type: application/json  
X-Secret-Key: {your-api-key}  
Accept-Language: en

5. Request Structure

cURL Example

curl -X POST https://reporting-api.flow-insight.com/rest/kpis/hourly \
-H "Content-Type: application/json" \
-H "X-Secret-Key: {your-api-key}" \
-H "Accept-Language: en" \
-d '{
  "date": "2026-04-19",
  "storeCodes": ["101", "102"]
}'

6. Response Structure

Sample

{
  "data": [
    {
      "storeCode": "101",
      "timestamp": "2026-04-19T11:00:00",
      "traffic": {
        "001": { "enters": 37, "exits": 47 }
      },
      "demographics": {
        "group_2": 11,
        "group_6": 50
      },
      "sales": 51854,
      "transactions": 12,
      "itemSold": 22
    }
  ],
  "status": 200
}

7. Data Definitions

Field	Description
storeCode	Unique store identifier assigned by Flow
timestamp	Start time of the hour (Example: 11:00:00 → data for 11:00–11:59)
traffic	Traffic counts per entrance or sensor enters: number of entrants exits: number of exits Keys such as "001", "002" represent individual entrances or sensors. These identifiers are managed by Flow and may not correspond to named entrances known by the client. Important: to calculate total store traffic, sum the enters values across all entrances.
demographics	Estimated counts by age and gender: group_1: Male ≤18 group_2: Male 19–44 group_3: Male 45–59 group_4: Male 60+ group_5: Female ≤18 group_6: Female 19–44 group_7: Female 45–59 group_8: Female 60+ Fields may be omitted if values are zero or not detected.
sales	Total sales amount
transactions	Number of transactions
itemSold	Number of items sold

8. Store Codes

Store codes are unique identifiers managed by Flow.
They cannot be created or modified by the client.

Store codes correspond directly to the store identifiers assigned to each location within the Flow platform.

9. Data Retrieval Rules

Maximum 20 stores per request
If more than 20 stores are required, split requests accordingly

Limitations:

The * wildcard cannot be used
Store codes must be explicitly specified

10. Data Availability

Data is updated continuously during store operation
The latest hour may still be updating
Use end-of-day data for finalized reporting
Historical data is available via the API

11. Data Aggregation and Usage

The API provides data at an hourly level.

Daily data is calculated by summing hourly values
Monthly data is calculated by summing daily values

Aggregation must be handled on the client side.

Usage Guidelines

Hourly data is typically used for:

Time-of-day performance analysis
Identifying peak hours
Staffing optimization

Daily data is typically used for:

Reporting and KPI tracking
Performance summaries
Monthly analysis

12. Error Handling

200: Success
401: Authentication error

Check:

API key
Request format

13. Support

Email: [email protected]
URL: https://app.flow-insight.com/general

Help center