Skip to main content
Version: 9.x

Attach files

Embeds files in a PDF: the source data, a spreadsheet, the XML of an e-invoice.

POST/forms/pdf/attach
Form data
filesfile[]required

The PDFs, and the files the options name.

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
filefilerequired

The uploaded file to embed.

namestring

The name the PDF lists it under.

Default: The file's name

mimeTypestring

The file's MIME type.

Default: From the name

relationshipstring

Source, Data, Alternative, Supplement or Unspecified. Makes the file a PDF/A-3 associated file.

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.

Attach a file​

curl \
  --request POST http://localhost:3000/forms/pdf/attach \
  --form files=@report.pdf \
  --form files=@invoice.xml \
  --form file=invoice.xml \
  -o report.pdf

The PDF lists the file under its name. name renames it, and mimeType overrides the type Gotenberg reads from the name. /forms/pdf/attachments lists the files a PDF holds.

Attach several​

One attach stage per file:

curl \
  --request POST http://localhost:3000/forms/pdf/pipe \
  --form files=@report.pdf \
  --form files=@invoice.xml \
  --form files=@logo.png \
  --form 'stages=[
    { "op": "attach", "file": "invoice.xml" },
    { "op": "attach", "file": "logo.png", "name": "brand.png" }
  ]' \
  -o report.pdf

Mark an associated file​

relationship makes the file a PDF/A-3 associated file, and says how it relates to the document: Source, Data, Alternative, Supplement or Unspecified.

curl \
  --request POST http://localhost:3000/forms/pdf/attach \
  --form files=@report.pdf \
  --form files=@invoice.xml \
  --form file=invoice.xml \
  --form relationship=Data \
  -o report.pdf

A Factur-X invoice needs more than its XML: the remediate stage with the Factur-X profile embeds it and makes the PDF conform.

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=@report.pdf \
  --form files=@invoice.xml \
  --form 'stages=[
    { "op": "attach", "file": "invoice.xml", "relationship": "Data" }
  ]' \
  -o report.pdf