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, PHP, GO, and Python.

Required Resources​

To complete this tutorial, you must add the merge-pdfs-pdf-endpoint sample to your samples folder in your cloud storage space using the File 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 File 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 File 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. Refer to the following for instructions on getting an API key.

tip

If you are not familiar with the File 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 File Manager.

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 File 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

The tutorial's video uses Postman rather than the cURL command.

curl -X POST https://api.dpdf.io/v1.0/pdf 
-H "Authorization:Bearer DP.xxx-api-key-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 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
GOmerge-pdfs.gogo-client-exampleshttps://github.com/dynamicpdf-api/go-client-examples/tree/main
PythonMergePdfs.pypython-client-exampleshttps://github.com/dynamicpdf-api/python-client-examples
tip

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

Available on NuGet:

Install-Package DynamicPDF.API
  • Create a new Visual Studio C# Console App (.NET Core) project named MergePdfs.
  • Add the DynamicPdf.Api Nuget package to the project.
  • Create a new static method named Run that takes the API key and base path as strings.
  • Add the call to Run to Main.
  • In Run create a new Pdf instance.
  • Add DocumentA.pdf to the Pdf instance and get a reference to the returned PdfInput instance.
  • Set the PdfInput instance's StartPage property to one and its EndPage property to one.
  • Create a new PdfResource instance and in its constructor set the path to DocumentC.pdf
tip

Note the difference between how you add the PDFs. Use the AddPdf method to add a PDF that resides in your cloud storage space but use PdfResource to add a resource from the local system.

  • Create a call to the Process method to return a PdfResponse instance.

  • Check to ensure the call is successful and then write the response's Content to a file.

using System;
using System.IO;

namespace MergePdfs
{
    class Program
    {
    
 static void Main(string[] args)
        {
            Run("DP.xxx-api-key-xxx", "C:/temp/dynamicpdf-api-samples/");
        }

        public static void Run(String apiKey, String basePath)
        {
            // create new pdf instance and set api key
            Pdf pdf = new Pdf();
            pdf.ApiKey = apiKey;

            //add pdf and get reference to PdfInput then set pages to append
            var inputA = pdf.AddPdf(new PdfResource(basePath + "DocumentA.pdf"));
            inputA.StartPage = 1;
            inputA.PageCount = 1;

            // add all of pdf from local system
            pdf.AddPdf(new PdfResource(basePath + "DocumentB.pdf"));

            // add pdf from cloud in resource manager
            pdf.AddPdf("/samples/merge-pdfs-pdf-endpoint/DocumentC.pdf");

            //call the pdf endpoint and get response
            PdfResponse pdfResponse = pdf.Process();

            // if successful, save merged pdf to file otherwise print JSON error
            if(pdfResponse.IsSuccessful)
            {
                File.WriteAllBytes(Path.Combine(basePath, "merge-pdfs-output.pdf"), pdfResponse.Content);
            } else
            {
                Console.WriteLine(pdfResponse.ErrorJson);
            }

        // process and get response from pdf endpoint
        PdfResponse pdfResponse = pdf.Process();

        // if the response is successful, save merged pdf to file if error, then printout JSON error
        if(pdfResponse.IsSuccessful)
        {
            File.WriteAllBytes(Path.Combine(basePath, "merge-output.pdf"), pdfResponse.Content);
        } else
        {
            Console.WriteLine(pdfResponse.ErrorJson);
        }     
    }
}
Source: Program.cs
  • Run the application and the merged PDF is saved to your local system.

In all six 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.

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 File 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 File Manager by calling AddPdf and passing the path in File 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.

   Follow us on social media for latest news!

Last updated on