Press

Appearance

Using the API ​

You've designed your template using the platform and everything looks great. You've added some example data and a content flow to preview how a template would look on the platform. The next step is to integrate Papermill with your software and get going! Let's generate a simple document via the API. We'll send some text to be typeset in a template and get back the PDF.

Obtain your API Key ​

The first step is to obtain an API key from the Papermill Platform. After logging in, you can click "API" in the top-right corner to open the API panel.

Under "API Keys" click "Create New API Key". In the popup, click "Copy to Clipboard" and store the key safely, for example in a secure password manager. You won't be able to view the key again.

You can create multiple keys and enable or disable them through the API panel.

Create the Template ​

Create a new template in the platform. We'll use this simple example of a letter template for the sake of this tutorial:

<press>
  <document>
    <page width="21cm" height="29.7cm" padding="2cm">
      <frame height="2cm" width="100%">
        <p text-align="right" width="100%">{{ data.date }}</p>
        <p text-align="right" width="100%">{{ data.recipient }}</p>
      </frame>
      <flow name="body" />
      <frame width="50%" height="5cm" space-before-desired="24pt">
        <p>Yours,</p>
        <p>{{ data.author }}</p>
      </frame>
    </page>
  </document>
</press>

Paste this template into the editor and refresh the preview so you can be sure everything works. In a normal Papermill workflow, you'll edit the template in the editor with example content until you're happy before moving on to call the API from code.

INFO

The previews provided by the editor use Papermill's draft mode, and do not count towards your main quota. To make an API request in draft mode, set draft=true as a query parameter.

Draft mode allows testing of Papermill in a quota-free way, but will add watermarks to generated documents.

Downloading a document from the Papermill editor through the Download button will generate the document without the draft mode watermark, but will also count towards your quota.

Generate the PDF ​

The template includes both the design and the content of the letter. When we want to generate the document, we only want to change the content.

The API will accept an XML payload containing your full template, or a partial document containing just the top-level tags you want to change --- usually the <flows> tag and the <data> tag. This makes it easy to reuse your template from the editor via the API.

To reuse the template via the API, you pass the template ID as a query parameter template_id. You can find the template ID in the browser address bar when you're editing the template (we know, it's alpha software!)

You can then call the PDF generation endpoint from your code:

JavaScript
const templateId = '<your template id>'

const payload = `
  <press>
    <flows>
      <body>
        Thank you for your application.
        I'm delighted to offer you the position.
      </body>
    </flows>
    <data>
      <recipient>Alan Turing</recipient>
      <author>Mr P. Mill</author>
      <date>1/1/1970</date>
    </data>
  </press>
`
const response = await fetch(
    `https://api.papermill.io/v2/pdf?template_id=${templateId}&draft=true`,
    {
        method: 'POST',
        headers: {
                'Content-Type': 'text/xml',
                'X-API-Key': `${YOUR_API_KEY}`
        },
        body: payload
    }
)

const pdfData = await response.arrayBuffer();
Python
import requests

payload = """
  <press>
    <flows>
      <body>
        Thank you for your application.
        I'm delighted to offer you the position.
      </body>
    </flows>
    <data>
      <recipient>Alan Turing</recipient>
      <author>Mr P. Mill</author>
      <date>1/1/1970</date>
    </data>
  </press>"""

pdf_data = requests.post(
    "https://api.papermill.io/v2/pdf?template_id=YOUR_TEMPLATE_ID&draft=true",
    headers={
            "Content-Type": "text/xml",
            "X-API-Key": f"{YOUR_API_KEY}"
    },
    data=payload
)
bash
curl -X POST \
  -H "Content-Type: text/xml" \
  -H "X-API-Key: API_KEY" \
  -d "<press> \
    <flows> \
      <body> Thank you for your application. I'm delighted to offer you the position.</body> \
    </flows> \
    <data> \
      <recipient>Alan Turing</recipient> \
      <author>Mr P. Mill</author> \
      <date>1/1/1970</date> \
    </data> \
  </press>" \
  --output response.pdf \
  https://api.papermill.io/v2/pdf?template_id=TEMPLATE_ID&draft=true
Elixir
xml_body = """
<press>
  <flows>
    <body>
      Thank you for your application.
      I'm delighted to offer you the position.
    </body>
  </flows>
  <data>
    <recipient>Alan Turing</recipient>
    <author>Mr P. Mill</author>
    <date>1/1/1970</date>
  </data>
</press>
"""

headers = [{"Content-Type", "text/xml"}, {"X-API-Key", "API_KEY"}]
url = "https://api.papermill.io/v2/pdf?template_id=TEMPLATE_ID&draft=true"

{:ok, response} = HTTPoison.post(url, xml_body, headers)
File.write!("response.pdf", response.body)

You'll want to add error handling and remove the draft for production use!