POST/v1/postbatches/{id}/proof

Proof PDF of a sample item

Renders the pinned template version with the recipient and variables of the chosen item; poll the render.

Scope items.read

Path parameters

idstringrequired

Body

itemIdstringrequiredmin length 1max length 40

Returns

11 fields of the 200 answer

idstringrequired

kindenumrequired

previewproof

templateIdstringrequired

templateVersionIdstringrequired

statusenumrequired

PENDINGRUNNINGREADYFAILED

paramsobjectrequired

2 fields

variablesobjectrequired

recipientobject or nullrequired

6 fields

namestringrequired

addressLine1stringrequired

addressLine2string

postalCodestringrequired

citystringrequired

countrystringrequired

urlsobjectrequired

issuesarray of objectsrequired

4 fields

codestringrequired

severityenumrequired

errorwarning

messagestringrequired

elementIdstring

errorstring or nullrequired

createdAtdate-timerequired

finishedAtdate-time or nullrequired

Responses

200Success

202The render is still running; poll it

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/postbatches/pb_01J9Y2K8QF4T6W8Z0B2D4F6H8K/proof \ -H "Authorization: Bearer $POSTBUDDY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "itemId": "itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K" }'

import { PostBuddyClient } from '@postbuddy/sdk'; const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! }); const result = await client.postbatches.proof('pb_01J9Y2K8QF4T6W8Z0B2D4F6H8K', { body: { itemId: 'itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K', }, });

import os from postbuddy import Client client = Client(os.environ["POSTBUDDY_API_KEY"]) result = client.postbatches.proof("pb_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" } }, "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" } ] }