Keeping 7shifts employee and labor data in sync

Key takeaways

Set the synchronization contract around these requirements:

• Define a separate contract for each flow, including its owner, direction, identifiers, required freshness, and correction path.
• Validate employee-to-punch identity relationships before applying labor records downstream.
• Build complete, restartable retrieval so incomplete batches cannot silently advance synchronization checkpoints.
• Treat webhook acknowledgment as receipt, not proof that downstream records reflect the source.
• Keep record capture separate from payroll readiness, preserving approval, break, and time-boundary information.
• Demonstrate corrected downstream state through reconciliation, with unresolved records and processing backlog visible.

Keeping 7shifts employee and labor data in sync requires separate contracts for employee identity, hourly wages, and time punches. A working connection is not the acceptance test.

Unclear ownership can let systems overwrite the wrong values. Unresolved identity mappings can send labor to the wrong employee. Without reconciliation, yesterday's successful import can remain today's incorrect payroll input even after the source has been corrected.

This guide gives integration engineers an operating model for selecting each flow's route and mapping identities. It also covers change retrieval, notification handling, and the checks needed to prove downstream consistency.

Choose a connection route for each flow

Choose each route based on what moves, which system owns it, and when the destination needs it. Native Employee Sync, native Wage Sync, custom inbound labor, and downstream labor retrieval each need their own contract.

Queueing, checkpointing, quarantine and reconciliation below are recommended designs, not 7shifts guarantees.

The 7shifts Employee Sync and Wage Sync guides describe 60-minute checks. Its Labor Integration Overview instead requires near-real-time punch creation for full labor functionality, without specifying a numeric latency SLA.

Use this matrix to separate your freshness requirements from each route's documented behavior:

Do not infer native time-punch support from Employee Sync support. Confirm native punch support and account-specific entitlements for the customer's integration before choosing that route.

After choosing the route, define the identity relationships. Both systems must agree on which employee, assignment, and punch each record represents.

Establish the employee-to-punch identity contract

Map the person separately from their organizational assignments. An employee who works across locations should not become a different downstream person merely because the location changes.

The 7shifts Mapping guide proceeds through locations, departments, roles, and then users. It uses id for user mapping, not employee_id or punch_id. The current List Time Punches sample references the employee through user_id, gives the punch its own ID, and includes company, location, department, and role identifiers.

The guide also allows users to have assignments across locations. A role can attach directly to a location with department_id=0; an absent department relationship must not automatically make that role invalid.

Store these relationships persistently in your integration. The following is a recommended local mapping contract, not a claim about the uniqueness scope of every provider identifier:

Use a quarantine path for unresolved relationships. Retain the source record and the reason you cannot apply it, then replay it after repairing the mapping. Silently dropping the record hides incompleteness; guessing the employee creates misattributed labor.

Build complete, restartable retrieval

Start an incremental reader with a complete scoped baseline. Advance its durable checkpoint only after you have applied the intended batch. A successful page request is not enough.

Pin x-api-version explicitly on every request, as the 7shifts Introduction recommends. The documented modification filter is modified_since; do not substitute updated_since as a verified alias.

Send x-api-version: 2026-01-01, the current published version. Its reference pages are labeled v2.2026.0101, which is a documentation label, not the header value. The older supported 2023-04-01 reference uses a different format for the same filter:

The 7shifts Pagination guide uses limit and cursor. Pass meta.cursor.next to retrieve the next page and finish when it is null. count describes the current page, not the complete collection.

The generic pagination guide gives a default limit of 20 and a maximum of 200 on most endpoints. Endpoint-specific definitions take precedence.

The current List Time Punches reference defaults deleted to false. True selects deleted records; null selects both deleted and non-deleted records. Make that selection explicit in your retrieval contract rather than assuming an ordinary read includes deletions.

An incremental read of approved punches, using an access token (OAuth clients add x-company-guid):

