Workflows

Workflows describe the PDF you want to generate. The workflow object is what you send in your request body, when you call the API. Here’s a simple one:


{
  "parts": [
    {
      "type": "template",
      "slug": "hello-world@v1",
      "variables": {
        "name": "John Doe",
        "age": 30
      }
    }
  ]
}

It contains a parts array, which is an ordered list of the parts that will be joined together to form your final PDF. In most situations, you only need one part per workflow. But you can have as many as you like, and they can be of different types.

Part Types

Parts are the building blocks of a PDF in Letterhead. They can be templates, URLs, raw HTML, or other PDFs.

Template — A template part makes use of a template that you define in the Letterhead app. Templates are defined in Liquid - a language with a simple templating syntax on top of ordinary HTML. You can pass variables at request time to populate your template.


{
  "type": "template",
  "slug": "hello-world@v1",
  "variables": {
    "name": "John Doe",
    "age": 30
  }
}

HTML — A raw HTML part includes the HTML content for the part directly in the request body. This is useful if you want to generate a PDF from a static HTML file, or if you render dynamic HTML on your side but don’t want to host it on a server.


{
  "type": "html",
  "content": "<h1>Hello, world!</h1>"
}

PDF — A PDF part includes the content of another PDF in the PDF you are generating. This is useful if you need to include a pre-rendered PDF as a smaller part in a larger PDF that may use other part types, or if you are merging together several existing PDFs.


{
  "type": "pdf",
  "url": "https://example.com/path/to/pdf"
}

URL — A URL part fetches the content of a web page and includes it in the PDF. You can use this if you prefer to host the HTML for your PDF yourself, and use Letterhead as the PDF generation infrastructure in your pipeline. You can still achieve dynamic content in this approach by hosting dynamic content on your server and passing a URL with query parameters.


{
  "type": "url",
  "url": "https://example.com/path/to/page"
}