The Multi State Compliance Guide

The jurisdiction table is seeded with 61 entries the first time a tenant with HR access logs in. Fifty are US states. Eleven are international: Canada, the United Kingdom, Ireland, Germany, France, Australia, Singapore, India, Brazil, Mexico, and Japan. The seed lives in the schema migration that ships with HR (revision 0104), which means every tenant starts from the same canonical list.

Each row stores:

• code: the canonical identifier we use in queries (for example, US-CA, GB, DE).
• name, country_code, region_code: display labels for the picker UI and the filter chips.
• tax_authority: the relevant agency name (for example, California Franchise Tax Board, HMRC).
• employment_law_notes: a short text field flagging the quirks an HR ops lead needs to remember (at-will exception states, right-to-work, ban-the-box localities).
• min_wage_cents, overtime_rule, paid_sick_leave_required:the three machine-checkable fields the scan engine cares about directly.

Four compliance requirements ship as global rows: SOC 2, cyber insurance, breach notification windows, and data residency. They are stored withtenant_id IS NULL in the requirements table, which is the convention we use for entries that every tenant inherits without duplication.

Tenants can layer their own requirements on top by inserting rows scoped to their tenant_id. The scan engine evaluates the global set plus the tenant set in one pass, and drift detection treats both the same way. That means a customer who needs to add HIPAA, FedRAMP, or PCI does not redefine SOC 2 from scratch; they insert the new rule and inherit the existing one.

The Run Scan button on /hrdashboard/compliance calls POST /v1/hr/compliance/scan. The endpoint walks every applicable requirement (global plus tenant-scoped, filtered by jurisdictions where you employ people), evaluates the latest evidence per requirement, and writes back two numbers: evaluated (how many requirements were checked) and drift_count (how many came back missing, expiring, or expired).

Drift items do not stop at the compliance page. Each one becomes an inbox card with a severity assigned by the scan engine: missing evidence for a SOC 2 control surfaces as CRITICAL; an expiring training certificate becomes WARNING. The compliance page and the inbox view show the same items from two angles.

The compliance page splits the same data three ways:

• Drift: evidence that is missing, expiring within the cadence window, or already expired. This is the queue you work; an auditor expects this list to be short and shrinking.
• All Requirements: the source-of-truth catalog. Every requirement that applies to your jurisdiction set, regardless of status.
• Met: the green-light view. Requirements with current evidence, ready to screenshot for a board deck or a prospect security review.

Adding an employee in a new state changes your nexus footprint, and the engine recomputes accordingly. When you set primary_jurisdiction on a new hr_employees row, the next scan picks up that jurisdiction's minimum wage, overtime rule, paid sick leave requirement, and any state-specific training that ships in the requirements catalog.

work_jurisdictions is an array on the same row, used for employees who travel or work across borders regularly. The scan treats the union of primary and work jurisdictions as the applicable set, so a New York employee on a six-month rotation in California shows up under both states until the rotation ends.

Some compliance requirements are universal; others are deeply jurisdiction-specific. The four global requirements (SOC 2, cyber insurance, breach notification, data residency) apply regardless of where your people work. Most state-specific rules (US minimum wage, US overtime classifications, US sick leave) do not extrapolate to other countries.

For international tenants, the engine reads the country-level fields (paid_sick_leave_required, employment_law_notes) and applies the global requirements. Country-specific rules (GDPR data subject rights, UK holiday pay calculations, Canadian provincial overtime) ship as named requirements that any tenant can subscribe to. The pattern lets a US company with a UK subsidiary work from one inbox without maintaining two compliance programs.

We recommend a weekly scan as the minimum cadence. Most teams run nightly and watch the inbox for fresh drift cards in the morning. Scans are cheap; staleness is expensive. Each requirement carries a cadence (annual for SOC 2 attestation, monthly for cyber insurance proof of coverage) and an expiration window. The engine surfaces a card 30, 14, and 7 days before expiration so a missed renewal becomes an open ticket, not a surprise.

For teams with formal compliance SLAs, the recommended pattern is to schedule the nightly scan at 02:00 local time and review fresh cards by 10:00 the next morning. Eight hours is enough lead time to chase evidence from a vendor or remind an employee to renew a training certificate.

The same scan, requirement list, and evidence catalog are reachable via REST. GET /v1/hr/compliance/requirements returns the applicable catalog. GET /v1/hr/compliance/evidence returns the latest evidence per requirement. POST /v1/hr/compliance/scan kicks off a fresh evaluation. Each response carries enough metadata that a CI pipeline can fail a release if a requirement drifts.

We have seen teams wire the scan into their security review workflow: every prospect questionnaire kicks off a scan, every drift card surfaces in the security channel, and the questionnaire response is auto-drafted from the latest Met list. That pattern turns compliance from a quarterly scramble into a continuous artifact.