Mappings & field aliasing

PDFs rarely come with field names you'd want in your application code. Open an IRS W-4 in a text editor and you'll find names like topmostSubform[0].Page1[0].f1_02[0]. A mapping is the bridge between that raw name and a key you can read at 11pm on a Tuesday: fullName.

Mappings live alongside templates. One template can have many mappings — usually one per consumer (your HR app, your contracts service, your customer-facing portal) so each consumer gets to use its own vocabulary without negotiating with the others.

The raw → alias pattern

Every mapping holds a field_mappings dictionary whose keys are raw PDF field names and values are your aliases:

When you submit a generation request, you send your aliases in data. SimplyFill walks the mapping, finds the raw PDF field for each alias, and writes your value there. Your code sends data.fullName = "Ada Lovelace"; the W-4 receives topmostSubform[0].Page1[0].f1_02[0] = "Ada Lovelace".

Creating a mapping

curl -X POST https://api.simplyfill.app/v1/mappings \
  -H "Authorization: Bearer $SIMPLYFILL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HR app — onboarding",
    "template_id": 123,
    "field_mappings": {
      "topmostSubform[0].Page1[0].f1_02[0]": "fullName",
      "topmostSubform[0].Page1[0].f1_06[0]": "ssn",
      "topmostSubform[0].Page1[0].c1_1[0]":  "filingStatusSingle"
    }
  }'

const mapping = await client.mappings.create({
  name: 'HR app — onboarding',
  templateId: 123,
  fieldMappings: {
    'topmostSubform[0].Page1[0].f1_02[0]': 'fullName',
    'topmostSubform[0].Page1[0].f1_06[0]': 'ssn',
    'topmostSubform[0].Page1[0].c1_1[0]':  'filingStatusSingle'
  }
})

mapping = client.mappings.create(
    name="HR app — onboarding",
    template_id=123,
    field_mappings={
        "topmostSubform[0].Page1[0].f1_02[0]": "fullName",
        "topmostSubform[0].Page1[0].f1_06[0]": "ssn",
        "topmostSubform[0].Page1[0].c1_1[0]":  "filingStatusSingle",
    },
)

The response includes a mapping.id you'll pass to every subsequent generation call. Most teams store this alongside their template ID — they tend to evolve together.

Simple and enhanced value forms

The simplest mapping value is a string alias (above). For more control, swap any value for an object that adds a transformation expression or conditional logic:

{
  "name": "HR app — onboarding (with transforms)",
  "template_id": 123,
  "field_mappings": {
    "f1_02[0]": {
      "source": "fullName",
      "transform": "concat(first_name, ' ', last_name)"
    },
    "f1_06[0]": {
      "source": "ssn",
      "condition": { "if": "ssn_redacted", "then": "***-**-****", "else": "ssn" }
    }
  },
  "transformations": {}
}

• source — the alias your data payload uses
• transform — a small expression evaluated against data before writing (see Custom field transformations)
• condition — if/then/else selector evaluated against data

The simple "alias" form is sugar for { "source": "alias" }.

Validating a mapping before going live

Mappings are easy to typo. Before pointing production at a new mapping, validate it against the template:

curl -X POST https://api.simplyfill.app/v1/mappings/456/validate \
  -H "Authorization: Bearer $SIMPLYFILL_API_KEY"

The validator confirms every key in field_mappings resolves on the current template version. Mismatches return a list of warnings (unknown field, missing alias, etc.) — fix them before you ship.

One template, many mappings

A common pattern: the same W-4 template lives in your HR app and your contractor portal. The HR app sends fullName and ssn; the contractor portal already uses legal_name and taxpayer_id. Rather than forcing one team to match the other's vocabulary, give each consumer its own mapping that aliases the same raw PDF fields differently. The W-4 doesn't care.

What's next

• Templates — how field detection produces the raw names you alias
• Custom field transformations — derived fields like uppercase, concatenation, conditional defaults
• Create mapping (API) — full request and response reference