Historical Workers Workflow (Partner Integration Guide)

When a customer is migrating from a previous payroll provider, it’s essential to account for historical worker (workers who were terminated or inactive before the transition). This guide explains how to handle these workers in the integration process to ensure data integrity and accurate payroll records.

📘 What Are Historical Workers?

Historical workers are workers found in the customer’s historical payroll data, such as past pay runs or tax documents, but who are no longer actively employed at the time of Salsa integration.

These are some common reasons workers would be absent in your platform:

• Pre-signup Termination: The worker was terminated before the employer began using your platform, so their data was never captured in the system.
• Out-of-scope Worker Roles: The worker falls outside the core operational focus of your platform. For example, a maintenance contractor for a hair salon may appear in historical payroll records, but would not be tracked in a salon management app that only supports stylists and front-desk staff.

Because of these limitations, historical workers may:

• Be entirely missing from the partner’s employee directory
• Lack a known external identifier (externalId) to match them to the Salsa system
• Miss important tax notification and documents (e.g. W2, 1099)

Salsa’s Handling of Historical Workers

When onboarding a new employer, a Salsa implementation agent may manually create historical workers in the system to backfill payroll history and ensure tax and compliance reporting is complete.

When a historical worker is created in Salsa, the regular Worker.created webhook is triggered, but there are certain attributes to look for:

• terminationDate: The date the worker was terminated.
• terminationCategory: The category of the termination, in this case HISTORICAL
• externalId: This field should come as null in this scenario, indicating the worker was created within Salsa

The webhook provides all the necessary fields for the partner to recognize the worker as historical and determine whether it’s a record they already track.

Recommendations when integrating with Salsa

The Partner platform must listen for the Worker.created webhook event and respond accordingly:

1. Detect Historical Worker scenario:
   • Check if the worker’s externalId is null
   • Check if terminationDate and terminationCategory have values
2. Create and Associate External ID
   • Once created in your platform we recommend updating the externalId reference back to Salsa, using the workerId sent in the webhook. You can either use:
     • Update worker endpoint
     • Paystream - Import worker endpoint, using the UPSERT command