How to Add Attachments to PDF Files with cURL, Tutorial

Share this page

In this tutorial, we'll walk through how to add attachments to PDF files using cURL and the Add to PDF API Tool. The complete shell command stays visible, and each pdfRest-specific field is explained before you adapt the Add Attachments to PDF request to your own workflow.

Why Add Attachments to PDF Files with cURL?

PDF attachments allow one document to carry related source material without placing that material on a visible page. This is useful when people need the PDF presentation while another system needs the original data or supporting evidence.

Consider an invoicing workflow that produces a readable PDF and an XML record for automated accounting. A cURL step can embed the XML inside the invoice PDF so both representations move through approval, delivery, and storage as one package.

The request uploads the main PDF through file and the supporting document through file_to_attach. pdfRest returns a new PDF resource; it does not overwrite either uploaded input.

cURL Code Example

# By default, we use the US-based API service. This is the primary endpoint for global use.
API_URL="https://api.pdfrest.com"

# For GDPR compliance and enhanced performance for European users, you can switch to the EU-based service by uncommenting the URL below.
# For more information visit https://pdfrest.com/pricing#how-do-eu-gdpr-api-calls-work
# API_URL="https://eu-api.pdfrest.com"

curl -X POST "$API_URL/pdf-with-added-attachment" \
  -H "Accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -H "Api-Key: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -F "file=@/path/to/file" \
  -F "file_to_attach=@/path/to/file" \
  -F "output=example_out"

Source for Add Attachments to PDF: View the cURL sample on GitHub.

Breaking Down the Code

Choose the pdfRest service region

# By default, we use the US-based API service. This is the primary endpoint for global use.
API_URL="https://api.pdfrest.com"

# For GDPR compliance and enhanced performance for European users, you can switch to the EU-based service by uncommenting the URL below.
# For more information visit https://pdfrest.com/pricing#how-do-eu-gdpr-api-calls-work
# API_URL="https://eu-api.pdfrest.com"

The Add Attachments to PDF example routes to the US service through the active URL, while the commented hostname provides the EU option. Keep every Add Attachments to PDF input and generated resource ID in the same region.

Build the authenticated multipart request

curl -X POST "$API_URL/pdf-with-added-attachment" \
  -H "Accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -H "Api-Key: xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \

This POST targets the endpoint used by Add Attachments to PDF. For the Add Attachments to PDF request, Accept asks for JSON, Content-Type identifies the multipart payload, and Api-Key authenticates the call.

Upload the input file data

-F "file=@/path/to/file" \
  -F "file_to_attach=@/path/to/file" \

The two file fields have different roles, so preserving descriptive filenames helps recipients recognize the PDF and its embedded attachment.

Set the operation-specific fields

-F "output=example_out"

For Add Attachments to PDF, the output field supplies the requested base name for the generated resource. Any additional fields shown here control behavior specific to this operation.

Read the generated resource response

curl -X POST "$API_URL/pdf-with-added-attachment" \

A successful Add Attachments to PDF call returns JSON describing the generated resource, including its output ID and download information. Preserve the Add Attachments to PDF result needed by the next workflow step before the configured retention period expires.

Beyond the Tutorial

You now have a cURL request that combines a PDF and a supporting file into one portable result. The same pattern can package invoice XML, audit evidence, source documents, or other records that should remain connected to the visible PDF.

When you bring this into an application, verify attachment names and media types in the PDF viewers your users depend on. Save the generated file before its retention period expires, and delete temporary resources when the package no longer needs to remain available.

Continue exploring the Add Attachments to PDF workflow in API Lab. For the complete Add Attachments to PDF request contract, accepted values, defaults, and limitations, consult the Add to PDF API Tool documentation.

Note: The Add Attachments to PDF example above uploads a file with multipart form data. For source content already stored in pdfRest, the Add Attachments to PDF JSON payload example shows the resource-ID request shape.