POST/v1/templates/{id}/versions/{number}/previews

Request preview images of a version

Answers 202 while rendering and 200 when an identical request was rendered before; poll GET /v1/previews/{id}.

Scope templates.readRate limit class preview

Path parameters

numberstringrequired

idstringrequired

Body

variablesobjectdefault {}

recipientobject

6 fields

namestringrequiredmax length 200

addressLine1stringrequiredmax length 200

addressLine2stringmax length 200

postalCodestringrequiredmax length 20

citystringrequiredmax length 100

countrystringrequiredmin length 2max length 2

sidestring

dpiintegermin 36max 300default 150

qrShortUrlstring

Returns

11 fields of the 200 answer

idstringrequired

kindenumrequired

previewproof

templateIdstringrequired

templateVersionIdstringrequired

statusenumrequired

PENDINGRUNNINGREADYFAILED

paramsone ofrequired

urlsobjectrequired

issuesarray of objectsrequired

4 fields

codestringrequired

severityenumrequired

errorwarning

messagestringrequired

elementIdstring

errorstring or nullrequired

createdAtdate-timerequired

finishedAtdate-time or nullrequired

Responses

200Success

202Rendering; poll the preview request

401Authentication required or API key invalid

403Permission or scope missing, organisation suspended

404Not found

422Validation failed

429Rate limited for this API key and class; wait Retry-After seconds

otherError (RFC 9457 problem details)

curl -X POST https://api.postbuddy.nl/v1/templates/tpl_01J9Y2K8QF4T6W8Z0B2D4F6H8K/versions/tv_01J9Y2K8QF4T6W8Z0B2D4F6H8K/previews \ -H "Authorization: Bearer $POSTBUDDY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "variables": { "first_name": "Sanne" }, "recipient": { "name": "Sanne de Vries", "addressLine1": "Oudegracht 112", "postalCode": "3511 AX", "city": "Utrecht", "country": "NL" }, "side": "first_name", "dpi": 36, "qrShortUrl": "https://example.com/r/Fq3ZtR8w" }'

import { PostBuddyClient } from '@postbuddy/sdk'; const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! }); const result = await client.renders.preview('tpl_01J9Y2K8QF4T6W8Z0B2D4F6H8K', 'tv_01J9Y2K8QF4T6W8Z0B2D4F6H8K', { body: { variables: { first_name: 'Sanne', }, recipient: { name: 'Sanne de Vries', addressLine1: 'Oudegracht 112', postalCode: '3511 AX', city: 'Utrecht', country: 'NL', }, side: 'first_name', dpi: 36, qrShortUrl: 'https://example.com/r/Fq3ZtR8w', }, });

import os from postbuddy import Client client = Client(os.environ["POSTBUDDY_API_KEY"]) result = client.renders.preview("tpl_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "tv_01J9Y2K8QF4T6W8Z0B2D4F6H8K", { "variables": { "first_name": "Sanne", }, "recipient": { "name": "Sanne de Vries", "addressLine1": "Oudegracht 112", "postalCode": "3511 AX", "city": "Utrecht", "country": "NL", }, "side": "first_name", "dpi": 36, "qrShortUrl": "https://example.com/r/Fq3ZtR8w", })

{ "id": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "kind": "preview", "templateId": "tpl_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "templateVersionId": "tv_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "status": "READY", "params": { "variables": { "first_name": "Sanne" }, "recipient": { "name": "Sanne de Vries", "addressLine1": "Oudegracht 112", "addressLine2": "2nd floor", "postalCode": "3511 AX", "city": "Utrecht", "country": "NL" }, "side": "Example", "dpi": 1, "qrShortUrl": "https://example.com/r/Fq3ZtR8w" }, "urls": { "key": "https://example.com/r/Fq3ZtR8w" }, "issues": [ { "code": "validation_failed", "severity": "error", "message": "The postal code is not valid", "elementId": "el_01J9Y2K8QF4T6W8Z0B2D4F6H8K" } ], "error": "Example", "createdAt": "2026-10-16T09:14:02.000Z", "finishedAt": "2026-10-16T09:14:02.000Z" }

{ "type": "https://docs.postbuddy.nl/errors/validation_failed", "title": "Validation failed", "status": 422, "code": "validation_failed", "detail": "Validation failed", "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "errors": [ { "field": "recipient.postalCode", "code": "invalid_string", "message": "Invalid postal code" } ] }