WFM integration API: the contract pattern for footfall-driven shift adjustments

What a WFM integration API is for

Most retail and venue operations run two systems that need to talk to each other. A workforce management platform owns the roster: contracts, shifts, swaps, payroll. A people counting platform owns the demand signal: how many visitors entered the building, how that breaks down by hour and zone, how it is trending against forecast. Neither system can do the other one's job, and the work of pairing them is almost always handled through an API contract between them rather than a shared database.

This post is for the engineer or solutions architect on either side of that contract. It walks through the integration shape that has held up in production: how the two systems authenticate, how schedules and forecasts sync, what events carry capacity changes, how realized labor is written back, and the operational decisions (idempotency, retries, security) that determine whether the integration runs quietly for years or breaks every other Saturday. It is technology-led, not vendor-led. The same shape applies whether the WFM side is Ariadne's Employees Planner or a separately licensed platform such as SAP, Workday, UKG, Quinyx, Deputy, Humanity, or Microsoft Shifts. The integration shape is the same; the field names differ.

The hub for what Ariadne integrates with is platform integrations. This post sits one level below that: not the catalog, the contract.

The two systems and the four flows

A working WFM integration with a counting platform comes down to four data flows. Anything else is a variant.

1. Schedule sync. The WFM platform publishes the current and upcoming roster to the counting platform so the counting side can present labor coverage against demand on the same dashboard.
2. Forecast publish. The counting platform publishes a forward-looking demand forecast (visitors per hour, by zone, by store) to the WFM platform so the scheduler can size shifts against expected traffic.
3. Intraday capacity events. When live conditions diverge from the forecast (a busier or quieter hour than expected), the counting platform emits an event the WFM can act on inside the day.
4. Realized labor write-back. After a trading period closes, the WFM platform reports the labor that was actually worked back to the counting platform so the demand-vs-coverage report reconciles to truth, not to plan.

Each of these is a separate endpoint or topic. They share an auth model, an identity model for stores and zones, and an error model, but they are not collapsed into one mega-endpoint. The reason is operational: the failure mode of a forecast push is different from the failure mode of a realized-labor write, and treating them as one surface makes both harder to debug.

Authentication

Two patterns dominate. Pick one and apply it consistently across all four flows; mixing them is the most common cause of integration drift over time.

• OAuth 2.0 client credentials. The WFM and counting platforms exchange a client id and client secret for a short-lived bearer token (typically one hour). Every request to the other system carries the token in an Authorization header. Token rotation is automatic, secret rotation is operator-driven, and revocation is centralised. This is the right default for any integration that crosses organisational boundaries.
• Long-lived API key. A single secret, sent as a header on every request, rotated manually. Simpler to implement, weaker for production. Acceptable when both systems are operated by the same organisation and key rotation is on a calendar; not acceptable when the integration crosses tenants or when the WFM is multi-tenant SaaS.

Both patterns sit on top of HTTPS with TLS 1.2 or higher. Mutual TLS shows up in regulated retail and in healthcare-adjacent venues, where the WFM platform asks the counting platform to present a client certificate alongside the bearer token. It is overkill for most retail deployments and standard for hospital operations.

Identity: stores, zones, and shifts

Before any flow runs, the two systems need a shared map of the world. A store in the WFM is a numeric or alphanumeric site id. A store in the counting platform is a building with sensors. Those have to point at each other, or every later request is ambiguous.

A clean identity model has three layers. Site id is the building. Zone id is a subdivision inside the building (sales floor, fitting rooms, back of house, a department). Shift id is the unit of work the WFM owns. Both systems keep their own primary keys and expose a mapping table: WFM_site_id <-> counting_site_id, WFM_zone_id <-> counting_zone_id. The mapping is owned on one side, queryable from the other, and audited when stores open, close, or are renumbered.

Two failure patterns are worth naming. The first is the silent rename: a store is renumbered on the WFM side without an update to the mapping, and the forecast keeps publishing to a stale id. The receiving system either rejects the payload (good) or accepts it and the forecast simply does not show up in the new site's dashboard (bad). The fix is a daily reconciliation job that compares both systems' site lists and surfaces deltas. The second is the zone fork: someone splits a department in the WFM without telling the counting side, and per-zone forecasts publish to a zone that no longer exists in the WFM tree. Zone identity needs a version field that both sides increment.

Flow 1: schedule sync (WFM to counting)

Schedule sync is the easier of the two outbound flows. The WFM publishes the current roster: who is working, in what role, in what zone, for which intervals. The counting platform stores it as labor coverage and shows it next to the demand series.

