Generate a PDF using the API

How it works

You can generate a PDF by making a POST request to the https://app.pdferret.dev/api/pdf endpoint with a body like this:

{
    "payload": {
        ...YOUR_PAYLOAD // your data (1)
    },
    "template": "YOUR_TEMPLATE_ID", // the template identifier string
    "callback_url": "YOUR_CALLBACK_URL" // this is optional (2)
}

Here you send the JSON object you defined to fill your PDF file.
The callback URL is an optional field. If you choose not to send it, the PDF will be available for download after generation. Continue reading for more information about this.

We offer two alternatives to retrieve your generated PDF:

Alternative A: Setting a callback_url in the body of your POST request, and then receive the generated PDF there.
Alternative B: Not setting a callback_url in the body of your POST request, and then polling the PDF endpoint to know when your PDF file is ready. After it is, download it.

Setting a callback URL

The following diagram shows how you should interact with our API in this scheme:

sequenceDiagram
  autonumber
  Your webapp->>PDFerret: Render a PDF, and send it back to this URL!
  PDFerret->>Your webapp: On it!
  Note right of PDFerret: Generate PDF
  PDFerret->>Your webapp: There you go!

You send a PDF generation request to PDFerret, including a callback_url. More details on the request here.
PDFerret enqueues your PDF generation request.
When the PDF generation is finished, PDFerret sends the file to your callback_url.

You send a PDF generation request, and then wait to receive it on an endpoint defined by you.

This is well suited for scenarios where the you are requesting the PDF generation from a web application or API, and can have a dedicated endpoint for this.

Warning

Protect your callback_url by using a signed URL, or including some random and hard-to-guess string to validate incoming requests. This way you ensure the PDF file you receive was requested by your application.

Examples

.NETLaravelpythonJavaScript

.NET example coming soon...

Laravel example coming soon...

Python example coming soon...

JavaScript example coming soon...

Polling the PDF endpoint

The diagram below shows how to interact with out API in this scheme:

sequenceDiagram
  autonumber
  Your app->>PDFerret: Render a PDF!
  PDFerret->>Your app: On it!
  loop Poll generation status
      Note right of PDFerret: Generate PDF
      Your app->>PDFerret: How is it going?
      PDFerret->>Your app: pending/in progress/completed/failed
  end
  Your app->>PDFerret: Give me my PDF!
  PDFerret->>Your app: There you go!

You send a PDF generation request to PDFerret. More details on the request here.
PDFerret enqueues your PDF generation request, and returns a status code 201 response containing a pdf_url to track its status.
You poll the pdf_url to check the status of the PDF generation.
PDFerret returns an object with the status of the PDF generation. The possible statuses are: pending, processing, completed, and failed. This endpoint also returns a download_url.
When the status of your PDF generation is complete, you can download your pdf by using the download_url.
PDFerret returns your PDF.

Warning

Wait some time between your poll checks, to avoid surpassing our rate-limiting. We recommend using the exponential back-off strategy. Review the examples below for more details on this.