---
title: "Flow API Documentation"
description: "Connecting your systems with your in-store analytics data via the Flow API"
url: https://help.flow-insight.com/en/articles/569-flow-api-documentation
collection: "Sensors & Data Sources"
updated: 2026-10-09
language: en
alternates: [ja]
---

# Flow API Documentation

Connecting your systems with your in-store analytics data via the Flow API

## **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:  
[**support@flow-solutions.com**](mailto:support@flow-solutions.com)

## 3\. Quick Start

To retrieve data:

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

This is sufficient to begin integration.

## 4\. Authentication

Headers:

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

## **5\. Request Structure**

### **cURL Example**

```javascript
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**

```javascript
{
  "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

<table style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1" style="border: 1px solid #e2e2e2; padding: 8px 12px; background-color: #f5f5f5;"><p><strong>Field</strong></p></th><th colspan="1" rowspan="1" style="border: 1px solid #e2e2e2; padding: 8px 12px; background-color: #f5f5f5;"><p><strong>Description</strong></p></th></tr><tr><td colspan="1" rowspan="1"><p>storeCode</p></td><td colspan="1" rowspan="1"><p>Unique store identifier assigned by Flow</p></td></tr><tr><td colspan="1" rowspan="1"><p>timestamp</p></td><td colspan="1" rowspan="1"><p>Start time of the hour (Example: 11:00:00 → data for 11:00–11:59)</p></td></tr><tr><td colspan="1" rowspan="1"><p>traffic</p></td><td colspan="1" rowspan="1"><p>Traffic counts per entrance or sensor</p><ul><li><p>enters: number of entrants</p></li><li><p>exits: number of exits</p></li></ul><p>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.</p><p>Important: to calculate total store traffic, sum the enters values across all entrances.</p></td></tr><tr><td colspan="1" rowspan="1"><p>demographics</p></td><td colspan="1" rowspan="1"><p>Estimated counts by age and gender:</p><ul><li><p>group_1: Male ≤18</p></li><li><p>group_2: Male 19–44</p></li><li><p>group_3: Male 45–59</p></li><li><p>group_4: Male 60+</p></li><li><p>group_5: Female ≤18</p></li><li><p>group_6: Female 19–44</p></li><li><p>group_7: Female 45–59</p></li><li><p>group_8: Female 60+</p></li></ul><p>Fields may be omitted if values are zero or not detected.</p></td></tr><tr><td colspan="1" rowspan="1"><p>sales</p></td><td colspan="1" rowspan="1"><p>Total sales amount</p></td></tr><tr><td colspan="1" rowspan="1"><p>transactions</p></td><td colspan="1" rowspan="1"><p>Number of transactions</p></td></tr><tr><td colspan="1" rowspan="1"><p>itemSold</p></td><td colspan="1" rowspan="1"><p>Number of items sold</p></td></tr></tbody></table>

## **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: [support@flow-solutions.com](mailto:support@flow-solutions.com)  
URL: [https://app.flow-insight.com/general](https://app.flow-insight.com/general)