The minimum useful payload is a list of shifts, each carrying a shift id, a site id, a zone id (optional, defaults to whole site), a start timestamp in ISO 8601 with offset, an end timestamp, a head count for the shift, and a role tag. Personally identifiable data (employee name, employee id) is not required for demand-vs-coverage reporting and should be omitted from this flow unless a specific feature on the counting side requires it. The counting side is reporting a coverage curve, not building a staff register.

The shape works well as a daily incremental push plus a weekly full snapshot. Incrementals carry only the shifts that changed since the last cursor; the weekly snapshot is the reconciliation point that catches anything the incrementals missed. Both endpoints accept the same payload shape and differ only in semantics, which keeps the WFM client simple.

Flow 2: forecast publish (counting to WFM)

The forecast flow is the one that earns the integration. The counting platform owns the demand model, computes a forward-looking visitor forecast, and publishes it to the WFM as a time series the scheduler can act on.

The payload is a list of forecast points. Each point carries a site id, an optional zone id, a forecast interval (typically one hour, sometimes fifteen minutes for fast formats), a start timestamp, a predicted visitor count, and a confidence band. A version field on the payload distinguishes the published medium-horizon forecast from later refinements. A model id and a generated-at timestamp are included so the WFM can audit which model produced the numbers.

Publication cadence depends on the WFM's roster cycle. A two-week roster horizon means the medium-horizon forecast publishes once a week, fourteen days out, replacing the previous publish for that window. A daily refinement publishes seven days out and overwrites the daily slice. The contract should be explicit about which publish supersedes which: the right rule is last-write-wins by version and generated-at, scoped to (site, zone, interval). Without that rule, two simultaneous publishes can leave the WFM in an inconsistent state.

Flow 3: intraday capacity events

The third flow is the one that distinguishes a serious integration from a nightly batch. Reality diverges from forecast inside the day, and the WFM needs to know in time to do something about it. Two patterns work:

• Webhook push. The counting platform sends an HTTPS POST to a WFM-side endpoint when a defined condition fires: an hour is trending more than a configured percentage above or below forecast, a zone has crossed a capacity threshold, the next-hour projection has shifted by more than a configured tolerance. The webhook carries the same identity fields as the forecast publish, plus the trigger reason and the suggested action. The WFM applies its own logic on top.
• Pollable nowcast. The counting platform exposes a low-latency endpoint that returns the current short-horizon forecast. The WFM polls every five or ten minutes and applies the same condition logic on its own side.

Webhooks are simpler when they work, harder when the receiver is down. Polling is harder when the network is busy, easier when it is intermittent. A robust integration usually supports both and lets the WFM operator pick. The webhook side needs a documented retry policy: a sensible default is three retries with exponential backoff (initial one second, factor two, max thirty), with a circuit breaker that pauses the channel for fifteen minutes after a sustained 5xx pattern and pages the operator.

Flow 4: realized labor write-back

The last flow closes the loop. After a trading period ends (a day, a week, a fortnight), the WFM reports what was actually worked: hours scheduled, hours worked, gaps, overruns, swaps, no-shows. The counting platform stores this against the same site, zone, and interval identity and uses it to reconcile the demand-vs-coverage report.

The payload is shaped like a closed time series. Each row carries site, zone, interval start, scheduled hours, worked hours, planned head count, actual head count, and an exception flag for anything that needed manager intervention. The flow is usually daily, posted shortly after store close. A weekly resend is a useful safety net because labor adjustments (timesheet corrections, late approvals) can land a day or two after the original write.

The reconciled view this enables is the most valuable artifact of the integration: a demand curve, a planned-coverage curve, and an actual-coverage curve overlaid, period by period, store by store. That is the report a regional manager defends labor decisions against, and the WFM cannot draw it without the demand series, and the counting platform cannot draw it without the realized-labor write.

Idempotency and error handling

Production integrations fail. The failure mode that breaks scheduling weekends is not a single error; it is a duplicate. A retry happens because the network timed out, the receiver had already accepted the original request, and a duplicate shift or a duplicate forecast point lands in the WFM. Idempotency is the contract property that prevents this, and it has to be designed in, not retrofitted.

The pattern that works is an idempotency key on every mutating request. The sender generates a UUID at the moment the request is built and includes it in an Idempotency-Key header. The receiver stores the key (and the response) for at least 24 hours. A second request with the same key returns the original response unchanged. Stripe popularized the pattern; it works equally well for WFM payloads because the receiver does not have to know whether the duplicate was caused by a network retry, a webhook re-delivery, or an operator running a backfill twice.

