Skip to main content
Version: 9.x

Fill a form

Fills the fields of a PDF form.

POST/forms/pdf/set-form
Form data
filesfile[]required

The PDFs.

archivesfile[]

ZIP files Gotenberg unpacks: each entry counts as a file uploaded under files.

downloadFromjson

URLs Gotenberg downloads first, as if you had uploaded the files. Each entry takes a url, and optionally extraHttpHeaders.

Options
fieldsobjectrequired

Values keyed by the fields' fully qualified names: a string, or an array of strings for a list that selects several. /forms/pdf/form lists the fields and the values each takes.

Response

The PDF, or a ZIP of the PDFs when you send several.

The route also takes the headers. An error answers a status and a message: see Errors.

Fill the fields​

/forms/pdf/form lists a form's fields, with the values each takes. This form has a checkbox agree, whose state is Yes, and a combo color, with the options Red and Green:

curl \
  --request POST http://localhost:3000/forms/pdf/set-form \
  --form files=@fields.pdf \
  --form 'fields={"agree":"Yes","color":"Green"}' \
  -o fields.pdf

fields keys each value by the field's name, as /forms/pdf/form lists them: name, or address.city for a field city inside a field address. A checkbox takes one of its states, a choice field one of its options. The fields stay editable. A field the PDF marks read-only takes its value too.

Select several items​

A list that selects several takes an array:

curl \
  --request POST http://localhost:3000/forms/pdf/set-form \
  --form files=@multi.pdf \
  --form 'fields={"tags":["b","c"]}' \
  -o multi.pdf

Values a field can't hold​

A value the field can't hold answers 400, and says what the field takes:

curl \
  --request POST http://localhost:3000/forms/pdf/set-form \
  --form files=@fields.pdf \
  --form 'fields={"color":"Blue"}'
Response
HTTP/1.1 400 Bad Request
Content-Type: text/plain; charset=UTF-8

Stage 'set-form' failed on 'fields.pdf': value the form field cannot hold: "Blue" for field "color": "Blue" is none of its options: Red, Green

A name the PDF doesn't have answers 400 too, with the names it has. Signature fields and push buttons take no value.

Fill a converted document​

LibreOffice exports a document's form fields as fields a reader can fill, unless exportFormFields is false. Add the set-form stage to the conversion to fill them in the same request.

In a list of stages​

The stage also runs in a list on /forms/pdf/pipe, and on the PDFs a Chromium or LibreOffice conversion makes, in its stages field:

curl \
  --request POST http://localhost:3000/forms/pdf/pipe \
  --form files=@form.pdf \
  --form 'stages=[
    { "op": "set-form", "fields": { "name": "Ada Lovelace" } }
  ]' \
  -o form.pdf

To lock the values into the page, flatten the form.