Render from Templates

Learn how to generate PDFs from your custom templates using the Posiboo API.

Render from Templates

Generate PDFs from your custom templates by sending structured data to the Posiboo API. This is the most common way to create PDFs with consistent branding and layouts.

Overview

The /v1/render/template endpoint accepts a template ID and JSON data, then renders a PDF by merging your data with the template HTML/CSS. The rendering happens asynchronously in the background, and you'll receive a webhook notification when the PDF is ready.

Authentication

All requests must include your API key in the x-api-key header:

bash
x-api-key: your_api_key_here

You can create and manage API keys in your dashboard.

Basic Usage

javascript
const data = {
title: "Invoice #12345",
customer: "Acme Corp",
amount: "$1,250.00",
date: "2024-10-01"
};


fetch("https://api.posiboo.com/v1/render/template", {
method: "POST",
headers: {
  "x-api-key": "<your-api-key>",
  "Content-Type": "application/json"
},
body: JSON.stringify({
  templateId: "cm123455837sh",
  data: data
})
})
.then(response => {
  if (response.status === 202) {
    console.log("PDF rendering started successfully");
  }
})
.catch(error => {
  console.error("Error:", error);
});

Request Parameters

Required Fields

templateId (string) - The unique identifier of your template. Find this in your Templates Store.

data (object) - JSON object containing the dynamic data to merge with your template.

Optional Fields

settings (object) - PDF generation settings (see Advanced Settings below).

overrideHtml (string) - Override the template's HTML with custom HTML for this render.

overrideCss (string) - Override the template's CSS with custom CSS for this render.

Advanced Settings

Customize the PDF output with optional settings:

javascript
{
"templateId": "cm123455837sh",
"data": { /* your data */ },
"settings": {
  "format": "A4",           // Paper size: A4, Letter, Legal, etc.
  "orientation": "portrait", // portrait or landscape
  "margin": {
    "top": "20px",
    "right": "20px",
    "bottom": "20px",
    "left": "20px"
  },
  "printBackground": true,   // Include background colors/images
  "scale": 1.0               // Scale factor (0.1 to 2.0)
}
}

Response

The endpoint returns HTTP 202 Accepted immediately, indicating that your PDF rendering job has been queued for processing.

bash
HTTP/1.1 202 Accepted

The PDF is rendered asynchronously in the background. When it's ready, you'll receive a webhook notification (see Webhooks below).

Webhooks

When your PDF is successfully rendered, Posiboo sends a webhook event to the URL you configured in your Webhooks settings.

Webhook Payload

json
{
"event": "pdf.rendered",
"timestamp": "2024-10-01T12:00:00Z",
"data": {
  "jobId": "job_abc123xyz",
  "templateId": "cm123455837sh",
  "status": "completed",
  "pdfUrl": "https://cdn.posiboo.com/pdfs/abc123.pdf",
  "downloadUrl": "https://api.posiboo.com/v1/pdfs/abc123/download",
  "expiresAt": "2024-10-08T12:00:00Z",
  "renderTime": 1.24,
  "pageCount": 3
}
}

Webhook Events

pdf.rendered - PDF was successfully generated and is ready for download.

pdf.failed - PDF rendering failed (includes error details).

Configure your webhook endpoint in the Webhooks section of your dashboard.

HTML Template Variables

Access your data in templates using double curly braces:

html
<div class="invoice">
<h1>{{title}}</h1>
<p>Customer: {{customer}}</p>
<p>Amount: {{amount}}</p>
<p>Date: {{date}}</p>
</div>

You can also use nested objects and arrays:

javascript
{
"templateId": "invoice_template",
"data": {
  "invoice": {
    "number": "INV-001",
    "customer": {
      "name": "Acme Corp",
      "email": "billing@acme.com"
    }
  },
  "items": [
    { "name": "Service A", "price": 500 },
    { "name": "Service B", "price": 750 }
  ]
}
}
html
<h1>Invoice {{invoice.number}}</h1>
<p>Bill to: {{invoice.customer.name}}</p>
<p>Email: {{invoice.customer.email}}</p>


<ul>
{{#each items}}
  <li>{{name}}: ${{price}}</li>
{{/each}}
</ul>

Override HTML/CSS

You can override your template's HTML or CSS for a specific render:

javascript
{
"templateId": "cm123455837sh",
"data": { "name": "John Doe" },
"overrideHtml": "<html><body><h1>\\{\\{name\\}\\}</h1></body></html>",
"overrideCss": "h1 { color: blue; font-size: 32px; }"
}

This is useful for one-off customizations without modifying your saved template.

Error Handling

202 - Success - PDF rendering has been queued

400 - Bad Request - Missing or invalid templateId

401 - Unauthorized - Invalid or missing API key

404 - Template not found

429 - Too Many Requests - Rate limit exceeded

500 - Server Error - Contact support

Rate Limiting

The /v1/render/template endpoint is rate-limited to 2 requests per minute per API key during development. Contact us for higher limits on production accounts.

Best Practices

  1. Use Webhooks - Don't poll for completion. Configure webhooks to get notified when PDFs are ready.
  2. Validate Data - Ensure your data object matches your template's expected structure before sending.
  3. Test Templates - Test your templates in the dashboard editor before using them in production.
  4. Handle Errors - Always check the response status and handle errors gracefully.
  5. Store Template IDs - Keep your template IDs in environment variables or a config file.

Next Steps