Skip to main content

​
Async Payroll Import Routing, User Status Enhancements, and State Registration Validation Metadata

This release introduces intelligent routing for payroll imports, improves user status response compatibility for hybrid integrations, and expands state registration metadata so clients can render better validation guidance.

​
Highlights

  • Async payroll import routing: payroll and differential payroll imports now route automatically based on company feature flag and payload size. Payloads under 10 employees are always processed synchronously to avoid impacting integrators who send individual import requests.
  • importMethod override: callers can now force a specific processing path via the new importMethod field, independent of the feature flag or payload size.
  • Enhanced user status payload: getUser now returns onboarding status detail fields by default for better hybrid integration support.
  • State registration validation metadata: state registration responses now include validationFormat when a state tax item has a configured display format.
  • updatePaySchedule usage clarification: use updatePaySchedule only to switch pay schedule mode between Self Initiated and Automatic.

​
New Features

​
🔹 Async payroll import routing (importRegularPayrollData, importRegularDifferentialPayrollData)

Both the regular and differential payroll import endpoints now share a unified routing model. The path taken is determined in the following priority order: 1. Explicit importMethod override (highest priority) Include importMethod in the request body to force a specific processing path regardless of feature flag or payload size:
2. Async Payroll Import feature flag + employee count When no importMethod is provided and the Async Payroll Import feature flag is enabled for the company: Payloads under 10 employees are processed synchronously so that integrators who send individual or small-batch import requests are not affected by the async queueing lifecycle.

​
🔹 updatePaySchedule endpoint

The updatePaySchedule endpoint can be used to change pay schedule mode only.
  • Supported usage: flip pay schedules between Self Initiated and Automatic modes.
  • For any other pay schedule detail changes, do not use updatePaySchedule. Instead, use this flow:
  1. deactivatePaySchedule
  2. addPaySchedule
This guidance ensures schedule updates are applied through the expected lifecycle.

​
🔹 Enhanced getUser status payload

The getUser endpoint now returns onboarding status detail fields under status by default.
  • generalInformationComplete
  • jobInformationComplete
  • inviteSent — Informational only. Invite sent is not required for an employee to become active. This field is useful for hybrid integrations because it indicates whether the employee has been invited to the Rollfi white-label experience.
  • onboardingComplete
  • bankAccountLinked — Informational only. Bank account linking is not required when an employee is configured for check payments.
  • i9Verification — Only returned when I-9 verification is provisioned for the employee. Contains the current I-9 verification status label. Employees without I-9 verification provisioned will not have this field in the status object.
The status.userStatus field remains present for compatibility. inviteSent is informational only, and is specific to hybrid integrations that use the Rollfi white-label for the employee experience. bankAccountLinked is only required to become active if the employee is configured for direct deposit. Employees configured for check payments do not need to link a bank account. i9Verification is conditional — do not require it in strict response models; it is omitted entirely unless I-9 verification is provisioned for the employee. ⚠️ Warning: The expanded status breakdown is only returned for employees in the Add Wage, Invite Sent, and Active statuses. Deactivated and Terminated employees return status.userStatus only, since the onboarding status breakdown is not required for these employees.

​
🔹 State registration validationFormat

State registration responses now surface a validationFormat value for each field when a configured display format exists in CompanyRefStateTaxItems.DisplayFormat. Example response:
This metadata is intended to help client applications present more precise validation and input guidance for state registration forms. At this time, the addStateRegistration and updateStateRegistration methods do not yet enforce these validationFormat values server-side. They are currently provided as response metadata only. Enforcement is planned for a coming update, so integrators should begin aligning client-side validation now.

​
⚠️ Notes for Integrators

📝 If your client deserializes status (returned by getUser) into a strict model, update it to support the expanded status object.
  1. Review payroll import payloads — no changes are required for payloads under 10 employees; they will continue to process synchronously.
  2. For large payroll payloads (≥ 10 employees), confirm the Async Payroll Import feature flag is enabled with your Rollfi account team if you want async routing.
  3. Use importMethod: "synchronous" or importMethod: "asynchronous" to override routing behaviour explicitly when needed.
  4. Update getUser consumers with strict response models to support the expanded status object.
  5. Treat fieldDescription.validationFormat as optional and only apply it when present.
  6. Verify state registration form rendering for states with configured DisplayFormat values.
  7. Restrict updatePaySchedule usage to mode flips between Self Initiated and Automatic.
  8. For other pay schedule changes, migrate callers to deactivatePaySchedule + addPaySchedule.