API referenceTemplates
Upload template
Upload a fillable PDF, extract its fields, and create a new template.
Upload template
Uploads a fillable PDF and creates a new template. SimplyFill parses the PDF's AcroForm layer and returns the detected field manifest in the response.
Signature
POST /api/v1/templates/uploadContent-Type: multipart/form-data
Permissions
API key scope: write or higher.
Subject to the per-tier template cap — see Quotas. Exceeding the cap returns 403 Forbidden.
Form fields
| Name | Type | Required | Description |
|---|---|---|---|
file | file (PDF) | yes | Fillable PDF. Must end with .pdf. Max 25 MB. |
name | string | no | Display name. Defaults to the filename without extension. |
description | string | no | Free-form description. Max 2,000 characters. |
organization_id | integer | no | Organization to attach the template to. Omit for personal. |
Example
curl -X POST https://api.simplyfill.app/v1/templates/upload \
-H "Authorization: Bearer $SIMPLYFILL_API_KEY" \
-F "file=@invoice.pdf" \
-F "name=Invoice Template"import fs from 'node:fs'
const template = await client.templates.upload({
file: fs.createReadStream('invoice.pdf'),
name: 'Invoice Template'
})
console.log(template.id, template.field_count)template = client.templates.upload(
file=open("invoice.pdf", "rb"),
name="Invoice Template",
)
print(template.id, template.field_count)Response
201 Created with the new template:
{
"id": 123,
"name": "Invoice Template",
"description": null,
"filename": "invoice.pdf",
"storage_path": "templates/abc.../invoice.pdf",
"field_metadata": {
"invoice_number": { "type": "text", "required": true, "max_length": 64 },
"customer_name": { "type": "text" },
"total_amount": { "type": "text" }
},
"field_count": 3,
"current_version": 1,
"draft_status": "draft",
"default_environment": "development",
"created_at": "2026-05-17T14:11:09Z"
}Errors
| Status | error code | Cause |
|---|---|---|
400 | invalid_file_type | Filename does not end with .pdf. |
400 | file_too_large | Upload exceeds 25 MB. |
403 | feature_limit_reached | Account has hit the per-tier template cap. |
XFA forms are flattened on upload
PDFs containing dynamic XFA layouts are converted to a static AcroForm representation. Any XFA scripting is discarded. Re-author from a non-XFA source if you depend on dynamic behaviour. See Templates concept.