Templates
How SimplyFill stores, versions, and extracts fields from your fillable PDFs.
Templates
A template is a fillable PDF you've uploaded to SimplyFill. Every generation request points at a template, and SimplyFill takes care of locating fields, applying your data, and returning a freshly rendered PDF. Templates are the foundation of every other concept — mappings target a template, environments promote a template version, generations consume a template's fields.
What you upload
Templates start as a regular PDF. The only requirement is that it contains an AcroForm layer — the embedded form-field structure that Adobe defined in PDF 1.2 and that every modern PDF tool emits when you "Create a fillable form." SimplyFill walks the AcroForm tree on upload, captures the name and type of every field, and stores both the bytes and the parsed field manifest in your account.
You don't pre-declare schemas. You don't write XSDs. Upload the PDF, get a template.id and a list of detected fields back in the same response.
Field detection
SimplyFill's parser handles every standard AcroForm field type:
| Field type | What it captures |
|---|---|
text | Single- and multi-line text inputs |
checkbox | On/off toggles, written as true or false |
radio | Mutually exclusive choice groups |
choice (combobox / listbox) | Dropdowns and pick lists |
signature | Signature widgets — accepts a base64 image or signer name |
date | Date fields with the PDF's declared format string |
Each detected field carries its original PDF name (sometimes a tortured path like topmostSubform[0].Page1[0].f1_02[0]), its type, default value, max length, and whether the original PDF marked it required. You can list a template's fields any time:
curl https://api.simplyfill.app/v1/templates/$TEMPLATE_ID \
-H "Authorization: Bearer $SIMPLYFILL_API_KEY"The response includes the parsed field manifest under fields[]. Most teams alias those raw names into something readable using mappings before going to production.
XFA handling
PDFs that ship as pure XFA (XML Forms Architecture) — common with old government forms and some enterprise systems — are flattened on upload. SimplyFill converts the dynamic XFA layout into a static AcroForm representation and discards the XFA layer. The resulting template behaves identically to a native AcroForm PDF.
XFA limitations
Flattening is lossy. Dynamic XFA features — repeating subforms that grow at runtime, JavaScript-driven calculations, conditional sections — collapse to their initial state. If your source PDF relies on XFA scripting, regenerate it as a plain fillable PDF from the original authoring tool (Adobe Acrobat Pro, LibreOffice Draw, Foxit) before uploading.
Versioning
Templates are immutable once created, but they're not frozen. Every time you re-upload the same PDF (using the same template.id or by replacing the source file through the dashboard) SimplyFill creates a new template version. Versions are append-only — old versions stay around forever so historical generations remain reproducible.
Mappings pin to a specific version. If you upload v1 of w4.pdf, build a mapping that aliases f1_02[0] to fullName, then upload v2 with a renamed field, your existing mapping keeps working against v1 — and you decide explicitly when to promote it to v2. The promotion flow is covered in Environments and walked through end-to-end in Multi-environment promotion.
When a generation request omits a version, SimplyFill uses the latest version published to the request's environment (the API key determines which environment — see Environments).
File size and quota limits
| Limit | Value |
|---|---|
| Max upload size | 25 MB per PDF |
| Max page count | 200 pages |
| Max fields per template | 5,000 |
| Templates per account | Tier-dependent — see Quotas |
Uploads that exceed any of these are rejected with 400 Bad Request and an explanatory error body. PDFs that exceed your tier's template count return 403 Forbidden with an upgrade_required error code; the dashboard will surface an upgrade prompt automatically.
A typical lifecycle
- Upload. Drop the PDF onto
POST /api/v1/templates/upload. SimplyFill returns the template ID and the parsed field manifest. - Inspect. Hit
GET /api/v1/templates/{id}to confirm field names and types match what you expect. - Map. Create a mapping that aliases raw field names to your domain language.
- Test in dev. Generate a few PDFs against a development API key. Verify output visually.
- Promote. Move the version to staging, then production, via the dashboard or the promotion API.
- Iterate. When the source PDF changes, re-upload — SimplyFill creates v2 automatically. Map and promote on your schedule.
What's next
- Mappings — alias raw PDF field names to your domain language
- Environments — promote template versions through dev → staging → prod
- Upload template (API) — full request and response reference