🔍 Contents
-
Prerequisites
-
Authentication
-
Overview of Endpoints
-
Create or Update a Dataset (PUT)
-
Retrieve Datasets (GET)
-
Delete Datasets (DELETE)
-
Technical Notes
-
Tips & Best Practices
-
FAQ
📋 Prerequisites
-
🔐 API credentials (Username + Password for HTTP Basic Auth)
-
🌐 Access to an execution environment (e.g., Power Automate, Python, Postman, Swagger UI, or your own integration solution)
-
🧾 UUIDs for KPI, Team, and optional Sub-Tile/KPI value (can be retrieved via meta-endpoints)
🔑 Authentication
Authentication is done via HTTP Basic Auth.
Header example:
Authorization: Basic <Base64-encoded username:password>
ℹ️ Note: Access is only possible for users with the appropriate API permission.
🔗 Overview of Endpoints (KPI)
| Method | Endpoint | Description |
|---|---|---|
| GET | /exchange/kpi-data |
Retrieve a list of all KPI data |
| GET | /exchange/kpi-data/{date}/{team-id}/{kpi-id} |
Retrieve a single dataset |
| PUT | /exchange/kpi-data/{date}/{team-id}/{kpi-id} |
Create or update a KPI dataset |
| DELETE | /exchange/kpi-data/{date}/{team-id}/{kpi-id} |
Delete a KPI dataset |
📸 Screenshot: API Endpoints Overview in Swagger UI
📥 Creating or Updating a KPI Dataset (PUT)
Example request:
PUT /exchange/kpi-data/2022-11-01/8dca904d-9134-3bb0-95b7-3f72ae3dfacf/c3ba32c2-a13a-0000-0000-000000000000
📸 Screenshot: Swagger UI – PUT request for KPI data
Headers:
Content-Type: application/vs.v2.0+json
Authorization: Basic <Base64 credentials>
Body example:
{
"values": [
{
"kpiValueId": "79cf2f74-0e9c-45b5-bc4d-f437079dde7c",
"value": 177
},
{
"kpiValueId": "fd2c7750-79e1-4514-89a2-e9c103db4d6b",
"value": 190
}
]
}
✨ Tip: You can also send only specific values (e.g., just "target") — the API will intelligently add or update existing values.
🔍 Retrieving KPI Datasets (GET)
Example: Retrieve all values for a KPI within a date range:
GET /exchange/kpi-data?kpi-id={kpi-id}&team-id={team-id}&from=2022-10-01&to=2022-10-31
📸 Screenshot: Swagger UI – GET request with filter parameters
ℹ️ Note:
-
Maximum range: 31 days (daily entries)
-
Or 6 months (weekly/monthly entries)
❌ Deleting a KPI Dataset (DELETE)
DELETE /exchange/kpi-data/2022-11-01/8dca904d-9134-3bb0-95b7-3f72ae3dfacf/c3ba32c2-a13a-0000-0000-000000000000
⚠️ Warning: Deleted entries cannot be restored.
📌 Technical Notes
-
Each KPI value is uniquely identified by: date + team + kpi (+ sub-tile)
-
The API accepts only one dataset per day/KPI/team/sub-tile
-
Date format:
yyyy-MM-dd(also applies to weekly/monthly entries)-
Week: Date of the Monday
-
Month: Date of the 1st day
-
-
Sub-tiles are optional but required for more granular structuring
✨ Tips & Best Practices
-
🧪 Start with tests in Swagger Editor or Postman
-
🔄 Update KPI values regularly for consistent analytics
-
🧩 Enter values only at the lowest team level – aggregation happens automatically
-
🧾 Verify UUIDs for KPI, Team, Sub-Tile, KPI value via meta-endpoints
❓ FAQ
How do I find the required UUIDs (KPI, Team, KPI values)?
👉 Use the meta-endpoints /exchange/kpi and /exchange/kpi/{kpi-id}.
What happens if I send the same values again?
👉 The API detects existing combinations and overwrites them (PUT = Create/Update).
Can I send only target values?
👉 No – if target values are missing, the API may set them to default (0) or use historical targets.