Skip to main content

Merging PDFs


Use the pdf endpoint to easily merge PDF documents into a combined PDF document.


This tutorial uses the pdf endpoint to merge three pre-existing PDFs into a new combined PDF. We first call the pdf endpoint directly using cURL from the command-line. We then use the DynamicPDF client libraries to illustrate merging using C#, Java, Node.js, and PHP.

Required Resources#

To complete this tutorial, you must add the Merge PDFs sample to your samples folder in your cloud storage space using the Resource Manager. After adding the sample resources, you should see a samples/merge-pdfs-pdf-endpoint folder containing the resources for this tutorial.

SampleSample FolderResources
Merge PDFssamples/merge-pdfs-pdf-endpointDocumentA.pdf, DocumentB.pdf, DocumentC.pdf, instructions.json
  • From you cloud storage space, use the Resource Manager to download DocumentA.pdf, DocumentB.pdf, and instructions.json to your local system; here we assume /temp/dynamicpdf-api-samples.
  • After downloading, delete the documents and instructions from samples/merge-pdfs-pdf-endpoint using the Resource Manager. Be certain not to delete DocumentC.pdf.
ResourceCloud/Local
DocumentA.pdflocal
DocumentB.pdflocal
DocumentC.pdfcloud
instructions.jsonlocal
tip

See Sample Resources for instructions on adding sample resources.

Obtaining API Key#

This tutorial assumes a valid API key obtained from the DynamicPDF Cloud API's Environment Manager. Refer to the following for instructions on getting an API key.

tip

If you are not familiar with the Resource Manager or Apps and API Keys, refer to the following tutorial and relevant Users Guide pages.

Calling API Directly Using POST#

Merging resources into a new PDF requires using the pdf endpoint. The pdf endpoint uses an instructions JSON document you send to the endpoint. The endpoint then processes the instructions to create the resultant PDF. When you call the pdf endpoint directly, you must create an instructions document. When you use one of the DynamicPDF client libraries, then the client library hides the complexities of creating the instructions document from you.

Let's call the endpoint directly using an instructions document.

Instructions JSON#

  • Open the instructions.json document that you downloaded earlier in a text editor.
{  "author": "Alex Smith",  "inputs": [    {      "type": "pdf",      "resourceName": "DocumentA.pdf",      "startPage": 1,      "pageCount": 1    },    {      "type": "pdf",      "resourceName": "DocumentB.pdf"    },    {      "type": "pdf",      "resourceName": "samples/merge-pdfs-pdf-endpoint/DocumentC.pdf"    }  ]}

The most important part of an instructions document is the inputs array. This array is where you specify the inputs to the pdf endpoint. Here we are specifying that three PDF documents as the inputs. The first two we refer to by name only, as you will download them from your cloud storage space to your local system and then use them locally. Dynamic resources that change with every request should be uploaded with the request and not reside in your cloud storage. The last document you refer to by the resources' path in your cloud storage space using the Resource Manager.

info

In a real-world application all three PDFs used here would probably come from your cloud storage space and not your local system, as all three documents do not change. You would usually store a PDF in the cloud if it is static in nature, like a cover page or terms sheet, so it does not have to be uploaded with every request. But, for purposes of example, this tutorial shows how to get resources from the cloud or from you local system.

As you see in the next section, when referring to a resource locally, you specify the resource's name in the instructions document and its path in the call to the endpoint. When referring to a resource in your cloud storage space, you specify the path of the resource in the Resource Manager.

tip

Refer to JSON Instructions Schema or Instructions Schema Diagram for more information on creating instruction documents.

cURL Command#

The pdf endpoint takes a POST request. When using cURL, you specify the endpoint, the HTTP command, the API key, any local resources required, and the instructions document. The following cURL command illustrates.

info

Here we are assuming the Windows operating system's filesystem convention.

curl -X POST https://api.dynamicpdf.com/v1.0/pdf -H "Authorization:Bearer DP.Pxxxx-apikey-xxx" -F "Resource=@C:/temp/dynamicpdf-api-samples/DocumentA.pdf" -F "Resource=@C:/temp/dynamicpdf-api-samples/DocumentB.pdf" -F "Instructions=@C:/temp/dynamicpdf-api-samples/instructions.json" -o merge-output.pdf
tip

The cURL command places any errors in the output.pdf rather than command-line. If you cannot open the created PDF, try opening the PDF in a text editor to view the error message.

In the preceding command, the -H parameter specifies that a header variable named Authorization is sent to the endpoint. The two -F parameters specify that they are form fields with the name of Resource and then the value. The value of the two parameters specify the paths of both local resources.

tip

If a filename in the cURL command does not match the filename in the instructions document, then add the filename by using a semicolon followed by the filename from the instructions document.

"Resource=@C:/temp/dynamicpdf-api-samples/DocumentB.pdf;MyDocument" 

The -o parameter specifies the output file to write the response to.

  • Execute the cURL command and the PDF is saved to your local system.

Figure 1. The merged PDF after the pdf endpoint processed.

Calling Endpoint Using Client Library#

To simplify your development, you can also use one of the DynamicPDF Cloud API client libraries. Use the client library of your choice to complete this tutorial section.

Complete Source#

You can access the complete source for this project at one of the following GitHub projects.

LanguageFile NameLocation (package/namespace/etc.)GitHub Project
JavaMergePdfs.javacom.dynamicpdf.api.exampleshttps://github.com/dynamicpdf-api/java-client-examples
C#Program.csMergePdfshttps://github.com/dynamicpdf-api/dotnet-client-examples
NodejsMergePdfs.jsnodejs-client-exampleshttps://github.com/dynamicpdf-api/nodejs-client-examples
PHPMergePdfs.phpphp-client-exampleshttps://github.com/dynamicpdf-api/php-client-examples
tip

Click on the language tab of choice to view the tutorial steps for the particular language.


In all four languages, the steps were similar. First, we created a new instance of the Pdf class, which abstracts the pdf endpoint. This Pdf instance holds the merged PDF after processing. We then added two local resources, DocumentA.pdfand DocumentB.pdf, to the pdf endpoint. We first created a PdfResource instance to add these local resources and then added the PdfResource instance to the Pdf instance. Because we only wanted the first page of DocumentA.pdf, we obtained a reference to the returned PdfInput. By getting a reference to the PdfInput object containing DocumentA.pdf, we could add merge instructions specifying only to use the first page.

tip

The DynamicPDF Cloud API and its client libraries follow the conventions of our desktop product. A classes class properties are mostly handled through obtaining references to objects and manipulating those references.

We then added DocumentC.pdf, but rather than first creating a PdfResource instance, we added the resource directly to the Pdf instance using its AddPdf method.

info

The difference between adding local resources and adding cloud resources in the Resource Manager bears repeating. Add local resources by first creating a PdfResource instance that loads the resource and then adding the PdfResource instance to the Pdf instance using its AddPdf method. Add cloud resources in Resource Manager by calling AddPdf and passing the path in Resource Manager as a string.

After adding all the resources to the Pdf instance, we then call the endpoint using the Process method and obtain the response from the endpoint. Finally, we ensured the call was successful and wrote the response's content to a PDF file.