> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rollfi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# August 3, 2026 Release

# 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:

| Value            | Behaviour                          |
| ---------------- | ---------------------------------- |
| `"synchronous"`  | Always processes synchronously     |
| `"asynchronous"` | Always queues for async processing |

```json theme={null}
{
  "companyId": "...",
  "payPeriodId": "...",
  "importMethod": "synchronous",
  "payrollData": [...]
}
```

**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:

| Employee count | Processing path |
| -------------- | --------------- |
| **\< 10**      | Synchronous     |
| **≥ 10**       | Asynchronous    |

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:

```json theme={null}
{
  "code": "WA",
  "companyStateRegistrationFieldList": {
    "ESD Account Number": "",
    "Unified Business Identifier (UBI)": ""
  },
  "fieldDescription": {
    "ESD Account Number": {
      "isMandatory": true,
      "validationFormat": ""
    },
    "Unified Business Identifier (UBI)": {
      "isMandatory": true
    }
  }
}
```

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

| Area                                   | Change                                                                                     | Action                                                                                              |   |                    |                                                       |                                                                      |
| -------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | - | ------------------ | ----------------------------------------------------- | -------------------------------------------------------------------- |
| `importRegularPayrollData`             | Now routes sync or async based on importMethod (if included) employee count                | No action required — payloads under 10 employees are always sync                                    |   |                    |                                                       |                                                                      |
| `importRegularDifferentialPayrollData` | Same routing logic as regular import                                                       | No action required — payloads under 10 employees are always sync                                    |   |                    |                                                       |                                                                      |
| `importMethod` field                   | New optional field to override routing behaviour                                           | Use `"synchronous"` or `"asynchronous"` to force a specific path when needed                        |   |                    |                                                       |                                                                      |
| `getUser` response                     | Onboarding status detail fields are now returned by default                                | Ensure strict response models allow the expanded `status` object                                    |   | State registration | `fieldDescription` may now include `validationFormat` | Update clients to read the field when present, but do not require it |
| State registration writes              | `addStateRegistration` and `updateStateRegistration` do not yet enforce `validationFormat` | Do not assume server-side format validation yet; prepare clients for enforcement in a future update |   |                    |                                                       |                                                                      |
| `updatePaySchedule` requests           | Intended for mode flips only (Self Initiated ⇄ Automatic)                                  | Use `updatePaySchedule` only for payment mode changes                                               |   |                    |                                                       |                                                                      |

📝 If your client deserializes `status` (returned by `getUser`) into a strict model, update it to support the expanded status object.

## Recommended Next Steps

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`.