# Standard Forms Library

> Clone Korala-curated government forms (IRS, USCIS, DOL, VA, GSA) into your templates

Source: https://docs.korala.ai/guides/standard-forms

---

Korala maintains a catalog of official forms with the field mapping already done: canonical names (`legal_name`, `ssn_area`, `federal_tax_classification`) instead of the IRS's cryptic AcroForm names, the choose-one and validation rules pre-set, and revisions tracked for you. You clone a form into your own template, bind your data, and send. No PDF wrangling, no field placement, no re-mapping when the IRS ships a new revision.

The catalog ships 20 forms from five publishers:

- **IRS tax status**: **W-9**, plus the full W-8 family: **W-8BEN** (foreign individuals), **W-8BEN-E** (foreign entities), **W-8IMY** (foreign intermediaries), **W-8ECI** (effectively connected income), **W-8EXP** (foreign governments and organizations). **8802** runs the other direction, certifying U.S. residency to a foreign withholding agent.
- **IRS withholding**: **W-4** (employees), **W-4P** (pensions and annuities), **W-4R** (nonperiodic distributions).
- **IRS authorizations and applications**: **4506-C** (IVES transcript request), **8821** (tax information authorization), **2848** (power of attorney), **8879** (e-file signature authorization), **SS-4** (EIN application), **W-7** (ITIN application).
- **Employment, benefits, and payments**: **USCIS I-9** (employment eligibility verification), **DOL WH-380-E** (FMLA medical certification), **VA 21-4142** (authorization to release medical records to the VA), **SF 1199A** (direct deposit sign-up).

Every catalog version records where its PDF came from. `listForms` returns `sourceUrl`, the publisher's own file, and `sourceSha256`, the hash of the exact bytes Korala ships, so you can download the form from the government and confirm the two match before you send anything to a signer. The dashboard links the source on each card and shows the checksum when you add a form. Korala cannot publish a form without both, whether it was seeded or uploaded by hand, so there is no catalog entry you have to take on trust.

  Prefer the dashboard? Open **Templates → Standard forms**, pick a form, and
  click **Use this form**. The confirmation shows the source PDF and its
  checksum; confirm it and Korala copies the form into your organization and
  opens the new template, ready to generate and send. Same result as the API
  calls below.

## Browse the catalog

    ```typescript
    const forms = await korala.catalog.listForms();
    // [
    //   { id, slug: 'irs-w9', title: 'IRS Form W-9 …',
    //     jurisdiction: 'IRS', publishedRevision: 'Rev. March 2024',
    //     publishedVersionId: 'ver_…',
    //     sourceUrl: 'https://www.irs.gov/pub/irs-pdf/fw9.pdf',
    //     sourceSha256: '…' },
    //   …
    // ]
    ```
    ```bash
    api_request "GET" "/api/v1/catalog/forms"
    ```

## See a form's fields before you clone it

`getFormFields` returns the signer roles and fields a clone will have, so you can map your own data to a form while you are still deciding whether to use it. It writes nothing to your organization. Working out which of twenty forms fits should not leave twenty templates behind for your teammates to scroll past.

Each field gives the `canonicalName` you set values against, the role that fills it, and any constraint it enforces. Check `validationPattern` in your own system so you catch bad data before a signer is stuck on a form that will not accept it.

    ```typescript
    const { signerRoles, fields } = await korala.catalog.getFormFields(
      form.publishedVersionId,
    );
    // signerRoles: ['Taxpayer']
    // fields: [
    //   { canonicalName: 'legal_name', label: 'Name of entity/individual',
    //     signerRole: 'Taxpayer', fieldType: 'text', pageNumber: 1,
    //     required: true },
    //   { canonicalName: 'ssn_area', label: 'SSN area number',
    //     signerRole: 'Taxpayer', fieldType: 'text', pageNumber: 1,
    //     required: false, groupKey: 'tin', groupRequired: true,
    //     maxLength: 3, validationPattern: '^\\d{3}$',
    //     validationMessage: 'Enter 3 digits' },
    //   …
    // ]

    // Fields sharing a groupKey answer one question together. The W-9's SSN
    // and EIN cells are one `tin` group, so fill one set or the other.
    const tin = fields.filter((f) => f.groupKey === 'tin');
    ```
    ```bash
    api_request "GET" "/api/v1/catalog/forms/$VERSION_ID/fields"
    ```

