Standard Forms Library

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.

Browse the catalog

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: '…' },
//   …
// ]

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.

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');

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.

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 and Fillable PDFs applies unchanged.

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: '[email protected]', name: 'Jane Q. Taxpayer' } },
  variables: {
    legal_name: 'Jane Q. Taxpayer',
    classification_individual: 'checked',
    ssn_area: '123', ssn_group: '45', ssn_serial: '6789',
  },
});

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:

const doc = await korala.templates.createDocument(template.id, {
  name: 'W-8BEN — Marie-Claire Dubois',
  signers: { [owner.id]: { email: '[email protected]', 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 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.

const doc = await korala.templates.createDocument(template.id, {
  name: 'W-8BEN-E — Acme Global Holdings',
  signers: { [entity.id]: { email: '[email protected]', 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.

const doc = await korala.templates.createDocument(template.id, {
  name: 'W-8IMY — Global Custody Nominees',
  signers: { [intermediary.id]: { email: '[email protected]', 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:

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