---
source: https://carbone.io/examples/pdf-form-template/
title: "Fill PDF Form API: Fill AcroForms from JSON | Carbone"
description: "Fill existing PDF forms from JSON with the Carbone API. Upload the fillable PDF (AcroForm) as the template and get it back with fields and checkboxes filled."
generated_at: "2026-11-17"
---

# Fill an existing PDF form

Visa applications or tax returns, with every field completed

[![Fill an existing PDF form: PDF generated from a PDF template and JSON data](/examples/pdf-form-template/thumb-result.webp)](/examples/pdf-form-template/result.pdf "Download the generated document")

[Download template](/examples/pdf-form-template/template.pdf)

[Sample data](/examples/pdf-form-template/data.json)

[Download the generated PDF](/examples/pdf-form-template/result.pdf)

- **Template:** PDF
- **Export as:** PDF
- **Carbone:** 5.0+

Features

-   [PDF form](/documentation/design/advanced-features/forms.md)
-   [Checkbox](/documentation/design/advanced-features/forms.md)
-   [Condition](/documentation/design/conditions/overview.md)

## Fill PDF forms from your software

Government, insurance and HR forms, such as visa applications or tax returns, are often published as fillable PDFs (AcroForms) whose layout must not change. Your application sends the data to the Carbone API as JSON, with the PDF as the template, and gets back the same PDF with its text fields filled and its checkboxes ticked, still fillable. Here, the harmonised Schengen visa application form is used as-is as a [PDF template](/documentation/design/template-formats/pdf.md).

| Your form | Example to follow |
| --- | --- |
| A PDF with form fields (AcroForm) | This page |
| A flat PDF, without form fields | [Fill a flat PDF form](/examples/pdf-forms-bg/index.md) |
| A new form that you design | [Prefilled PDF form](/documentation/design/advanced-features/forms.md#prefilled-form-example) |

In this example, you will:

-   Use an existing fillable PDF as a template
-   Fill text fields with Carbone tags
-   Tick checkboxes with comments and conditions

## How to fill an existing PDF form programmatically

Follow these steps to fill an existing PDF form with Carbone:

### 1\. Open the Form in a PDF Editor

Open the PDF form in Adobe Acrobat, or in another editor that supports form fields. There is no layout to create: the form already contains its text fields and checkboxes.

### 2\. Type Tags in the Text Fields

[Insert a Carbone tag](/documentation/design/template-formats/pdf.md#write-tags-in-the-fields) in each text field: open the field **Properties**, and in the **Options** tab, type the tag in **Default Value**, for example `{d.lastName}`.

A field can combine several tags, for example `{d.guardian.surname} {d.guardian.firstName}`.

The "Other (specify)" fields are filled only when the matching option is selected, with the [:ifEQ](/documentation/design/conditions/overview.md#ifeq-value) formatter:

```text
{d.civilStatus:ifEQ(other):show(.otherCivilStatus):elseShow('')}
```

### 3\. Tick the Checkboxes with Comments

Add a **Sticky Note** comment on top of each checkbox, and type a Carbone tag ending with the [:check](/documentation/design/template-formats/pdf.md#place-tags-over-the-fields) formatter. The box is ticked when the condition is true, and Carbone removes the comment from the result:

-   For a single value: `{d.sex:ifEQ(M):check}`
-   For a value in a list, with the [:ifIN](/documentation/design/conditions/overview.md#ifin-value) formatter: `{d.appSupportMeans:ifIN('cash'):check}` ticks the box when `appSupportMeans` contains `cash`
-   For several values, with the [:or](/documentation/design/conditions/overview.md#or-value) formatter: `{d.journeyPurpose:ifIN(family):or:ifIN(friend):check}`

_Tip: the comment must overlap the checkbox, otherwise Carbone returns an error. To place the tag anywhere in the PDF, target the field by its name with [:checkField](/documentation/design/template-formats/pdf.md#target-fields-by-name)._

> ℹ️ **Note:** PDF templates require Carbone v5. To see the filled fields in Studio, turn off the embedded PDF viewer in **Preview options**.

Save the PDF template, connect it to your JSON data, and let Carbone fill your PDF forms automatically.

## Related Examples

Check out these similar templates to learn more:

- [Fill a flat PDF form](/examples/pdf-forms-bg/index.md): ODT template to PDF.
- [Vehicle condition report](/examples/check-out/index.md): DOCX template to PDF.

## Related topics

- [Daily restaurant menu](/examples/menu/index.md)
- [Editor.js to PDF and Word](/examples/editorjs/index.md)
- [Illustrated recipe book](/examples/recipe-book/index.md)
