Most payroll integration failures don't start as integration failures. They start as a disagreement nobody wrote down. One system thinks a "shift" means clock-in to clock-out. Another thinks it means net paid minutes after unpaid breaks. The vendor assumes timestamps are UTC. The receiving system assumes local. Nobody signed anything that says who's right, so when payroll is off by 40 hours across a department, three teams spend a week arguing over whose definition was correct.
A time-data interoperability contract is what prevents that argument. Not the legal MSA — the technical contract. The agreed shape of a time event, the required fields, the versioning rules, and the tests that prove a sender actually produces what it claims. Done well, it turns "whose fault is this" into a thirty-minute lookup against a signed spec.
This is the playbook for building those contracts so payroll stays auditable, e-discovery stays clean, and vendor onboarding stops being a guessing game.
Why undefined contracts quietly wreck payroll
Time data crosses more organizational boundaries than almost any other operational data you have. A single paid hour might be captured on a mobile app, enriched by a scheduling system, adjusted by a supervisor, aggregated by a time engine, and finally consumed by payroll and your GL. Each handoff is an implicit contract. When those contracts live in people's heads instead of a spec, every handoff is a place where meaning drifts.
The drift is rarely dramatic. It looks like a vendor adding a break_paid boolean in a release and not telling anyone, so for two pay periods your system silently double-pays breaks for one site. It looks like a field that used to be minutes becoming decimal hours after an "improvement." It looks like a null that used to mean "no data" now meaning "zero hours worked."
A useful way to think about it: your payroll run is only as trustworthy as the least-specified field in the chain. One ambiguous field, consumed confidently, produces confidently wrong pay.
What makes this worse than other data problems is that errors are directional and expensive. Underpay triggers compliance exposure and employee trust damage. Overpay is nearly impossible to claw back. And because time feeds into the GL, a contract ambiguity doesn't just create a payroll ticket — it creates a reconciliation problem Finance inherits at month-end.
The canonical contract: what a time event actually needs to say
A canonical contract defines one authoritative shape for a time event that every producer must emit and every consumer can rely on. The goal isn't to capture everything a system could send. It's to define the minimal set of fields payroll requires to be correct and auditable — then let everything else be optional and clearly namespaced.
Accurate time tracking made effortless.
GoTimio empowers your team to log, monitor, and manage work hours seamlessly.
- Real-time time tracking
- Automated timesheet approvals
- Payroll and billing integration
No credit card required
Here's a canonical time-event contract that serves as a reasonable baseline. Deliberately small.
time-event.contract.v2.1.0.yaml contract: time.event version: 2.1.0 description: Canonical worked-time event consumed by payroll and GL identity: eventid: { type: string, format: uuid, required: true } # globally unique, idempotency key employeeref: { type: string, required: true } # stable payroll identity, not display name sourcesystem: { type: string, required: true } # e.g. "field-app", "kiosk-ne" time: intervalstart: { type: string, format: date-time, required: true } # RFC3339, UTC with offset intervalend: { type: string, format: date-time, required: true } timezoneiana: { type: string, required: true } # e.g. "America/Chicago" workedminutes: { type: integer, required: true, min: 0 } # authoritative paid-time quantity classification: paycode: { type: string, required: true } # REG, OT1, OT2, HOL, PTO... costcenter: { type: string, required: true } # drives GL allocation breakminutesunpaid:{ type: integer, required: false, min: 0 } provenance: capturedat: { type: string, format: date-time, required: true } capturemethod: { type: string, required: true } # badge, gps, manual, import lasteditedby: { type: string, required: false } # populated if edited editreason_code: { type: string, required: false } ext: # vendor-specific, never required by payroll type: object additionalProperties: true
Two design decisions here matter more than they look.
First, workedminutes is the authoritative quantity, and it's an integer in minutes — not decimal hours, not a derived value from start/end. Deriving worked time from intervalstart and interval_end feels elegant until you hit unpaid breaks, split shifts, and rounding rules that live in the producing system. The producer owns the rounding math; the contract transmits the result. If you want to see how the upstream rounding gets decided before it reaches this field, that's a separate governance question — but by the time it hits the contract, it's final and explicit.
Second, everything vendor-specific lives under ext. Payroll code is forbidden from reading ext. This single rule prevents the most common slow-motion failure: a consumer quietly depending on a field the contract never promised, which then disappears in a vendor update.
Minimal payroll-required fields
If you strip the contract to only what payroll cannot run correctly without, you get a short list. This is the subset you treat as sacred — breaking any of these is a major version event.
-
event_id— idempotency and dedup -
employee_ref— stable identity, never a name or email that changes -
intervalstart,intervalend,timezone_iana— anchoring and reconstruction -
worked_minutes— the paid quantity of record -
pay_code— how it's paid -
cost_center— where it's costed -
capturedat+capturemethod— provenance for audit and e-discovery
Everything else can be absent and payroll still produces a defensible result. Agreeing on this short list with Finance before onboarding any vendor is the highest-leverage hour you'll spend.
Semantic versioning rules for time payloads
Most teams know semantic versioning as a software concept and never apply it to data contracts. That's a mistake, because a payload is an interface. The whole point is to make breaking changes impossible to ship by accident.
| Change | Version bump | Example | Consumer impact |
|---|---|---|---|
| Remove a field, change its type, change its meaning, tighten validation | MAJOR | workedminutes becomes decimal hours; paycode enum restricted | Breaking — requires coordinated cutover |
| Add an optional field, add an enum value, loosen validation | MINOR | New optional project_ref; new OT3 pay code | Backward-compatible — safe to deploy |
| Clarify docs, fix an example, correct a description | PATCH | Fix timezone example in spec | No behavior change |
The rules that actually keep people honest:
-
Meaning changes are major, even if the type doesn't change. If a null in
breakminutesunpaidused to mean "unknown" and now means "zero," that's a MAJOR bump. This is the sneakiest break and the one teams consistently forget to version. -
Consumers pin to a major version and tolerate minors. Payroll declares "I consume
time.eventv2.x." Any v2.minor is safe. A v3 requires an explicit, tested migration — never silent. -
No producer ships a new major into a shared channel. New majors go to a parallel topic/endpoint so both versions run during cutover. This is what lets you reconcile old and new in parallel before flipping payroll over.
-
Deprecation has a clock. A field marked deprecated in v2.3 isn't removed until v3, with a stated sunset date in the contract itself.
In practice, the version lives in the payload and the transport — a header and a field — so a consumer can reject anything outside its declared range before a single bad event reaches the pay calc.
Consumer conformance tests: proving a sender does what it claims
A contract without tests is a suggestion. Conformance tests are how a receiving team verifies that a producer genuinely emits valid events before that producer is allowed anywhere near a production pay run.
The pattern worth recommending: the consumer owns the conformance suite, and every producer must pass it during onboarding and on every major release. Don't let vendors self-certify against their own interpretation.
conformancetimeevent.py import jsonschema, json, sys from datetime import datetime SCHEMA = json.load(open("time-event.schema.v2.json")) REQUIREDPAYROLLFIELDS = [ "eventid", "employeeref", "intervalstart", "intervalend", "timezoneiana", "workedminutes", "paycode", "costcenter", "capturedat", "capturemethod", ] def check(event): errors = [] # 1. Structural conformance try: jsonschema.validate(event, SCHEMA) except jsonschema.ValidationError as e: errors.append(f"schema: {e.message}") # 2. Minimal payroll fields present and non-null for f in REQUIREDPAYROLLFIELDS: if event.get(f) in (None, ""): errors.append(f"missing required payroll field: {f}") # 3. Semantic: interval sanity try: start = datetime.fromisoformat(event["intervalstart"]) end = datetime.fromisoformat(event["intervalend"]) if end <= start: errors.append("intervalend must be after intervalstart") spanmin = (end - start).totalseconds() / 60 if event.get("workedminutes", 0) > spanmin: errors.append("workedminutes exceeds interval span") except Exception as e: errors.append(f"timestamp parse: {e}") # 4. workedminutes must be a non-negative integer (not decimal hours) wm = event.get("workedminutes") if not isinstance(wm, int) or wm < 0: errors.append("workedminutes must be a non-negative integer") return errors if name == "main": events = json.load(open(sys.argv[1])) failures = 0 for i, ev in enumerate(events): errs = check(ev) if errs: failures += 1 print(f"[FAIL] event {i} ({ev.get('event_id','?')})") for e in errs: print(f" - {e}") print(f"\n{len(events)-failures}/{len(events)} events passed") sys.exit(1 if failures else 0)
Run the suite against edge-case fixtures like DST transitions, overnight shifts, and zero-minute corrections to catch the subtle failures that hit payroll.
The point isn't the specific checks — it's that this suite becomes a gate. A vendor's sample file either passes or it doesn't, and "it mostly passes" is a failing grade. Run it against a representative fixture set that includes the ugly cases: overnight shifts crossing midnight, DST transition days, zero-minute corrections, and maximum-length intervals. Those edge cases are where contracts quietly fail in production.
A good conformance fixture set also doubles as regression protection. When a vendor ships a new release claiming it's a MINOR bump, you re-run the exact same suite. If anything that used to pass now fails, their "minor" was actually a major, and you caught it before payroll did. This kind of pre-production verification pairs naturally with a disciplined payroll integration runbook that covers connector testing and safe cutover.
Provenance headers for e-discovery
The audit and legal side of time data gets ignored until someone's in a wage dispute or a regulator asks for records. At that point, "we have the hours" is not enough — you need to show where each number came from, who touched it, and when, in a way that stands up.
Provenance belongs in two places: inside the event (as shown with capturedat, capturemethod, lasteditedby) and in the transport headers, so you can trace the journey of a payload across systems without opening it.
X-Contract-Name: time.event X-Contract-Version: 2.1.0 X-Event-Id: 5f3c9b2a-... # matches payload event_id X-Source-System: field-app X-Producer-Cert-Id: vendor-acme-2024Q1 X-Emitted-At: 2024-11-03T14:22:05Z X-Trace-Id: 9a1e... # correlates across every hop X-Payload-Hash: sha256:7d8f... # integrity + tamper evidence
The two that matter most for e-discovery are X-Trace-Id and X-Payload-Hash. The trace ID lets you reconstruct the full path of a single paid hour across every system it touched — capture, enrichment, edit, aggregation, payroll — from logs alone. The payload hash gives you tamper evidence: if the hash logged at receipt matches the hash logged at emission, you can demonstrate the record wasn't altered in transit.
For records that may end up in litigation, this is the difference between producing a clean, defensible chain and handing a lawyer a pile of numbers with no story. Keep the provenance headers in your immutable log tier, not just in the application database, so an edit to the operational record never rewrites the history of what was received.
A vendor-certification checklist for onboarding and auditability
Onboarding a new time-data vendor without a certification gate is how bad contracts get into production. The certification is a go/no-go: the vendor doesn't connect to any production payroll path until every item is satisfied and the evidence is filed.
Use this as the HR/IT onboarding gate:
-
[ ] Vendor signed against a specific contract version (e.g.
time.event v2.1.0), named in the agreement -
[ ] Vendor's sample payloads pass the full consumer conformance suite, including edge-case fixtures
-
[ ] Vendor demonstrated DST-transition and overnight-shift handling with correct
worked_minutes -
[ ] Vendor emits all required provenance headers, verified against a captured trace
-
[ ]
event_idis proven globally unique and stable across retries (idempotency verified) -
[ ] Vendor documented their versioning and deprecation policy and committed to parallel-channel major releases
-
[ ] Payload-hash integrity verified end-to-end on a test batch
-
[ ] Backfill and correction behavior defined
how late edits and retro changes are emitted and flagged
-
[ ] Certification ID issued (
X-Producer-Cert-Id) and recorded in the vendor register -
[ ] Re-certification trigger defined (any major version, or any schema change) before next production release
The register matters as much as the checklist. When a payroll discrepancy surfaces six months later, you want to look up which certified contract version the vendor was on, which conformance run they passed, and when — not reconstruct it from memory. For teams building out the commercial side of these relationships, this certification gate fits directly into a vendor SLA framework for time feeds so the contract clauses and the technical tests reinforce each other.
A realistic scenario: where the contract pays for itself
A mid-market logistics operation ran around 600 hourly staff across a dozen sites, feeding three different capture sources into one payroll system. No canonical contract — just three integrations, each built to whatever the source happened to emit.
One source pushed an "efficiency" update that changed how it reported unpaid meal breaks: previously it subtracted them before sending hours, now it sent gross hours and a separate break field the payroll mapping ignored. For two pay periods, one region was paid for unpaid breaks. The overpay landed somewhere in the $18k–$22k range before anyone caught it, and most of it was unrecoverable.
The cleanup wasn't just the money. It was roughly three weeks of HR, payroll, and IT time reconstructing which events were affected — with no trace IDs and no payload hashes, so the investigation was manual, event by event, across logs that didn't correlate.
After that, they defined a canonical time.event contract with worked_minutes as the authoritative quantity, stood up a consumer conformance suite, and gated all three sources through certification. The next vendor "improvement" that changed break handling failed conformance on the first fixture run — before it ever touched a pay calc. The contract didn't stop vendors from shipping surprises. It made their surprises visible before they became payroll errors.
When this level of rigor makes sense — and when it's overkill
When it's worth it: You have more than one time-capture source, you have multiple vendors or expect to switch, you operate across jurisdictions, or you're large enough that a two-period payroll error costs real money and real trust. The moment time data crosses more than one organizational boundary, informal contracts start costing more than the formal ones.
When it's probably overkill: A single-site business on one time system with a native payroll connector doesn't need a versioned contract spec and a conformance harness. The handoff is internal and stable. Writing YAML contracts for a 15-person shop is process for its own sake.
Who should not start here: If your underlying time data is still a mess — missing punches, inconsistent cost centers, unreconciled edits — a contract won't save you. A contract formalizes clean data; it doesn't clean dirty data. Fix the capture and reconciliation layer first. The architectural groundwork for that, including how events flow and reconcile deterministically, is worth settling before you formalize the interface — the patterns in a canonical time-data architecture make a natural prerequisite.
The workflow, start to finish
Here's how the pieces connect in a mature setup, end to end:
-
HR and Finance agree on the minimal payroll-required fields and sign off on the canonical contract at version 2.0.0.
-
The consumer team builds the conformance suite and an edge-case fixture set from that contract.
-
A new vendor is onboarded
they receive the contract and fixtures, build to spec, and must pass conformance before any production access.
-
On pass, a certification ID is issued and recorded in the vendor register alongside the contract version and conformance run.
-
Every time payload flows with provenance headers — trace ID, payload hash, contract version — logged to an immutable tier.
-
When a vendor ships a release, the same conformance suite re-runs. A true minor passes unchanged; anything that breaks forces a major version and a parallel-channel cutover.
-
During a dispute or audit, any paid hour is reconstructed from its trace ID and verified against its payload hash — provenance on demand, not forensic archaeology.
A visual of this workflow helps teams follow the cutover and certification steps.
Each step removes a place where meaning could silently drift. That's the whole value proposition: not fewer integrations, but integrations that can't quietly lie to payroll.
The reason these contracts matter isn't elegance. Time data is the one operational feed where a small, unversioned, undocumented change turns directly into wrong pay and an audit problem. Everywhere time data crosses a boundary and nobody wrote down what that boundary means, you're accepting a risk you can't see until it costs you.
The templates, versioning rules, conformance tests, and certification gate here aren't about bureaucracy. They're about making the boundaries explicit, testable, and traceable — so when something changes, you catch it in a conformance run instead of a payroll run. Start with the minimal required fields and one canonical contract. The rest builds naturally from there, and every piece you add is one fewer argument nobody wrote down.
Ready to optimize your workforce time management?
Join 2,000+ companies using GoTimio to improve timesheet accuracy, reduce payroll errors, and boost team productivity.