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

# Tax Form Runs

> List, filter, and run W-2, quarterly, annual, and 1099-NEC tax form runs through generation, filing, distribution, and e-filing.

The Tax Form Runs page lists all tax form runs with filtering controls and provides dialogs to initiate new runs for each supported form type. It is served at route `/hr/payroll/tax-forms/runs`.

## Overview

The page uses `useTaxFormRuns` with server-side filters for tax year, form type, status, and quarter. Filter controls are rendered above the run list. A "New Run" dropdown button opens the appropriate creation dialog based on form type:

* `CreateW2RunDialog` — W-2
* `CreateQuarterlyRunDialog` — quarterly forms (941, AZ-A1-QRT)
* `CreateAnnualRunDialog` — annual forms (940, AZ-A1-R)
* `Create1099NECRunDialog` — 1099-NEC

Each run card links to the run detail page. Supported form types and statuses are defined in `TAX_FORM_TYPES`, `TAX_FORM_STATUSES`, `TAX_FORM_TYPE_LABELS`, and `TAX_FORM_STATUS_LABELS`.

No `RequirePermission` guard on this route (Tax Form Settings requires `HR_PERMISSIONS.PAYROLL_ADMIN`; confirm access controls with SME).

## Who it's for

Access follows your organization's role and module configuration. SME: confirm whether `hr.payroll.admin` is required.

## Before you start

* Employer tax configuration must exist for the target tax year at `/hr/payroll/tax-forms/settings`.

## Steps

**View runs**

1. Navigate to **HR > Payroll > Tax Forms > Runs** or go to `/hr/payroll/tax-forms/runs`.
2. Use the **Year**, **Type**, **Status**, and **Quarter** filters to narrow the list.
3. Click a run card to open the detail page.

**Create a new run**

1. Click the **New Run** dropdown (top right).
2. Select the form type (W-2, Quarterly, Annual, 1099-NEC).
3. Complete the creation dialog and confirm.

## Key concepts

| Term         | Meaning                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------- |
| Tax form run | A batch job that generates tax form line items for a specified form type, year, and period.    |
| Quarter      | Applicable for quarterly forms (1, 2, 3, or 4).                                                |
| Form type    | W-2, 941, 940, AZ-A1-R, AZ-A1-QRT, 1099-NEC (values from `TAX_FORM_TYPES`).                    |
| Run status   | Lifecycle state of the run (values from `TAX_FORM_STATUSES`). SME: confirm all valid statuses. |

## Viewing a tax form run

The Tax Form Run Details page manages a single tax form run through its lifecycle, from item generation to distribution or e-filing. It is served at route `/hr/payroll/tax-forms/runs/:runId`.

The page loads run data via `useTaxFormRunById`, items via `useTaxFormItems`, and employer config via `useEmployerTaxConfigByYear`. It renders:

* A status badge (`TaxFormRunStatusBadge`) and breadcrumb navigation.
* `FilingMethodRadio` to select paper vs. e-file.
* `EFileStatusCard` for e-file status and credential check.
* `W2PreviewCard` for individual item previews.
* Action buttons: generate items, finalize and distribute, delete run, create W-2 correction.
* `useGenerateW2Pdf` for PDF download.

No `RequirePermission` guard is present on this specific route, but access should be limited to payroll administrators. The Tax Form Settings route (parent) requires `HR_PERMISSIONS.PAYROLL_ADMIN` (`hr.payroll.admin`). Confirm access controls with SME.

Before you start: employer tax configuration for the relevant tax year must exist at `/hr/payroll/tax-forms/settings`. E-file credentials must be configured before e-filing is available.

1. Navigate to **HR > Payroll > Tax Forms > Runs** and click a run, or go to `/hr/payroll/tax-forms/runs/:runId`.
2. Review the run summary (form type, tax year, period, status).
3. If items have not been generated, click the generate action to create tax form line items.
4. Select the **Filing Method** (paper or e-file).
5. Review items and preview W-2 PDFs as needed.
6. When ready, use the **Finalize & Distribute** action to send forms.
7. For corrections, use **Create W-2 Correction**.

**Key detail concepts:**

| Term           | Meaning                                                                                  |
| -------------- | ---------------------------------------------------------------------------------------- |
| Tax form run   | A batch execution for a specific form type, tax year, and period (e.g., W-2 annual run). |
| Filing method  | Paper (manual distribution) or e-file (electronic submission).                           |
| E-file status  | Current state of an electronic filing submission via the configured e-file credential.   |
| W-2 correction | An amended W-2 (W-2c) generated to correct a previously distributed form.                |

## Generating a new hire report

The New Hire Report page at `/hr/payroll/tax-forms/new-hire` (`NewHireReportPage`, HR-PAY-04) supports state new hire reporting workflows. It lists recently hired employees within a configurable date range and allows administrators to select records and export them as a CSV file. Records can also be marked as reported after filing. By default the view shows unreported-only records; the date range defaults to the most recent 20 days.

**Key concepts:**

* **Unreported** — A new hire record that has not yet been marked as reported to the relevant state agency.
* **CSV Export** — A comma-separated values file generated from the selected records for use in filing.

Before you start: ensure employee hire dates are accurately recorded in the system; determine the date range and reporting period required by the filing agency.

1. Navigate to `/hr/payroll/tax-forms/new-hire`.
2. Adjust the **Start Date** and **End Date** fields as needed.
3. Use the **Unreported only** toggle to show or hide previously reported hires.
4. Select the employee rows to include in the report.
5. Click **Download CSV** to export the report file.
6. After filing, mark the records as reported using the available action.

## Related

<Columns cols={2}>
  <Card title="Human Resources" icon="users" href="/hr/overview">
    Human Resources core overview.
  </Card>

  <Card title="Governance & parity" icon="scale-balanced" href="/governance/index" />
</Columns>

<Note>
  This page documents shipped product behavior. It is not medical, legal, or
  billing advice. Verify against your organization's policies and applicable
  regulations before using it for clinical, compliance, or billing decisions.
  Protected health information (PHI) shown in the product is governed by your
  tenant's access controls and is never exposed in this documentation.
</Note>

<Accordion title="Documentation sources">
  * src/routes/hr.tsx
  * src/cores/hr/pages/TaxFormRunsPage.tsx
  * src/cores/hr/pages/TaxFormRunDetailPage.tsx
  * src/cores/hr/pages/NewHireReportPage.tsx
  * src/cores/hr/hooks/tax-forms/useTaxFormRuns.ts
  * src/cores/hr/hooks/tax-forms/useTaxFormItems.ts
  * src/cores/hr/hooks/tax-forms/useTaxFormRunMutation.ts
  * src/cores/hr/hooks/useNewHireReport.ts
  * src/cores/hr/services/new-hire.ts
  * src/cores/hr/types/tax-forms.ts
</Accordion>