What does the Build State SUI/SUTA Wage File (ICESA Fixed-Width) skill do?

Convert quarterly per-employee payroll into a state unemployment-insurance wage-detail file in the ICESA fixed-width layout — A/B/E/S/T/F record sequence, state account number, taxable-wage-base capping and excess wages, cents formatting, reconciliation, and a worked example (state-specific — confirm the target state's spec)

How do I run the Build State SUI/SUTA Wage File (ICESA Fixed-Width) skill?

Copy the skill and paste it into your own Claude or ChatGPT, then provide your source data. FinchContext skills run inside your own AI assistant, so your financial data never leaves your control.

Which region does the Build State SUI/SUTA Wage File (ICESA Fixed-Width) skill cover?

United States. It targets the local tax authority / e-invoicing format described on this page.

Build State SUI/SUTA Wage File (ICESA Fixed-Width)

Skill: Convert quarterly payroll into a state unemployment-insurance wage-detail file

Region: United States Category: Payroll Does: Takes a quarter's per-employee wage data and assembles the ICESA fixed-width wage-detail file that employers (and reporting agents/payroll providers) upload to state workforce agencies for State Unemployment Insurance (SUI / SUTA) quarterly wage reporting. Spec: ICESA (Interstate Conference of Employment Security Agencies) fixed-width record layout

SUI wage reporting is state-specific. Most states accept the ICESA layout (or the closely related SSA EFW2/MMREF style), but each state customizes the optional fields, the state-specific positions in the S record, and the accepted upload channel — some states require their own CSV/XML instead. Always validate against the target state's current wage-file specification. The positions below are the common ICESA structure, not any one state's verbatim map.

When this applies

Employers liable for state unemployment tax file a quarterly wage report (per-employee names, SSNs, and gross wages) and a contribution/tax return to each state where they have covered employees.
Due dates are quarterly, typically the last day of the month following the quarter (Apr 30 / Jul 31 / Oct 31 / Jan 31) — confirm per state.
Many states mandate electronic filing above a small employee count; bulk filers/payroll services almost always file electronically.

ICESA record sequence

A  Transmitter Record        (once, first — who is sending the file)
B  Authorization / Basic     (transmitter software + authorization)
E  Employer Record           (one per employer: EIN, state account no., quarter)
  S  Employee Wage Record     (one per employee under that E)
T  Total Record              (totals for the preceding E's S records)
F  Final Record              (once, last — file grand totals)

Each E opens an employer block; its T closes it with control totals; F ends the file.

Key fields by record

A — Transmitter

Field	Notes
Record identifier `A`	position 1
Transmitter FEIN, name, address	who submits
Media/transmitter contact	name, phone, email

E — Employer

Field	Notes
Record identifier `E`
Payment year + quarter	e.g. `2025` + `1` (Q1)
Federal EIN	9 digits
State unemployment account number	the state-assigned employer ID
State code (FIPS)	the reporting state
Employer name, address

S — Employee Wage (the core)

Field	Notes
Record identifier `S`
Employee SSN	9 digits, no dashes
Employee last / first / middle name
State QTR total gross wages	cents, right-justified, zero-filled
State QTR UI total wages	wages subject to UI (capped at the state taxable wage base)
State code
Number of weeks worked / other state fields	state-specific (some require hours, weeks, officer/seasonal codes)

T — Total (per employer)

Field	Notes
Record identifier `T`
Number of `S` records	count of employees
Total gross wages, total UI wages, total excess wages	sums for the block
Taxable wages, tax due (if file also carries contribution)	where the state combines wage + tax

F — Final

Grand totals: number of E and S records and total wages across the file.

Data rules

All records are fixed-width (commonly 275 bytes in classic ICESA — confirm the state's length); pad with spaces, money fields right-justified and zero-filled in cents, no decimal point ($5,000.00 → 000000500000).
SSNs and EINs are 9 digits, no dashes; names follow the state's justification rules.
UI/taxable wages are capped at the state's taxable wage base per employee per year — Q-over-Q, only wages up to the base are taxable; the excess is the difference between gross and taxable.
T totals must reconcile exactly with the sum of the block's S records; F totals must reconcile with all blocks.

Worked example (one employer, two employees, Q1)

State taxable wage base assumed $9,000/employee/year; Q1 gross = full quarter:

E  Year=2025 Qtr=1 EIN=123456789 StateAcct=0001234-5 State=CA Name=ACME LLC
  S  SSN=123456789 Name=DOE JANE     GrossQtr=1500000 UIWagesQtr=900000   (gross $15,000; UI capped at $9,000)
  S  SSN=987654321 Name=ROE RICHARD  GrossQtr= 600000 UIWagesQtr=600000   (gross $6,000; under base, all taxable)
T  CountS=2 TotalGross=2100000 TotalUIWages=1500000 TotalExcess=600000
F  CountE=1 CountS=2 TotalGross=2100000

(Jane's gross $15,000 = 1500000 cents but only the first $9,000 = 900000 is UI-taxable; her $6,000 over the base is excess. Each line is then written as a fixed-position ICESA record for the target state.)

Validation checklist

Target state's current wage-file spec confirmed (ICESA vs. state CSV/XML; record length; state-specific S fields)
One A first, one F last; E…T block per employer/state account
State unemployment account number present and correctly formatted in E
Each S has a valid 9-digit SSN and the employee name
UI/taxable wages capped at the state taxable wage base; excess computed as gross − taxable
Money fields in cents, right-justified, zero-filled, no decimals/symbols; records padded to length
T totals reconcile with S records; F reconciles with all blocks
Correct payment year/quarter; quarterly deadline met; uploaded via the state's accepted channel

Last updated: 2026-05-31 — SUI wage reporting is per-state; confirm the target state's record layout, length, state-specific S-record fields, taxable wage base, accepted format/channel, and deadline against the current state workforce-agency specification before use.