curl -G "https://api.7shifts.com/v2/company/{COMPANY_ID}/time_punches" \
  -H "Authorization: Bearer " \
  -H "x-api-version: 2026-01-01" \
  --data-urlencode "modified_since=2026-10-01T00:00:00Z" \
  --data-urlencode "approved=true" \
  --data-urlencode "limit=100"

{
  "data": [ { "id": 85685660, "user_id": 12345, "location_id": 222, "clocked_in": "2026-10-02T15:12:00+00:00", "clocked_out": "2026-10-02T20:47:00+00:00" } ],
  "meta": { "cursor": { "next": "eyJpZCI6Ijg2MDIzMDM2IiwibmV4dCI6dHJ1ZX0=", "count": 100 } }
}

Repeat with the same filters and cursor set to meta.cursor.next until it comes back null.

Build the retrieval worker around this sequence:

1. Record the request contract: Persist the API version, company scope, filters, modification-time format, and intended deletion selection. On restart, reconstruct the same request scope rather than resuming with today's defaults.
2. Establish the baseline boundary: Define the included employees, locations, and processing period, then record a change-capture boundary before the baseline begins. Complete the baseline and replay modifications from that boundary with an overlap defined by your requirements. Choose boundary precision and overlap for the pinned filter format; do not treat the baseline as an immutable snapshot.
3. Traverse every page: Preserve the original scope and filters while passing each next cursor. Continue until the next cursor is null. A page cursor records traversal state; it does not prove that the synchronization batch is complete.
4. Retrieve deleted state: Include deletion retrieval in the batch contract and apply the corresponding downstream disposition. Verify how your client expresses the documented null selection. Do not mistake an omitted filter for a selection of both states.
5. Apply replay-safe local changes: Upsert using persistent source-to-destination identities, handle repeated work safely, and retain unresolved records with their exceptions. Persist enough run state to recover unfinished work without treating partial application as completion.
6. Commit the durable checkpoint: Advance only after you have durably applied the intended batch under your exception policy. On interruption, resume or replay from the last committed boundary. Keep any saved page cursor tied to its original request scope.

Budget rate usage separately within this worker. The 7shifts Integrating Payroll / EWA guide specifies 10 requests per second per token across endpoints. Its Errors reference separately documents 600 requests per minute and a one-minute block after exceeding that limit.

Budget aggregate work against both descriptions. They do not establish identical enforcement windows or scope, so arithmetic equivalence is not evidence of a permitted burst. When throttled, preserve unfinished work and reschedule it without advancing the checkpoint.

OWASP's API9:2023 inventory guidance recommends inventorying hosts and versions and documenting authentication, errors, redirects, rate limiting, endpoints, parameters, requests, and responses. Keep that documented contract beside the worker configuration, and treat a version change as an explicit implementation change.

For additional traversal background, see the keyset pagination guide. The 7shifts Pagination reference remains the authority for this provider's cursor behavior.

Use notifications to accelerate detection, not replace recovery

Use change notifications to schedule state refreshes. Retain incremental retrieval and reconciliation as recovery paths. A successful webhook acknowledgment must not be treated as proof that the downstream record is current.

The 7shifts Configure Company Level Webhooks reference selects an event, topic, and notification URL. It lists user creation, modification, deactivation, and reactivation topics.

Its Integrating Payroll / EWA guide identifies time_punch.created, time_punch.edited, and time_punch.deleted. Edited events can also notify approval changes, so a punch notification can matter even when the worked interval has not changed. 7shifts also sends payroll_period.closed, covered below.

Two constraints shape the receiver. First, 7shifts webhooks are unauthenticated: your endpoint has to accept unsigned POSTs. Treat every payload as a prompt to re-read through the API, never as data to apply, and do not expose a guessable URL. Second, company-level webhooks require a Premium (formerly Gourmet) plan or higher, and OAuth partners arrange webhooks by emailing 7shifts API support. Confirm both before you design around notifications.

Separate receipt from processing with this sequence:

