PDF templates

Carbone can use an existing fillable PDF, an AcroForm such as an official government form, an HR document, or a form built in Adobe Acrobat, directly as a template. Upload the PDF as-is: Carbone reads its form fields and fills them with your JSON data. The template stays a PDF throughout, there is no intermediate conversion step.

This is a low-level feature to update existing PDF forms. If you want to design a new form from scratch, with clickable checkboxes and editable text fields, see Forms: that page covers the ODT-based workflow, which is the fastest way to build a form and export it to PDF. This page is about reusing a PDF form that already exists.

Prerequisites

• A PDF that already contains form fields (text fields, checkboxes, radio buttons), created or edited in a tool such as Adobe Acrobat, PDFescape, or LibreOffice Draw.
• Carbone v5.0.0 or later, Enterprise Edition (Cloud or On-Premise).

Three ways to fill a PDF form

1. Carbone tags directly inside a form field

The simplest method: open the field's default value/content in your PDF editor and type a Carbone tag directly, for example {d.user.firstName}. Carbone replaces it with the corresponding value from your dataset. Loops are supported inside a text field, so a single field can repeat content for each item of an array.

2. Annotation formatters: fill, check, uncheck

Add a text annotation positioned directly above the field you want to update, and insert a Carbone tag using one of the following formatters. Carbone detects the field behind the annotation, removes the annotation, and updates the field:

Formatter	Description
:fill	Fills the text field behind the tag
:check	Checks the checkbox or radio button behind the tag
:uncheck	Unchecks the checkbox behind the tag

{d.myText:fill}                        // fills the text field behind the tag
{d.myCondition:ifEQ(true):check}       // checks the checkbox/radio button behind the tag
{d.myCondition:ifEQ(false):uncheck}    // unchecks the checkbox behind the tag

Note: The annotation must overlap the target field. If Carbone cannot find a field below the annotation, it returns an error, move the annotation so it fully overlaps the field.

3. Target a field by name: fillField, checkField

Place a Carbone tag anywhere in the PDF, it does not need to sit on top of the field, and target the field directly by its name:

Formatter	Description
:fillField('fieldName')	Fills the text field named fieldName. Any non-empty value also checks a checkbox.
:checkField('fieldName')	Checks the checkbox or radio option named fieldName if the condition is true.

{d.text:fillField('fieldName')}
{d.confirm:ifEQ(true):checkField('fieldName')}

To select one option in a group of radio buttons, resolve the option name with a condition and pass it to :fillField():

Data

{ "genre": "boy" }

Template tag

{d.genre:ifEQ('boy'):show(male):ifEQ('girl'):show(female):fillField('genderGroup')}

If the resolved option (male or female above) does not exist in the radio group, Carbone returns an error.

Known limitations

• In Carbone Studio, the embedded PDF viewer cannot display filled forms. Uncheck "Use embedded PDF viewer" in the preview panel to see the actual result.
• Buttons and other unsupported field types are silently ignored rather than raising an error.
• The native macOS Preview app can break PDF forms that contain radio buttons. Test the generated document with Adobe Acrobat Reader or another standards-compliant viewer.

Generate a document from a PDF template

To fill a PDF form using the Carbone API, follow this workflow:

1. Prepare two files: your fillable PDF template (with Carbone tags placed as described above) and a JSON dataset.
2. Send a POST /render/template request to the Carbone API. Since the template is already a PDF and the output should stay a PDF, omit convertTo, Carbone only fills the tags and returns the same file, unconverted:

curl --location --request POST 'https://api.carbone.io/render/template?download=true' \
  --header 'carbone-version: 5' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer API_TOKEN' \
  --data-raw "{
    "data": {},
    "template": "$(base64 -i form.pdf)"
  }" \
  --output result.pdf

💡 Linux users: replace base64 -i form.pdf with base64 -w 0 form.pdf

Key Parameters

Parameter	Description
template	Your fillable PDF, encoded as a Base64 string.
data	JSON dataset used to fill the form fields.
?download=true	Query parameter to download the document as a stream.
Authorization	Header required for the Carbone Cloud API. Get your API key here.

For more details, refer to the Carbone API Documentation.

Example

The PDF Forms example shows the general field techniques (borderless text boxes, checkbox styling) covered on this page, though its template is authored in ODT and exported to PDF rather than starting from a native fillable PDF. See also PDF Forms with a background image for adding a background image behind form fields.