Skip to content
PenBlitz
← Developers

API: jobs and mail merge

Create print jobs from templates and data, follow their progress and control the queue.

Create a job

POST /api/v1/jobs takes what to print and the data. Each record becomes one sheet.

FieldMeaning
template_idId of a stored template. Or send a complete document.
documentA whole document as JSON, instead of a template.
recordsList of objects with the placeholder values, one per sheet.
csvThe same data as CSV or JSON text, instead of records.
copiesCopies per record. Default 1.
additional_template_idsTemplates printed after the main one for every record, e.g. the envelope.
scheduled_atDo not start before this time (ISO 8601).
confirm_each_pageWait after every sheet until the job is resumed (manual feeding).
strictReject the job if a placeholder has no value.
strict_layoutReject the job if a sheet writes outside the margins or into a postal zone.
holdCreate the job paused; it waits for approval in the app.
callback_urlAddress that is notified when the job has finished.
seedFixed handwriting variant; random if omitted.
curl -X POST http://127.0.0.1:8787/api/v1/jobs \
  -H 'Content-Type: application/json' \
  -d '{
    "template_id": "voucher-qr",
    "csv": "salutation;code\nMrs. Smith;FHE93KL\nMr. Jones;KQ7X2MB",
    "strict": true
  }'

Follow a job

GET /api/v1/jobs/{id} returns the job with every page. The state is one of:

StateMeaning
scheduledWaits for its start time.
queuedWaits for the printer.
printingA sheet is being written.
pausedPaused by a person, or waiting for approval.
waiting_for_paperWaits for the next sheet to be loaded and confirmed.
doneAll sheets written.
failedA sheet failed; the error field says why.
canceledCanceled.

Control

  • POST /api/v1/jobs/{id}/pause, /resume and /cancel act on one job.
  • Resume also confirms a paper change and retries the remaining sheets of a failed job.
  • POST /api/v1/queue/pause and /resume hold and release the whole queue.
  • GET /api/v1/jobs/{id}/pages/{page}/preview.svg returns the picture of one sheet (page numbers start at 0).

Warnings

Each page of a job carries its warnings: a placeholder without value, text that leaves the margins, a QR code too small for the pen. Read them before a large batch, or send strict and strict_layout so that such a job is refused.