1. Configure the required notifications: Select the documented user topics and punch events relevant to your contract. Do not infer additional event coverage or delivery behavior from those names.
2. Capture work and acknowledge promptly: Where the implementation permits it, durably capture actionable work before returning a successful response. The 7shifts guidance calls for a prompt 2xx response without complex synchronous processing. Keep state refresh and downstream application outside the receiver's critical path.
3. Refresh and apply state: Use persistent record identities and local processing history to make duplicate work safe. If you cannot establish an event's freshness, retrieve authoritative state rather than treating its payload as the latest revision. Retain unresolved event-to-record relationships for recovery.
4. Validate structure and real joins separately: The provider's test payload has valid structure but invalid company values. Use it to test parsing and receiver behavior, not to prove customer-record joins. Validate those joins separately against the intended company's records.
5. Recover through retrieval: Run catch-up retrieval and reconciliation when notifications are absent, unresolved, or inconclusive. Reprocess unresolved work after repairing mappings or restoring processing. Do not depend on an unverified retry count, event order, or exactly-once delivery contract.

Monitor receiver health, processing health, and synchronized-state health separately. Check acknowledgment and errors at the receiver, and unapplied work and failures in processing. Assess state health by comparing downstream state with the authoritative records.

For the employee assigned across locations, a healthy receiver does not prove that a corrected punch reached the right downstream person. Only applied state and reconciliation can establish that.

Separate captured punches from payroll-ready inputs

A punch can be synchronized while still open or awaiting approval. Preserve it as a processing state rather than silently dropping it or treating unapproved work as unpaid.

The current 7shifts List Time Punches reference defaults approved to null, returning approved and unapproved records; true selects approved records. employee_approval_statuses is a separate filter. The Integrating Payroll / EWA guidance calls for approved punches in the processing flow and distinguishes paid from unpaid breaks.

Define how to interpret each concern below before calculating downstream totals:

Use the payroll period as the readiness signal

7shifts already models payroll readiness. Its Payroll Period endpoints return each pay period with per-location states[] and a company-wide finalized flag that turns true only when every location has closed the period. With include_punches_status=true, each period also reports all_punches_approved and employee_punch_approvals. Subscribe to payroll_period.closed to hear when a period, or one location's part of it, closes, then re-read the period before pulling its punches.

curl -G "https://api.7shifts.com/v2/time_clocking/payroll_periods" \
  -H "Authorization: Bearer " \
  -H "x-api-version: 2026-01-01" \
  --data-urlencode "company_id=12345" \
  --data-urlencode "include_punches_status=true"

The period record holds dates and status, not hours. Pull time punches for its start and end, then apply the interpretation rules in the table above.

Two defaults from 7shifts' help center catch payroll exports out. Punches synced from a POS are marked Employer Approved by default, even when the clock-out is missing. And a punch with no clock-out gets a default clock-out of midnight UTC so a duration can be computed. An approved punch ending at exactly midnight UTC is a review item, not a payable shift.

Under the U.S. Department of Labor's 29 CFR §§785.18-785.19, short rest periods, generally 5 to about 20 minutes, count as hours worked. Bona fide meal periods require complete relief from duty; ordinarily 30 minutes or more is sufficient, although shorter periods are possible under special conditions. Duration alone does not determine compensability.

Use that federal boundary to surface conflicts, not to automatically subtract every break. It is not a complete state-law or payroll-compliance model, and elapsed time multiplied by a wage rate is not a complete payroll engine.

Date-range searches in the current 7shifts punch reference default to UTC. localize_search_time enables local-time interpretation. Decide which interpretation matches your processing period before retrieving its records.

The IETF explains in RFC 9557 §1.2 that a UTC offset does not encode a location's time-zone rules. Named time zones support local-time operations across offset changes, including daylight-saving transitions. RFC 9557 extends and updates RFC 3339, but that does not establish that 7shifts accepts its extended timestamp syntax.

A punch crossing local midnight therefore needs more than a stored offset to establish its payroll-date treatment. Keep your internal time-zone representation separate from the timestamp syntax accepted by the provider.

Prove consistency after corrections and interruptions

