🔍 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.
✨ Tip: Values with unit "Time"
For KPIs with the unit "Time", provide the value as minutes since 0:00 (midnight).
Examples:
-
2:43 PM (14:43) →
14 × 60 + 43 = 883 -
08:00 AM →
8 × 60 = 480
🔍 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 only accepts one dataset per Day/KPI/Team/Sub-Tile
- Date format:
yyyy-MM-dd(used for weekly and monthly entries as well)- Week: Date of Monday
- Month: Date of the 1st day
- Sub-Tiles are optional but required for detailed structuring
- For KPIs with unit "Time", the value must be provided as total minutes since midnight (e.g.,
14:43 = 883)
✨ Tips & Best Practices
-
🧪 Start with tests in Swagger Editor or Postman
-
🔄 Update KPI values regularly for consistent analytics
-
🧾 Verify UUIDs for KPI, Team, Sub-Tile, KPI value via meta-endpoints
❓ FAQ
How can 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 recognizes existing combinations and overwrites the values (PUT = Create/Update).
Can I send only target values?
👉 No – if target values are missing, the API may replace them with standard values (0) or fallback to historical targets.
How do I send time-based KPI values?
👉 For KPIs with unit "Time", send the number of minutes since 00:00 midnight as integer. Example: 14:43 = 883.