HR & Employment · Internal Revenue Service

Fill IRS Form W-4 programmatically from your payroll data.

Send SimplyFill the employee's withholding inputs as plain JSON and get back a correctly-filled, flattened W-4 — without ever touching the form's opaque AcroForm field names yourself.

Start free trial Read the quickstart

What is Form W-4?

Form W-4, Employee's Withholding Certificate, tells an employer how much federal income tax to withhold from a paycheck. The 2020 redesign replaced allowances with dollar-amount steps for dependents, other income, deductions, and extra withholding.

Who files it?

Every U.S. employee completes a W-4 at hire and whenever their tax situation changes. Employers keep it on file and feed the values into payroll.

Why filling Form W-4 by hand hurts

The W-4 is an IRS AcroForm, which means its fields are named things like `topmostSubform[0].Page1[0].f1_05[0]` — not `first_name`. Figuring out which `f1_NN` maps to "extra withholding" versus "dependents amount" is a half-day of trial and error per form. SimplyFill hides that behind readable aliases.

Fill Form W-4 in one call

Fill a W-4 from readable payroll fields

fill-w-4.ts

Node.js

const res = await fetch('https://api.simplyfill.app/v1/generate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SIMPLYFILL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    template: 'w4_2025',
    // Your aliases — SimplyFill maps these to f1_01[0], f1_02[0], ...
    data: {
      first_name: 'Ada',
      last_name: 'Lovelace',
      ssn: '123-45-6789',
      filing_status: 'single',
      dependents_amount: 0,
      extra_withholding: 50,
    },
  }),
})

const { url } = await res.json()

Fields on Form W-4

Real form fields are named for the PDF spec, not for humans — so a single value can hide behind something like topmostSubform[0].Page1[0].f1_02[0]. SimplyFill lets you map your own readable keys to these once, then forget they exist.

Raw PDF field name	What it means
topmostSubform[0].Page1[0].f1_01[0]	First name and middle initial
topmostSubform[0].Page1[0].f1_02[0]	Last name
topmostSubform[0].Page1[0].f1_05[0]	Social security number
topmostSubform[0].Page1[0].c1_1[0]	Filing status (single / married / head of household)
topmostSubform[0].Page1[0].f1_09[0]	Step 3: dependents claim amount
topmostSubform[0].Page1[0].f1_11[0]	Step 4(c): extra withholding per pay period

Frequently asked questions

Do I have to learn the W-4’s AcroForm field names?

No. You define a mapping once (or use the default) that aliases readable keys like `extra_withholding` to the underlying `topmostSubform[0].Page1[0].f1_11[0]`. After that you only ever send your own field names.

How are the filing-status radio buttons handled?

The three filing-status options share a radio group (`c1_1[0]`). You send a single `filing_status` string and SimplyFill selects the correct export value, so you never deal with the on/off states directly.

Can I generate a W-4 and an I-9 in the same request?

Yes. Use the bulk endpoint with an array of templates and a single data payload; SimplyFill returns one download URL per document plus a combined envelope.

Is the dollar-amount (post-2020) W-4 supported?

Yes — the templates track the current redesigned W-4 with Steps 2–4. Allowance-era forms are not supported because the IRS no longer publishes them.