# Use cases

The Dyflexis API is designed to slot into the systems already
running your business. Below are three common integration
shapes, pick the one that matches the role your software plays
in the customer's stack.

## Business intelligence (BI)

Pull scheduled hours, registered hours, and payroll-period data
into a BI tool such as **Power BI** so leadership can monitor
workforce cost, productivity, and absence trends alongside
revenue.

**Typical endpoints**

- `GET /api/business/v3/scheduled`, planned shifts for a period
- `GET /api/business/v3/registered-hours`, worked hours after
clocking, ready for variance analysis against the schedule
- `GET /api/business/v3/employees`, employee dimension table
- `GET /api/department-management/v3/tree`, office and
department dimension hierarchy
- `GET /api/absence/v3/sick-leave`, absence facts for
availability dashboards


**Authentication.** Issue a `business` scope token per BI
service account. Most BI tools attach it on every refresh as an
`Authorization: Token <key>` header.

**Refresh cadence.** Polling once per hour during business
hours is plenty for most dashboards. For near-real-time
operational views, subscribe to the
[`Payroll period ready` webhook](/guides/webhooks)
and pull the period only when notified.

## Point of sale (POS)

Use information streams to push **historically realised
workload** from the POS into Dyflexis (covers served,
transactions completed, visitors counted) so the forecaster
learns from what actually happened on the floor. The same
integration can record clock-in and clock-out events from the
POS terminal.

**Typical endpoints**

- `POST /information-streams/v3/streams`, register a stream
for the workload metric you want to record (for example
"revenue per hour" for a restaurant, or "transactions per
hour" for a retail store)
- `POST /information-streams/v3/datapoint/{key}`, push
historically realised data points as transactions are
finalised at the end of a shift or trading day
- `POST /api/clock/v3/clock-in`, record a clock-in event
against the POS terminal acting as the clocking device
- `POST /api/clock/v3/clock-out`, record the matching
clock-out event


**Authentication.** Two scopes are typically used together:
`forecasting` for stream writes and `clock` for clock events.

**Granularity.** Pick a granularity at stream creation time
that matches your POS reporting cadence, `hour` works well
for restaurants and bars, `day` is enough for retail.

## Operational software

Synchronise the workforce of record from an enterprise
resource planning system, a **WMS** (warehouse management
system) for logistics, a **PMS** (property management system)
for hospitality, or a generic ERP for everything in between,
into Dyflexis, and push payroll-ready hours back for
downstream salary processing.

**Typical endpoints**

- `POST /api2/external-employees/{employeeReference}`,
upsert employees from the ERP master
- `POST /api2/external-employees/{employeeReference}/contracts`,
push employment contracts
- `GET /api/payroll/v3/employees`, pull employees with the
payroll-relevant subset of fields
- `GET /api/payroll/v3/hours-per-day/...`, pull hours per
day for a payroll period
- `GET /api2/payroll/queue/from/{lastQueueId}`, poll the
queue of finalised periods waiting to be picked up
- `POST /api2/payroll/queue/{queueId}/status`, acknowledge
once the ERP has consumed the period


**Authentication.** Three scopes are usually combined:
`external_employees` for the employee/contract upsert,
`payroll` for pulling period data, and `payroll_hours` for
consuming the queue.

**Idempotency.** Both `external-employees` and the contracts
endpoint are upserts keyed by `employeeReference` and
`contractReference` respectively, replaying the same payload
is safe and is the recommended way to recover from transient
failures.