To prove synchronization, compare eligible source records with downstream records and calculated totals. Scope those comparisons by company, employee, location, and processing period. Last-success timestamps alone cannot demonstrate correction handling.

The 7shifts Introduction notes that managers can retroactively correct punches and recommends re-reading a trailing window rather than processing only new records. Its Integrating Payroll / EWA guidance recommends synchronizing between 08:00 and 15:00 UTC on the payroll-processing day or preceding day to capture recent corrections. That is a recommendation, not an exclusive permitted synchronization window.

Punches from native POS integrations add one more limit. 7shifts' help center says that once a punch is recorded after clock-out, later edits in the POS do not sync to 7shifts. A correction made only in the POS never reaches your reads; it has to be made in 7shifts.

Define the evidence needed to pass or fail each consistency condition:

Measure freshness from the last successfully applied source state, not the last request or webhook received. Choose trailing-window length, tolerances, and numerical acceptance thresholds from the downstream requirements; this operating model supplies no universal value.

Before accepting the integration, test these failure and correction cases:

• Replay an already applied batch and verify that effective downstream records and totals remain unchanged.
• Interrupt retrieval after a page and interrupt processing before checkpoint commit, then verify that recovery completes the intended scope.
• Correct a previously imported punch and verify that its downstream revision and affected totals change accordingly.
• Move a punch through an approval transition and close an open punch, then verify that capture and processing eligibility remain distinct.
• Delete an imported punch and verify its downstream disposition through the explicit deletion-retrieval path.
• Process labor around local-date and offset changes for an employee assigned across locations, then verify attribution and period membership.

Require an exception disposition before processing close. Record the decision to repair, hold, or accept an unresolved case under your processing policy. An unresolved backlog must not disappear behind a green connection indicator.

These checks define the behavior your infrastructure must deliver. Use them to decide whether a route can meet the contract, including its freshness and correction-recovery requirements.

Evaluate whether a unified API fits the contract

Hold a unified API to the same ownership, identity, freshness and reconciliation requirements as a direct build.

Bindbee has a live 7shifts connector, and its shape decides which flows it can serve. It is read-only: per Bindbee's model availability matrix, it reads Employee, Employment, Compensation, Company, Group, Location, Time Off and Timesheet Entry, and writes nothing to 7shifts.

Freshness decides the labor flow. Bindbee syncs every 24 hours by default, adjustable on request, and sends webhooks after each sync. Each event carries an id for deduplication and a per-connector sequence for ordering, and reports what that sync found. If your export runs on the payroll day, schedule or force a sync inside 7shifts' recommended 08:00 to 15:00 UTC window so recent corrections are in it.

Recovery keeps an owner. Bindbee retries a failed webhook delivery up to four times within about a minute and has no replay. Missed events are recovered by reading with modified_after from the start of the gap, which is the same reconciliation discipline this guide applies to 7shifts directly.

To check your objects and flows against the connector, see the 7shifts integration page or book a requirements review.

Frequently asked questions

Does 7shifts support webhooks?

Yes, for time punch created, edited and deleted, schedule.published, payroll_period.closed, user events and authorization.revoked. They are unsigned, company-level webhooks need a Premium plan or higher, and OAuth partners request them by email.

How do I know when 7shifts payroll data is ready to export?

Listen for payroll_period.closed, then re-read the payroll period. Its finalized flag turns true once every location has closed, and include_punches_status=true adds all_punches_approved.

Why do POS punches show as approved without a clock-out?

7shifts marks punches synced from a POS as Employer Approved by default, even when the clock-out is missing, and gives a missing clock-out a default of midnight UTC. Treat an approved punch ending at exactly midnight UTC as a review item.

How do I match 7shifts time punches to employees?

Time punches reference the employee through user_id, and 7shifts' Mapping guide maps users by id, not employee_id. Map the person separately from location and role assignments, since one user can work across locations.

Does 7shifts Wage Sync overwrite wages?

Yes. Wage Sync checks every 60 minutes, runs one way from the POS into 7shifts, covers hourly wages only, and overwrites manual changes made in 7shifts.