Dökümantasyon

List templates

Paginated list of templates in a workspace. Filter by active flag, folder, or substring on name.

Response

{
  "templates": [
    {
      "id": "…",
      "workspaceId": "…",
      "name": "Invoice",
      "fields": [
        "…"
      ],
      "active": true,
      "folder": "invoices",
      "updatedAt": "…"
    }
  ],
  "nextCursor": null
}

Get one template

Full template metadata including field placements and the linked schema id.

Response

{
  "template": {
    "id": "…",
    "name": "Invoice",
    "fields": [
      "…"
    ],
    "schemaId": "…",
    "active": true
  }
}

Render one PDF

Synchronous render. Default streams application/pdf back. Optional responseMode='s3' returns a presigned download URL instead.

Response

(application/pdf — binary stream)

// or, with responseMode: "s3"
{ "downloadUrl": "https://…", "expiresAt": "…", "urlExpiresAt": "…" }

filename is optional. If supplied, it sets the response's Content-Disposition; otherwise we fall back to a sanitized version of the template name. Path separators and control characters are stripped; .pdf is appended if missing.

renderer (optional) selects the engine: plumav1 (default; required for QR/barcode, shapes, signatures, custom transforms) or standard (legacy AcroForm-only path).

responseMode (optional, default "inline"): set to "s3" to upload the rendered PDF to the paid renders bucket and return a presigned downloadUrl instead of the bytes. The URL is valid for 10 minutes; the underlying object lives until its expiresAt (controlled by ttlSeconds below).

ttlSeconds (optional) sets how long the stored render survives in the bucket. Capped by your plan: Free 30 min, Advanced 7 d, Pro 30 d, Enterprise 90 d. Default 72 h on paid tiers, 30 min on Free. Values above the plan cap return 400 ttl_exceeds_plan.

password (optional) password-protects the rendered PDF. Requires the template to opt in via apiCanSetPassword; otherwise the field is ignored. If the template has its own default password set in the editor, the request-body password overrides it.

ignoreErrors (optional, default false) controls what happens when a field's custom transform code throws, rejects, fails to compile, or times out:

• false — any transform failure aborts the render with HTTP 400 and a JSON body { "error": "transform_failed", "fields": [{ "name": "…", "message": "…" }, …] }. You get every offending field at once, not just the first.
• true — failures are coerced as if the transform had returned null: text fields fall back to the pre-transform value, checkboxes render unchecked, radios render no widget. The PDF still comes back as 200 application/pdf and the count of silently-failed transforms is on the X-Pluma-Transform-Errors response header. Wire this header to your monitoring if you use soft mode in production.

Bulk render (synchronous)

Render up to 30 items in one request and stream a ZIP back. Each item gets its own PDF inside the archive.

Response

(application/zip — binary stream)

Per-item filename is optional. Items without one default to <template-slug>_0001.pdf, <template-slug>_0002.pdf, … — e.g. a template named Sample template — try it! produces sample-template-try-it_0001.pdf. Names are ASCII-slugified (accents stripped, non-alphanumerics collapsed to dashes); if the template name has no ASCII characters at all, the prefix falls back to item. Duplicate names get a -2, -3, … suffix so unzip never overwrites.

ignoreErrors applies uniformly to every item — per-item overrides are ignored. Default false: the first item whose transform throws aborts the entire request with HTTP 400 and body { "error": "transform_failed", "template", "itemIndex", "fields": [...] }. Siblings already in flight are dropped; no further items are scheduled. With true the renderer coerces failures per item and the response is the usual ZIP; per-item counts surface on the renderer-side log, not on the ZIP response.

Send a template out for e-signature

Renders the PDF, stores it in the paid renders bucket, and emails the recipient a /sign/<token> link. When they sign, the PDF is re-rendered with their signature embedded and delivered to your template's deliveryEmail (or your tenant owner, if unset).

Response

{
  "signatureRequestId": "uuid",
  "recipientEmail": "[email protected]",
  "status": "pending",
  "expiresAt": "2026-05-17T10:00:00.000Z"
}

recipientEmail is the only required field. The address is lowercased before storage; subsequent lookups don't depend on case. The template must contain at least one signature field with kind=request for the recipient's signature to land in the re-rendered PDF.

data follows the same shape as /generate — values keyed by field JSON-path. Image-typed values can reference uploaded field-images by id; expansion happens server-side.

recipientName (optional, max 200 chars) is the recipient's display name. When set, the /sign/<token> page greets them by name ("Hi Jane, please sign…") and the request email opens with "Hi Jane,"; otherwise we fall back to the email localpart and a generic "Hi,". Stored verbatim on the SignatureRequest row so the dashboard and the recipient-copy email reuse the same name.

requesterDisplayName (optional) is the sender name shown in the request email. Defaults to the authenticated user's display name or email.

Lifecycle. The SignatureRequest expires after 7 days (default). Recipient can sign once or decline; either flips the row's status and a second visit to /sign/<token> returns 410. The expiry sweeper marks any still-pending row past expiresAt as expired hourly.

Availability. Hosted Pluma only. Self-hosted installs return 402 not_available_on_self_hosted.

Plan gate. Free is blocked entirely — Free tenants get 402 paid_tier_required. Paid tiers include a monthly quota: Advanced 20, Pro 100, Enterprise 500. Past the quota, each sign-request is billed from your prepaid balance at €0.10 (configurable via SIGN_REQUEST_OVERAGE_CENTS). When the balance is empty AND the quota is exhausted, the endpoint returns 402 sign_request_quota_exceeded with a top-up hint.

Render-quota cost. The initial pre-sign render counts against your /generate render quota (same accounting). The post-sign re-render does NOT — it's triggered by the recipient, not your tenant. One quota-counting render per SignatureRequest.

Sign-request counter. The per-month sign_requests_count only increments after the WHOLE workflow succeeded: render OK, PDF stored, recipient email accepted, row persisted. A render failure, storage failure, or SMTP failure returns the appropriate error without consuming any quota or balance.

Renderer. Always uses plumav1 — the only engine that supports signature placement. The renderer field is not accepted on this endpoint.

Error responses. Failures are returned as JSON with a stable error code and a human-readable detail message. No stack traces. When the renderer surfaces per-field transform errors, they're forwarded under a fields array — same shape /generate uses for transform_failed.

Create async render job

Queue a large batch (up to 10,000 items). Returns immediately with a jobId; poll GET /jobs/:id for status + downloadUrl.

Response

{
  "jobId": "uuid",
  "status": "pending",
  "itemsTotal": 2
}

Per-item filename follows the same rules as /bulk: optional, defaults to <template-slug>_NNNN.pdf, duplicates get a -N suffix. Legacy alias: POST /api/v1/:workspace/templates/:id/bulk-job (also /bulk-jobs).

ignoreErrors persists on the job row so a stale-job recovery run after a builder restart honours the same contract. Default false; on a transform failure the job's status flips to failed and the error field carries a single sentence naming the template, item, and offending field — e.g. Transform failed for template "Invoice template" on item 4: "Customer name": Cannot read properties of null (reading 'name').

List render jobs

Workspace-scoped job list, newest first.

Response

{
  "jobs": [
    {
      "id": "…",
      "status": "completed",
      "itemsTotal": 100,
      "itemsDone": 100
    }
  ],
  "nextCursor": null
}

Get one job

Once status === completed, the response includes a downloadUrl valid for 10 minutes. Once status === expired, the row is preserved but the ZIP is gone (re-create the job to regenerate).

Response

{
  "id": "…",
  "status": "completed",
  "itemsTotal": 100,
  "itemsDone": 100,
  "downloadUrl": "https://…"
}