Your first filled PDF

This walkthrough covers the complete workflow: uploading a template, mapping fields, and generating a filled PDF with data already in your application.

Upload your PDF template

Start with any fillable PDF. SimplyFill extracts form fields automatically:

curl -X POST https://api.simplyfill.app/v1/templates \
  -H "Authorization: Bearer $SIMPLYFILL_API_KEY" \
  -F "file=@invoice.pdf" \
  -F "name=Invoice Template"

const template = await client.templates.upload({
  file: fs.createReadStream('invoice.pdf'),
  name: 'Invoice Template'
})

console.log(`Template ID: ${template.id}`)

template = client.templates.upload(
    file=open('invoice.pdf', 'rb'),
    name="Invoice Template"
)

print(f"Template ID: {template.id}")

The response includes your template.id and extracted field names.

Explore extracted fields

Check what fields the PDF contains:

curl https://api.simplyfill.app/v1/templates/$TEMPLATE_ID/fields \
  -H "Authorization: Bearer $SIMPLYFILL_API_KEY"

const { fields } = await client.templates.get(template.id)
console.log('PDF fields:', fields.map(f => f.name))

template = client.templates.get(template.id)
print('PDF fields:', [f.name for f in template.fields])

These field names come directly from the PDF. Plan how they map to your data.

Create field mappings (optional)

Mappings let you use your domain terminology while preserving the PDF's exact field names. This captures the organics in your existing data structure:

curl -X POST https://api.simplyfill.app/v1/mappings \
  -H "Authorization: Bearer $SIMPLYFILL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "$TEMPLATE_ID",
    "mappings": [
      {"pdf_field": "invoice_number", "alias": "invoiceId"},
      {"pdf_field": "customer_name", "alias": "clientName"},
      {"pdf_field": "total_amount", "alias": "amount"}
    ]
  }'

await client.mappings.create({
  template: template.id,
  mappings: [
    { pdfField: 'invoice_number', alias: 'invoiceId' },
    { pdfField: 'customer_name', alias: 'clientName' },
    { pdfField: 'total_amount', alias: 'amount' }
  ]
})

client.mappings.create(
    template=template.id,
    mappings=[
        {"pdf_field": "invoice_number", "alias": "invoiceId"},
        {"pdf_field": "customer_name", "alias": "clientName"},
        {"pdf_field": "total_amount", "alias": "amount"}
    ]
)

With mappings, send invoiceId instead of invoice_number — your data, your keys.

Generate with your data

Now fill the PDF with data already in your application:

curl -X POST https://api.simplyfill.app/v1/generate \
  -H "Authorization: Bearer $SIMPLYFILL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "$TEMPLATE_ID",
    "data": {
      "invoiceId": "INV-2024-001",
      "clientName": "Acme Corp",
      "amount": "$1,250.00"
    }
  }'

const result = await client.generate({
  template: template.id,
  data: {
    invoiceId: 'INV-2024-001',
    clientName: 'Acme Corp',
    amount: '$1,250.00'
  }
})

// result.url is a signed URL to download the PDF

result = client.generate(
    template=template.id,
    data={
        "invoiceId": "INV-2024-001",
        "clientName": "Acme Corp",
        "amount": "$1,250.00"
    }
)

# result.url is a signed URL to download the PDF

Download the PDF from result.url. The document is ready to send.

Next steps

Quickstart — Faster setup if you skipped it
Bulk generation — Fill hundreds at once
Template versioning — Manage multiple PDF versions

Your first filled PDF

Your first filled PDF

Upload your PDF template

Explore extracted fields

Create field mappings (optional)

Generate with your data

Next steps

On this page