GET/v1/items/{id}/preview

Preview images of an item

Renders the item with its template version, recipient and variables through a render request; poll until READY for the signed image URLs (ITEM-007).

Scope items.readRate limit class preview

Path parameters

idstringrequired

Query parameters

sidestring

dpiintegermin 36max 300default 150

Returns

12 fields of the 200 answer

itemIdstringrequired

idstringrequired

kindenumrequired

previewproof

templateIdstringrequired

templateVersionIdstringrequired

statusenumrequired

PENDINGRUNNINGREADYFAILED

paramsobjectrequired

5 fields

variablesobjectrequired

recipientobject or nullrequired

6 fields

namestringrequired

addressLine1stringrequired

addressLine2string

postalCodestringrequired

citystringrequired

countrystringrequired

sidestring or nullrequired

dpiintegerrequired

qrShortUrlstring or nullrequired

urlsobjectrequired

issuesarray of objectsrequired

4 fields

codestringrequired

severityenumrequired

errorwarning

messagestringrequired

elementIdstring

errorstring or nullrequired

createdAtdate-timerequired

finishedAtdate-time or nullrequired

Responses

200Success

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)

import { PostBuddyClient } from '@postbuddy/sdk'; const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! }); const result = await client.items.preview('itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K');

{ "itemId": "itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "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": "first_name" }, "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" } ] }