Skip to main content

pdf


Use the pdf endpoint to create pages, PDF reports from DLEX files, convert images to PDF, and merge PDFs into a combined PDF.


The pdf endpoint is arguably the most useful, and most complex, endpoint the DynamicPDF Cloud API offers. Use the pdf endpoint to create simple one-page PDF documents (cover pages for example), create documents/reports using DLEX files, convert images to PDFs, and to merge PDFs into a combined PDF.

info

Refer to pdf in the Client Libraries Users Guide section for this example using the DynamicPDF Cloud API's client libraries.

You can also combine the results from these tasks to merge into a single PDF document. You perform one or more of the following tasks using the pdf endpoint.

caution

The pdf endpoint is more complex than the other Cloud API endpoints. You must understand the pdf endpoint's schema for creating instructions if you use this endpoint via a REST call rather than one of our client libraries. pdf.instructions - JSON Schema.

TaskDescription
pageCreate a simple one-page PDF document such as a cover-page.
dlexCreate a report/document from a DLEX file combined with JSON data.
imageConvert an image to a PDF.
pdfSpecify a pre-existing PDF to merge with other PDF documents.
One or more of the four listed tasks.Combine any of the four previous tasks to create and return a combined PDF document.

The pdf endpoint takes an HTTP POST form submission, the Instructions JSON document is sent as a file upload in the form's body.

POST https://api.dynamicpdf.com/v1.0/pdf HTTP/1.1Authorization: Bearer your-api-key

Parameters#

Header ParametersTypeDescription
AuthorizationBearer DP.V9xxxxThe API key used to authenticate endpoint.
Form Fields
ResourcestringThe resource path and filename on cloud resources.
InstructionsfilePath to the local instructions JSON file.

Example#

curl https://api.dynamicpdf.com/v1.0/pdf -H"Authorization:Bearer DP.V9xxxxxxxxxxxxxxx"-F "Instructions=@C:/instructions-simple-page.json"-o simple-page.pdf

Instruction Document#

Understanding the pdf endpoint requires understanding the pdf.instructions.schema.json JSON schema, as the instructions document is where the pdf endpoint does its real work. Calling the pdf endpoint requires a JSON document that contains the instructions on the tasks you wish performing when calling the endpoint. You combine one or more of these tasks (or more accurately inputs) to create a final PDF.

Creating Instructions#

info

Refer to pdf.instructions - JSON Schema endpoint for a detailed description of the pdf.instructions schema.

The first thing every instructions document must contain is at least one input type in the input array. The input is the source for the final PDF. Inputs can be images, DLEX files, and other PDFs. For example, in the following code snippet the instructions document contains two inputs which are merged to create a merged PDF.

{  "author": "John Doe",  "title": "Getting Started - Merge Two PDFs",  "inputs": [    {      "type": "pdf",      "resourceName": "getting-started/A.pdf"    },    {      "type": "pdf",      "resourceName": "getting-started/myimage.png"    }  ]}
More on Inputs#

Understanding the inputs array is fundamental to understanding the pdf endpoint and the processing that occurs to produce a finished PDF. Two or more inputs indicate the two inputs will be merged into a new PDF document. For example, consider a PDF input and an image that occur in that order.

Figure 1. Merging two inputs to create a new PDF.

  • Create a new PDF from A.pdf.
  • Convert myimage.png into a PDF.
  • Append the image PDF to the newly created already containing A.
  • Return the resultant PDF.

The order that you specify the inputs in your instructions document is the order they are merged to create the final PDF.

Of course, you are not required to merge the outputs of one input type with another. You can also use the pdf endpoint as a standalone input. For instance, if you called the pdf endpoint and only included one image input type, then the pdf endpoint would convert the image to a PDF and then return that PDF.

tip

Remember, two or more inputs in the same instructions document merges the output of those inputs into a combined PDF.

It is important you understand the inputs array and how they are combined to form a finished PDF. Undoubtedly you will use the pdf endpoint extensively, so it is important you understand how to use the inputs array into a finished PDF.

More on pdf Endpoint#

This Users Guide topic only provided brief information on the pdf endpoint. But understanding the pdf endpoint requires understanding the endpoint's instructions JSON document. For more information on creating an instructions document, refer to one of the following topics. You can also chose to use one of the client libraries if you prefer to eschew creating an instructions document. The client library abstracts the complexities of creating an instructions document and creates it for you behind the scenes.