# Central Reports API

Pull structured reporting data across venues, transactions, and performance metrics. Built on AWS infrastructure with scheduled cloud sync.

**Base URL:** `https://central-reports-api.helixleisure.net`

---

## Overview

The Central Reports API provides easy-to-understand raw data outputs from your location database. Built on AWS infrastructure, data is synced from your location database to cloud storage on a regular basis throughout the day.

The endpoints allow you to queue a dataset and then retrieve it once processed. Data is returned in a semi-computed format — structured and normalised so it is straightforward to consume without additional heavy lifting on your end.

> Access to the Central Reports API requires a subscription. Please enquire with your Embed representative about pricing and getting set up. Once signed up, only minor setup work is required to get started.

### Parameters & Limits

| Constraint | Limit |
|-----------|-------|
| Maximum location IDs per request | 25 |
| Maximum date range per request | 30 calendar days |
| Card History endpoint | 1 location and 1 day per call |

> The Card History endpoint has stricter limits due to the high volume of data in its output.

### Available Report Endpoints

Replace `{{reportname}}` in the API URLs with the relevant report name. Contact your Embed representative for the full list of available report names and their parameter schemas.

---

## Getting Started

Each dataset in the Central Reports API supports three operations. The typical flow is to queue a report, then retrieve it once processing is complete. If you need fresh data for the same parameters, you can force a regeneration using the PUT endpoint.

### Call Flow

**Step 1 — Queue a Report**

```
POST /report/{{reportname}}
```

Queues the report for processing. Returns a **token** that identifies this output.

**Step 2 — Retrieve the Report**

```
GET /report/{{reportname}}/{{token}}
```

Returns the compiled dataset if processing is complete. If not yet ready, retry after a short delay.

**Step 3 — Refresh / Regenerate the Report**

```
PUT /report/{{reportname}}/{{token}}
```

Forces a fresh run of the report. Use this when you want updated data for a previously queued request.

> **How caching works:** If you POST for the same report type with the same input parameters, you will receive the same token as the previously queued dataset. To get fresh data, send a PUT with that token.

### Example Request

```
POST /report/transactions HTTP/1.1
Host: central-reports-api.helixleisure.net
Authorization: Bearer [your token]
Content-Type: application/json

{
  "location_ids": [101, 102, 103],
  "date_from": "2025-06-01",
  "date_to": "2025-06-30"
}
```

---

## Authentication

The Central Reports API uses **Bearer Token** authentication. You will need a **client secret**, which you can obtain from Embed support.

### Get a Bearer Token

Exchange your client secret for a Bearer Token:

```
POST /token

{
  "client_secret": "[your client secret]"
}

// Response: a bearer token, valid for 3600 seconds
```

### Using the Bearer Token

Include the token in the `Authorization` header for every subsequent API call:

```
Authorization: Bearer [your token]
```

### Token Expiry

There is no token refresh endpoint. When your token expires, simply POST to `/token` again to obtain a new one.

### Authentication Summary

| Property | Details |
|----------|---------|
| Method | Bearer Token |
| Credential | Client Secret (provided by Embed support) |
| Token endpoint | `POST /token` |
| Token lifetime | 3600 seconds (1 hour) |
| Refresh | None — re-request a new token on expiry |
| Header | `Authorization: Bearer [token]` |