You fill a cloned template by canonical name, never by the widget name buried in the PDF, so the response leaves out positions and AcroForm names. If you are authoring your own fillable PDF and need those, see [Fillable PDFs](https://docs.korala.ai/guides/fillable-pdfs).

## Clone a form into a template

One call copies Korala's curated PDF into your organization and creates a template with the form's mapped fields and signer roles. The result is an ordinary template; everything in [Templates](https://docs.korala.ai/guides/templates) and [Fillable PDFs](https://docs.korala.ai/guides/fillable-pdfs) applies unchanged.

    ```typescript
    const template = await korala.catalog.createTemplate(form.publishedVersionId, {
      name: 'W-9 for Acme investors',
    });

    // Generate a per-investor document, binding data by canonical name.
    const roles = await korala.templates.getSignerRoles(template.id);
    const taxpayer = roles.find((r) => r.name === 'Taxpayer');

    const doc = await korala.templates.createDocument(template.id, {
      name: 'W-9 — Jane Q. Taxpayer',
      signers: { [taxpayer.id]: { email: 'jane@example.com', name: 'Jane Q. Taxpayer' } },
      variables: {
        legal_name: 'Jane Q. Taxpayer',
        classification_individual: 'checked',
        ssn_area: '123', ssn_group: '45', ssn_serial: '6789',
      },
    });
    ```
    ```bash
    api_request "POST" "/api/v1/catalog/forms/${VERSION_ID}/create-template" \
      '{ "name": "W-9 for Acme investors" }'
    ```

The cloned template already carries the rules Korala curated for the form:

- **Canonical merge names**: bind `legal_name`, `ssn_area`, `address_street` instead of `topmostSubform[0].Page1[0].f1_01[0]`.
- **Choose-one classification**: the seven federal-tax-classification boxes are one required group, so the signer must pick exactly one.
- **TIN validation**: the SSN/EIN comb fields carry length limits and digit patterns, and are grouped so the signer must provide one.
- **Signature and date** on the Sign Here line.

Prefills you pass as `variables` are editable by default, so the signer can correct your data before signing.

## W-8BEN

The W-8BEN clones the same way. Pick the `irs-w8ben` form from `listForms`, clone it, and bind data by canonical name. Its role is `Beneficial Owner`, and the map covers Part I identification, the optional Part II treaty claim, and Part III certification:

```typescript
const doc = await korala.templates.createDocument(template.id, {
  name: 'W-8BEN — Marie-Claire Dubois',
  signers: { [owner.id]: { email: 'marie@example.com', name: 'Marie-Claire Dubois' } },
  variables: {
    beneficial_owner_name: 'Marie-Claire Dubois',
    country_of_citizenship: 'France',
    residence_address: '12 Rue de la Paix',
    residence_city_state_postal: 'Paris 75002',
    residence_country: 'France',
    us_taxpayer_id: '123-45-6789',   // validated as a 9-digit SSN/ITIN
    date_of_birth: '04-15-1985',     // validated as MM-DD-YYYY
  },
});
```

Korala stamps the signature as an overlay and flattens the form's embedded signature widget at completion; the adjacent date fills through the form. See [Fillable PDFs](https://docs.korala.ai/guides/fillable-pdfs) for how signing and flattening work.

## W-8BEN-E (entities)

The W-8BEN-E is the entity form (`irs-w8bene`, role `Entity`). Its catalog map covers the blocks every entity completes: **Part I identification** and the **Part XXX certification**. Part I includes the two choose-one status groups:

- **Chapter 3 status** (entity type): bind exactly one of `chapter3_corporation`, `chapter3_partnership`, `chapter3_simple_trust`, … The 13 boxes are one required group.
- **Chapter 4 status** (FATCA): bind exactly one of the 32 statuses, e.g. `chapter4_active_nffe`, `chapter4_passive_nffe`, `chapter4_participating_ffi`, `chapter4_nonreporting_iga_ffi`.

```typescript
const doc = await korala.templates.createDocument(template.id, {
  name: 'W-8BEN-E — Acme Global Holdings',
  signers: { [entity.id]: { email: 'ap@acme.ie', name: 'Siobhan Murphy' } },
  variables: {
    entity_name: 'Acme Global Holdings Ltd',
    country_of_incorporation: 'Ireland',
    chapter3_corporation: 'checked',   // one Chapter 3 box
    chapter4_active_nffe: 'checked',    // one Chapter 4 box
    residence_address: '1 Docklands Ave',
    residence_city_state_postal: 'Dublin D01',
    residence_country: 'Ireland',
    us_taxpayer_id: '12-3456789',       // validated as a 9-digit EIN
  },
});
```

The conditional per-status parts (II–XXVIII) and the Part XXIX substantial-U.S.-owners table are not mapped: a filer completes Part I, the single Part their FATCA status requires, and Part XXX. If you need a specific conditional Part mapped, ask and we'll add it.

## W-8IMY (intermediaries)

The W-8IMY (`irs-w8imy`, role `Intermediary`) is for foreign intermediaries and flow-through entities. Same shape as the W-8BEN-E: Part I identification plus the Part XXIX certification. Its Chapter 3 status names intermediary roles (`chapter3_qi`, `chapter3_nonqualified_intermediary`, `chapter3_withholding_foreign_partnership`, …), and line 8 adds a TIN-type choose-one (`tin_type_qi_ein`, `tin_type_wp_ein`, `tin_type_wt_ein`, `tin_type_ein`) alongside the EIN, GIIN, and foreign-TIN fields.

```typescript
const doc = await korala.templates.createDocument(template.id, {
  name: 'W-8IMY — Global Custody Nominees',
  signers: { [intermediary.id]: { email: 'ops@custody.lu', name: 'Jean Weber' } },
  variables: {
    entity_name: 'Global Custody Nominees Ltd',
    country_of_incorporation: 'Luxembourg',
    chapter3_qi: 'checked',           // one Chapter 3 box
    chapter4_active_nffe: 'checked',  // one Chapter 4 box
    us_taxpayer_id: '98-7654321',     // validated as a 9-digit EIN
    tin_type_qi_ein: 'checked',       // which EIN type
  },
});
```

As with the W-8BEN-E, the conditional per-status parts (III–XXVIII) are not mapped. The W-8IMY certification has no capacity-to-sign checkbox, so the Part XXIX block is signature, print name, and date.

## W-8ECI and W-8EXP

The remaining W-8s follow the family conventions. The **W-8ECI** (`irs-w8eci`, role `Beneficial Owner`) certifies effectively connected income: line 4's entity type is a choose-one group (`entity_type`), line 7's TIN accepts an SSN, ITIN, or EIN, and the U.S. business address and first income line are required because the form's own instructions make them conditions of validity. The **W-8EXP** (`irs-w8exp`, role `Entity`) covers foreign governments, international organizations, foreign central banks, and foreign tax-exempt organizations. Its entity-type and Chapter 4 status groups are required; the conditional Part II and III certifications are mapped and optional. Both forms require the capacity-to-sign checkbox, which their instructions also treat as a validity condition.

## W-4 (employee withholding)

The W-4 (`irs-w4`, role `Employee`) covers Steps 1–5 of the 2026 certificate: personal information with SSN format validation, the required `filing_status` choose-one group, the Step 2(c) two-jobs box, Step 3 credit amounts, Step 4 adjustments, and the exemption box. Korala leaves the "Employers Only" block and the worksheet pages unmapped. The worksheets stay with the employee rather than going to the employer, so the template collects what the employee certifies and nothing else.

## 4506-C (IVES transcript request)

The 4506-C (`irs-4506c`, role `Taxpayer`) is the consent lenders use to obtain tax transcripts through IVES. The map covers the taxpayer's side: names, TINs, address, transcript selection (`transcript_type` choose-one), years requested, and the required attestation checkbox. Line 5 belongs to the requesting lender, so it stays unmapped like the W-9's requester box. Spouse name and TIN are optional so you can identify joint filers, but the spouse signature line stays unmapped so a single filer is never blocked by a signature nobody will provide.

## Authorizations and applications (8821, 2848, SS-4, W-7)

The **8821** (`irs-8821`, role `Taxpayer`) authorizes a designee to receive confidential tax information. Taxpayer identity is required; both designee blocks are optional text you can pre-fill; the signature stamps as an overlay and the date fills through the form.

The **2848** (`irs-2848`) carries two roles: `Taxpayer` signs the Part I power of attorney, then `Representative` signs the Part II declaration. Representative blocks two through four stay unmapped, so add those signers by hand when a matter needs them.

The **SS-4** (`irs-ss4`, role `Applicant`) applies for an EIN, with required entity-type and reason-for-applying groups. The EIN box at the top belongs to the IRS, and the Third Party Designee block to whoever files on your behalf, so neither is mapped. The **W-7** (`irs-w7`, role `Applicant`) applies for an ITIN. Application-type, reason, and gender are required choose-one groups, and its date boxes take digits only because the form prints the slashes for you. The Acceptance Agent block stays unmapped.

## 8802 (U.S. residency certification)

Where the W-8s tell a U.S. withholding agent that your counterparty is foreign, the **8802** (`irs-8802`, role `Applicant`) does the reverse: it applies for the Form 6166 letter that proves your U.S. residency to a foreign tax authority, so a treaty rate applies to income you earn abroad.

At 190 fields it is the catalog's largest map, and its required set is the smallest: applicant name, TIN, signature, and date. The form branches, and which lines apply depends on answers given earlier, so marking more fields required would block filers who correctly skip a branch. Line 4's `applicant_type` group is the one required choice. The line 11 country grid is mapped as optional cells named after the form's own country codes, and the third-party appointee block belongs to whoever files for you, so it stays unmapped.

## Multi-signer forms

Sixteen catalog forms carry one signer role. Four need two, and cloning creates both with sequential signing order:

| Form | First signer | Second signer |
|------|--------------|---------------|
| 2848 | `Taxpayer` (Part I power of attorney) | `Representative` (Part II declaration) |
| 8879 | `Taxpayer` (Part II PIN authorization) | `ERO` (Part III) |
| I-9 | `Employee` (Section 1) | `Employer` (Section 2) |
| WH-380-E | `Employer` (Section I) | `Health Care Provider` (Sections II–IV) |

Provide a signer for each role when you generate the document. Korala invites the second signer once the first finishes, over the ordinary [sequential signing](https://docs.korala.ai/guides/templates) flow.

## Withholding and retirement (W-4P, W-4R)

The **W-4P** (`irs-w4p`, role `Payee`) mirrors the W-4's structure for periodic pension and annuity payments, with a required `filing_status` group and a "no withholding" election the W-4 lacks. The **W-4R** (`irs-w4r`, role `Payee`) is the short nonperiodic-distribution certificate: identity plus one whole-number withholding rate between 0 and 100.

## Employment and payments (I-9, SF 1199A)

The **I-9** (`uscis-i9`, Edition 01/20/25) verifies employment eligibility. The `Employee` completes Section 1: identity, address, and a required `citizenship_status` choose-one group. SSN stays optional, since the form demands it from E-Verify employers and no one else.

Section 2 belongs to the `Employer`, and there only the signature and date are required. A hire presents either one List A document or one from List B and one from List C, and a per-field required flag cannot express that choice; the document columns also tend to arrive pre-filled from your onboarding system. Supplement A (preparer or translator) and Supplement B (reverification and rehire) stay unmapped, so complete those by hand when a hire needs them.

The **SF 1199A** (`gsa-sf1199a`, role `Payee`) sets up direct deposit of federal payments, with required account-type and payment-type groups plus routing and account validation. The form prints three copies for the agency, the financial institution, and the payee. Each copy carries its own fields rather than sharing one set, so Korala maps the first and leaves the rest. Section 3's certification and the joint-account-holder lines belong to the bank and the co-holder, so they stay unmapped too.

## Benefits and medical authorizations (WH-380-E, VA 21-4142)

The **WH-380-E** (`dol-wh380e`) certifies an employee's FMLA leave. Its two roles are asymmetric: the `Employer` fills Section I, which carries no signature line, and the `Health Care Provider` completes the medical sections and signs. This is the one catalog form where the first role never signs.

Its inline either/or toggles ("has been / is expected to be", "day / week / month") each live in a single PDF form field holding several boxes. Filling such a field through the form can only ever tick the first box, so Korala stamps those choices as overlays and marks the box the provider actually chose.

The **VA 21-4142** (`va-21-4142`, role `Veteran`) authorizes private providers to release treatment records to the VA for a benefits claim. The published PDF bundles the companion **21-4142a** release, and its five provider blocks are mapped as optional rows. The identity block repeated on that release's first page is not.

## Revisions

Each catalog form has a published revision (e.g. the W-9's `Rev. March 2024`). When the IRS publishes a new revision, Korala adds a new version and it becomes the one `listForms` returns. Templates you already cloned keep working against the revision you cloned; re-clone to move to the new one.

Cloning is org-scoped: the copied PDF and template live in your organization, and Korala never edits your documents. The catalog is read-only source material.