Render from Templates

Generate PDFs from saved templates using structured JSON data with the Posiboo API.

Render from Templates

Template rendering is the most common way to generate PDFs with Posiboo. You create a reusable template in the dashboard, then render PDFs by sending structured JSON data through the API. Posiboo merges your data with the template to produce a consistent, branded PDF output.

Templates are ideal for documents with predictable structures such as invoices, reports, certificates, tickets, and contracts.

Rendering Modes

Posiboo supports two template rendering modes:

Asynchronous Rendering (Default)

Renders PDFs in the background and delivers the result via webhook. This is the recommended approach for most use cases, especially high-volume or long-running renders.

  • Non-blocking
  • Scales to handle large workloads
  • Result delivered via webhook notification
  • Best for production systems

Synchronous Rendering

Returns the PDF directly in the HTTP response. Suitable for low-latency scenarios where you need immediate access to the file.

  • Blocks the request until rendering completes
  • Returns PDF binary in response body
  • No webhook setup required
  • Best for backend services and low-volume workloads

Authentication

All template rendering requests require an API key. Include your key in the X-API-Key header:

X-API-Key: your_api_key_here

Missing or invalid API keys will result in authentication errors.

Asynchronous Template Rendering

Endpoint

POST https://api.posiboo.com/v1/render/template

Request Headers

  • X-API-Key (required): Your API key
  • Content-Type (required): application/json

Request Body

json
{
"templateId": "your_template_id",
"data": {
  "customerName": "Acme Corp",
  "invoiceNumber": "INV-12345",
  "amount": 1250.00,
  "items": [
    { "description": "Consulting", "price": 500 },
    { "description": "Support", "price": 750 }
  ]
}
}

Fields:

  • templateId (string, required): The unique identifier of your template
  • data (object, required): JSON object containing the dynamic data to merge with your template

Response

The API responds immediately with HTTP 202 Accepted, indicating that the render job has been queued for processing.

HTTP/1.1 202 Accepted

The PDF is rendered asynchronously in the background. When rendering completes, Posiboo sends a webhook notification to your configured endpoint.

Webhook Delivery

When the PDF is ready, you'll receive a webhook event with type pdf.rendered. The webhook payload includes a pdfDownloadUrl field containing a presigned URL to download the generated PDF.

For complete details on webhook structure, signature verification, and security, see the Webhooks documentation.

Synchronous Template Rendering

Endpoint

POST https://api.posiboo.com/v1/render/template/sync

Request Headers

  • X-API-Key (required): Your API key
  • Content-Type (required): application/json

Request Body

The request body is identical to async rendering:

json
{
"templateId": "your_template_id",
"data": {
  "customerName": "Acme Corp",
  "invoiceNumber": "INV-12345",
  "amount": 1250.00
}
}

Response

The API returns the PDF binary directly in the response body:

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="document.pdf"
Content-Length: 245789

<PDF binary data>

You can save this response directly to a file or stream it to your users.

Important Considerations

  • The request blocks until rendering completes
  • Timeout limits apply (typically 30-60 seconds)
  • Not recommended for high-volume or long-running renders
  • Use async rendering for large workloads or when rendering time is unpredictable

Code Examples

Asynchronous Rendering

javascript
const fetch = require('node-fetch');


const apiKey = process.env.POSIBOO_API_KEY;


async function renderAsync() {
const response = await fetch('https://api.posiboo.com/v1/render/template', {
method: 'POST',
headers: {
'X-API-Key': apiKey,
'Content-Type': 'application/json'
},
body: JSON.stringify({
templateId: 'your_template_id',
data: {
customerName: 'Acme Corp',
invoiceNumber: 'INV-12345',
amount: 1250.00
}
})
});


if (response.status === 202) {
console.log('PDF rendering queued successfully');
console.log('You will receive a webhook when the PDF is ready');
} else {
console.error('Error:', response.status, await response.text());
}
}


renderAsync();

Synchronous Rendering

javascript
const fetch = require('node-fetch');
const fs = require('fs');


const apiKey = process.env.POSIBOO_API_KEY;


async function renderSync() {
const response = await fetch('https://api.posiboo.com/v1/render/template/sync', {
method: 'POST',
headers: {
'X-API-Key': apiKey,
'Content-Type': 'application/json'
},
body: JSON.stringify({
templateId: 'your_template_id',
data: {
customerName: 'Acme Corp',
invoiceNumber: 'INV-12345',
amount: 1250.00
}
})
});


if (response.ok) {
const buffer = await response.arrayBuffer();
fs.writeFileSync('output.pdf', Buffer.from(buffer));
console.log('PDF saved to output.pdf');
} else {
console.error('Error:', response.status, await response.text());
}
}


renderSync();

Error Handling

Template rendering requests can fail for various reasons. Always check the response status and handle errors appropriately.

Common Error Responses

400 Bad Request

The request body is malformed or missing required fields. Check that you've included both templateId and data fields.

401 Unauthorized

Your API key is missing, invalid, or has been revoked. Verify that the X-API-Key header is set correctly.

403 Forbidden

You don't have access to the specified template. Ensure the template exists and belongs to your account.

404 Not Found

The specified template ID does not exist. Verify the templateId value is correct.

402 Payment Required

Your account has insufficient credits to render this PDF. Add credits in your dashboard.

429 Too Many Requests

You've exceeded the rate limit for your account. Implement exponential backoff and retry logic.

500 Internal Server Error

An unexpected error occurred during rendering. Retry the request. If the problem persists, contact support.

504 Gateway Timeout (sync only)

The synchronous rendering request timed out. This typically occurs with complex templates or large documents. Consider using async rendering instead.

Error Response Format

Error responses include a JSON body with details:

json
{
"error": {
  "code": "INVALID_TEMPLATE_ID",
  "message": "Template not found"
}
}

Choosing Between Sync and Async

Use Asynchronous Rendering When:

  • Rendering high volumes of PDFs
  • Building production systems that need to scale
  • Rendering time may exceed a few seconds
  • You can implement webhook handling
  • You want to decouple rendering from request handling

Use Synchronous Rendering When:

  • You need immediate access to the PDF file
  • Rendering in backend services (not user-facing APIs)
  • Working with simple templates that render quickly
  • Webhook infrastructure is not available
  • Building prototypes or internal tools

Comparison

Async Rendering (/v1/render/template)

  • Response time: Immediate (202 accepted)
  • Result delivery: Via webhook callback
  • Timeout risk: No - processes in background
  • Scalability: High - handles large volumes
  • Setup complexity: Requires webhook endpoint
  • Best for: Production systems, high-volume rendering

Sync Rendering (/v1/render/template/sync)

  • Response time: Waits for PDF generation to complete
  • Result delivery: Direct PDF response body
  • Timeout risk: Yes - can timeout on large templates
  • Scalability: Limited by connection timeouts
  • Setup complexity: None - simple HTTP request
  • Best for: Backend services, on-demand rendering

Next Steps

Render from Templates | Posiboo | Posiboo