Errors fall into three buckets, each with a different response shape. 4xx errors are payload problems (bad identity, malformed timestamp, missing required field). The response body lists the offending field and the sender does not retry, it fixes and resubmits. 5xx errors are receiver problems. The sender retries with exponential backoff, respecting any Retry-After header. 409 conflicts are version problems (two writers, last-write-wins violated). The response carries the current server version, and the sender either retries with the latest version or surfaces the conflict to an operator.

Security and operational hygiene

The integration crosses a boundary between two production systems and frequently between two organisations. The security model needs to be explicit at six points:

• Transport. TLS 1.2 or higher, modern cipher suites, and HSTS on the receiver. Plain HTTP is not an option for any flow.
• Authentication. OAuth 2.0 client credentials as the default, with documented secret rotation cadence and a revocation path that takes effect within minutes.
• Authorization. Scopes that map to flows. A schedule-sync client cannot publish forecasts; a forecast-publish client cannot write realized labor. Principle of least privilege applies as in any system.
• Rate limits. Documented per-endpoint, with 429 responses carrying a Retry-After header. The webhook side should also be guarded so a misbehaving sender cannot flood the WFM.
• Audit logging. Every request, with its idempotency key, sender id, and response code, retained long enough to investigate a disputed payroll period. Most retailers settle on twelve months.
• Data minimisation. Personally identifiable data crosses only where it has to. Demand-vs-coverage reporting does not need employee names; payroll reconciliation might. Two clients, two scopes, two payload shapes is cleaner than one fat client that sees everything.

How Ariadne fits in

Ariadne sits on the counting side of the integration. The people counting platform produces the demand series the WFM consumes: visitors per hour per site, optionally per zone, with a forecast and an intraday update channel. The same numbers feed Ariadne's own Employees Planner for teams that want one product end to end, or they export to a separately licensed WFM via the same contract shape.

Ariadne measures this with Hybrid Fusion, its patented camera-free method. Time-of-Flight depth sensing counts every visitor at the entrances, capturing geometry rather than images, while patented phone signal sensing follows movement through the interior, detecting the signals a phone emits even in airplane mode. The sensor streams both feeds to Ariadne, where Hybrid Fusion combines them into one trajectory per visit and computes counts, dwell, and paths. The streams carry no identifier: no MAC address, no device ID, no biometric data, and no camera is involved. Identifiers are stored only when a visitor explicitly opts in, which keeps the method GDPR-friendly and outside biometric territory.

Two integrity points matter for procurement on the WFM side. First, the demand signal Ariadne publishes is a count, not a stream of recognised people. The WFM receives an integer per interval, not an event stream of identifiable visits. That keeps the integration outside the scope of biometric data and outside most of the heaviest GDPR obligations the WFM might face if a vendor were pushing camera-derived data into its boundary. Second, the count itself is independent of point of sale conversion: a busy non-converting hour is visible in the forecast, where a transactions-only forecast would miss it. The contract shape described above is the same either way; the upstream measurement is what makes the demand signal worth integrating in the first place. Data handling is set out in the privacy policy.

For a team evaluating the integration before commitment, the test is whether each of the four flows can be exercised end to end against a staging environment, with an idempotency key, with a deliberate retry, and with a deliberate error. An integration that does not survive that exercise in staging will not survive a busy weekend in production.

FAQ

Does the integration require cameras anywhere in the path?

No. Ariadne counts with Hybrid Fusion: Time-of-Flight depth sensing plus patented phone signal sensing, never cameras. Time-of-Flight captures geometry rather than images, and signal sensing captures no MAC address by default, so the measurement involves no video, no faces, and no biometric data.

Is the demand series real time or batch?

Both. The medium-horizon forecast is a batch publish on the roster cycle (typically weekly, with a daily refresh). The intraday capacity flow is event-driven: a webhook fires when conditions cross a configured threshold, or the WFM polls a low-latency nowcast endpoint every few minutes. Most production deployments use the batch publish for scheduling and the event channel for in-day adjustments.

What if the WFM platform we use is not on the integrations page today?

The contract shape described in this post is platform-agnostic: any WFM that can accept an authenticated POST of a time series, expose a schedule endpoint, and consume a webhook is compatible. The platforms named here are illustrative examples of WFM tools a retailer or venue might already run. Specific connectors evolve over time; the integrations hub is the current source of truth for what is documented and supported.