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.
| Field | Meaning |
|---|---|
template_id | Id of a stored template. Or send a complete document. |
document | A whole document as JSON, instead of a template. |
records | List of objects with the placeholder values, one per sheet. |
csv | The same data as CSV or JSON text, instead of records. |
copies | Copies per record. Default 1. |
additional_template_ids | Templates printed after the main one for every record, e.g. the envelope. |
scheduled_at | Do not start before this time (ISO 8601). |
confirm_each_page | Wait after every sheet until the job is resumed (manual feeding). |
strict | Reject the job if a placeholder has no value. |
strict_layout | Reject the job if a sheet writes outside the margins or into a postal zone. |
hold | Create the job paused; it waits for approval in the app. |
callback_url | Address that is notified when the job has finished. |
seed | Fixed 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:
| State | Meaning |
|---|---|
scheduled | Waits for its start time. |
queued | Waits for the printer. |
printing | A sheet is being written. |
paused | Paused by a person, or waiting for approval. |
waiting_for_paper | Waits for the next sheet to be loaded and confirmed. |
done | All sheets written. |
failed | A sheet failed; the error field says why. |
canceled | Canceled. |
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.