Verified documents

Turn on verified documents for a template and every real render of it issues a document: a record with its own public verify page at https://bannx.com/verify/<id>. You put that link in a QR code on the design. Whoever holds the printed certificate, the card or the badge can show it, and whoever scans the code sees whether it is genuine, who it was issued to and who issued it.

You don't build or host anything. bannx keeps the record, serves the page, and lets you revoke a document later.

There are three kinds:

KindForPhoto on the verify page
CertificateCourse completion, awards, training and CPD, diplomasNo
ID cardMembership, staff, student and volunteer cardsYes, optional
Event badgeConference badges and name tagsYes, optional

Issuing documents is free. Each render costs its normal credits.

Turn it on

Open the template in the editor, then Template settings → Verified documents:

SettingWhat it does
Issue verified documentsThe switch. Off, renders issue nothing.
KindCertificate, ID card or Event badge.
TitleShown at the top of the verify page, e.g. "Certificate of completion" (up to 80 characters). Without one, the page shows the kind.
Public fieldsThe variables the verify page shows, each with a label: recipient as "Name", course as "Course". Up to 12. Only these are public; see Privacy.
PhotoID cards and badges: an image variable holding the holder's photo.
ExpiryNone, a date variable (2027-06-30, valid to the end of that day, UTC; or a full ISO date-time), or a number of days after issue (1 to 3650).
Subject keyA variable that identifies the holder, such as email or memberId. It decides when a render reuses or replaces a document; see Renewals and reuse.

Every variable the setting names must be a variable the template declares, and the photo must be an image variable. Otherwise saving the setting is refused with the problem named.

Add a QR code layer (Insert → QR code) and set its Value to:

{{ credential.url }}

Every issued document then prints its own verify link. Two more values are there for the design:

ValueExampleUse it for
{{ credential.url }}https://bannx.com/verify/4kT9…The QR code's value, or a printed link
{{ credential.code }}4KT9XW2P8 characters to print beside the QR, so a person can quote the document
{{ credential.id }}4kT9xw2pQ… (22 letters and digits)The full public id, for the verify API

credential is a reserved name, like brand. A credential value sent in a request's variables is ignored, so nobody can print another document's link into yours. If the template itself declares a variable called credential, that variable wins and the QR will not point at a verify page: rename it.

In the editor canvas, previews and anywhere else nothing is issued, these values are samples: {{ credential.url }} is https://bannx.com/verify/sample, an explanatory page, so the QR still lays out and scans.

Publish again

API renders use the published version of a template, and so does its setting. After you turn verified documents on (or change the setting), publish the template again. Until then, renders from the API and MCP issue nothing, unless they pass "draft": true. A template that was never published uses its draft either way. Bulk runs read the template as it is now.

What issues a document

A document is issued only when a real file goes out:

Issues a documentDoes not (sample values)
POST /api/v1/templates/:id/render and the API-key GET renderThe editor canvas and previews
template_render over MCPThumbnails and OG images
Bulk runs: one per rowSigned image URLs (/r/…)
Download on the template's pageEmbeds and public forms
Zapier and n8n renders, which go through the Render APIDownloads of someone else's public template from the gallery

Workflows have no render step of their own; a workflow issues a document when it calls the Render API.

A render that fails issues nothing. A bulk row that fails issues nothing, and a bulk job whose ZIP or PDF never gets delivered issues nothing for any row. Every API-key GET render issues (and is charged), so don't put one in an <img> tag that loads on every view. A POST retried with the same Idempotency-Key returns the first answer, with the same document.

When the space's documents are suspended, renders of templates with verified documents on are refused with 403 CREDENTIALS_SUSPENDED. Templates without them keep rendering.

Renewals and reuse

Without a subject key, every render issues a new document.

With a subject key, bannx keeps one current document per holder of a template:

  • Same holder, same public fields, same photo and expiry, still valid: the render reuses the existing document. Same id, same verify link, reused: true in the response. Re-sending a lost certificate does not create a second one.
  • Same holder, something changed (a corrected name, a new grade, a new expiry date): a new document is issued. The old one becomes Replaced and its page links to the new one. This happens only once the new file is rendered, so a failed renewal never invalidates the old document.
  • Same holder, document expired: a new document is issued with a new expiry. This is how you renew a yearly membership card: render it again.

With an expiry of a number of days, a reused document keeps its first expiry date. Re-rendering does not extend it; a render after it expires issues the renewal.

In a bulk run, a _credentialKey column (or JSON key) sets each row's holder and overrides the subject key variable. See Bulk.

The verify page

Scanning the QR code opens the document's page. It is made for a phone, and it is not indexed by search engines. It shows:

  • the status, in a banner:
StatusBannerMeaning
validValid documentIssued through bannx and not revoked.
expiredExpiredGenuine, but past its expiry date.
revokedRevokedThe issuer withdrew it. The reason they gave is shown.
replacedReplaced by a newer documentThe issuer issued an updated version; the page links to it.
suspendedIssuer suspendedbannx suspended the issuer. The page shows no fields, photo or preview.
  • the title or kind, the public fields, the photo (ID cards and badges), and the issue and expiry dates;
  • the issuer: your space's name and logo, with Verified issuer: yourdomain.com when you have verified a domain, else "bannx has not confirmed this issuer's identity";
  • the document as it was rendered, for PNG and WebP renders;
  • a document fingerprint: the SHA-256 of the rendered file (the first page for a multi-page still render). Someone holding the file can compare it, for example with shasum -a 256 certificate.pdf. When a reused document is rendered again, the fingerprint follows the latest file;
  • Report this document, see Reports and suspension.

An unknown, mistyped or deleted id shows "not found". A page changes within about 30 seconds of a revoke.

https://bannx.com/verify/sample is a made-up certificate that explains the page. Sample QR codes point there.

Manage documents

Every document your space issued is on the Verified documents page in your space's sidebar. Search by a public field or the document's id, see its status and any reports, and:

  • Revoke a document. Its page stays up with the status Revoked and the reason you give (up to 200 characters). The reason is public, so keep it factual: "Issued in error", "Membership cancelled".
  • Delete a document. Its page then shows "not found", exactly like an id that never existed. Use it when the holder asks for their data to be removed.
  • Export CSV of the list as filtered.

A space that still has valid documents cannot be deleted, because every printed QR code would then point at "not found". Revoke or delete them first.

Verified issuer

Anyone can name a space "Acme University". To show people that a document really comes from acme.edu, prove you control the domain:

  1. On the Verified documents page, add your domain. bannx shows a DNS record for it.
  2. Add a TXT record at your DNS provider:
_bannx-verify.acme.edu   TXT   bannx-verify=<token>
  1. Click Verify. Once the record is found, every verify page of your space shows Verified issuer: acme.edu.

DNS changes can take a while to appear. bannx re-checks verified domains about once a week; if the record is gone, the badge comes off. A domain verified by one space cannot be verified by another.

Reports and suspension

Anyone on a verify page can report a document: it looks fake, it belongs to someone else, or the issuer is impersonating an organisation. A report can carry a message and an email for a reply. Nothing in a report is shown on the page.

You see the report count on your documents. Reports also reach bannx. If a space issues fake documents or impersonates an organisation, bannx can suspend its documents: every verify page of the space then says Issuer suspended and withholds its fields, and the space cannot issue new documents. To appeal, write to [email protected] from the space owner's account.

Privacy

What becomes public is what you choose:

  • Public fields only. The verify page and the API return the public fields you picked, frozen at the moment the document was issued, plus the title, dates, photo and issuer. No other variable, nothing from the design and nothing about your space beyond its name, logo and verified domain is ever shown.
  • Subject keys are not stored. bannx keeps a one-way hash of the subject key, enough to recognise the same holder again. The email or member number itself is not kept and never shown, unless you also chose it as a public field.
  • Photos come from your space. The photo is shown only when its URL is a file in your space's media library (an upload or a generated image). A link to another site is left off the page.
  • Ids are not guessable. A document id is 128 random bits. Ids are not numbered, and an unknown id gets the same "not found" as a deleted one.
  • Deleting removes it. A deleted document is gone from its page and from the API.

Pick public fields that let someone check the document without exposing more than they need: a name and a course, not a date of birth and a home address.

API

The render response

When the template has verified documents on, a render's JSON carries the document it issued:

{
  "ok": true,
  "templateId": "TEMPLATE_ID",
  "format": "pdf",
  "url": "https://…/render.pdf",
  "credential": {
    "id": "4kT9xw2pQm7LbR1sVd8eZc",
    "url": "https://bannx.com/verify/4kT9xw2pQm7LbR1sVd8eZc",
    "code": "4KT9XW2P",
    "reused": false
  }
}

reused is true when an unchanged document of the same holder was rendered again. A pages: "all" render issues one document for the whole set. Raw responses (raw: true, or the default binary GET render) have no JSON body, so the document rides as headers: x-credential-id and x-credential-url. MCP template_render returns the same credential object.

Store credential.id beside your own record of the person if you will want to find the document later.

Bulk

A bulk run issues one document per rendered row. Give each row its holder with the reserved _credentialKey key (a CSV column or a JSON key). It never reaches the template as a variable, and it overrides the template's subject key variable:

curl -X POST https://bannx.com/api/v1/templates/TEMPLATE_ID/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "format": "pdf",
    "rows": [
      { "id": "ada",  "recipient": "Ada Lovelace", "course": "Data Foundations", "_credentialKey": "[email protected]" },
      { "id": "alan", "recipient": "Alan Turing",  "course": "Data Foundations", "_credentialKey": "[email protected]" }
    ]
  }'

Without _credentialKey, a row's holder comes from the subject key variable, as for a single render. The finished job lists the documents under credentials, one entry per rendered row. row is the row's id key, else its position counted from 1:

{
  "jobId": "…",
  "state": "completed",
  "zipUrl": "https://…/renders.zip",
  "credentials": [
    { "row": "ada",  "credentialId": "4kT9xw2pQm7LbR1sVd8eZc", "url": "https://bannx.com/verify/4kT9xw2pQm7LbR1sVd8eZc", "code": "4KT9XW2P", "reused": false },
    { "row": "alan", "credentialId": "9fQ2mR7tLx1KcW4pZb6nYa", "url": "https://bannx.com/verify/9fQ2mR7tLx1KcW4pZb6nYa", "code": "9FQ2MR7T", "reused": false }
  ]
}

Documents of a bulk run become valid when the ZIP or PDF is delivered. A row that failed is in errors and has no document.

Check a document from code

GET /api/v1/credentials/:id is the verify page as JSON. No authentication: the id is the key.

curl https://bannx.com/api/v1/credentials/4kT9xw2pQm7LbR1sVd8eZc
{
  "status": "valid",
  "kind": "certificate",
  "title": "Certificate of completion",
  "fields": [
    { "label": "Name", "value": "Ada Lovelace" },
    { "label": "Course", "value": "Data Foundations" }
  ],
  "photoUrl": null,
  "issuedAt": "2026-11-20T09:12:44.000Z",
  "expiresAt": null,
  "revokedAt": null,
  "revokedReason": null,
  "replacedBy": null,
  "fileSha256": "9b74c9897bac770ffc029102a200c5de…",
  "previewUrl": null,
  "issuer": { "name": "Northfield Learning Centre", "logoUrl": "https://…/logo.png", "verifiedDomain": "northfield.edu" }
}
FieldNotes
statusvalid, expired, revoked, replaced or suspended, worked out when you ask.
kindcertificate, idcard or badge.
fieldsThe public fields as { label, value }, in your order. Empty while the issuer is suspended.
revokedAt, revokedReasonSet when status is revoked.
replacedByThe id of the newer document, when status is replaced.
fileSha256SHA-256 (hex) of the rendered file.
previewUrlThe rendered image, for PNG and WebP documents.
issuer.verifiedDomainSet only while the issuer has a verified domain; null means bannx has not confirmed who the issuer is.

An unknown or deleted id is 404 CREDENTIAL_NOT_FOUND. Lookups are limited to 60 a minute per IP address (429 RATE_LIMITED), and an answer may be cached for 30 seconds.

POST /api/v1/credentials/:id/report files a report, also without authentication: { "reason": "fake" | "wrong_person" | "impersonation" | "other", "message"?, "email"? } (message up to 1000 characters). At most 5 reports an hour per address, and one per document per day.

Both routes are in the API reference.

From an agent (MCP)

An agent turns the setting on with template_apply_ops and settings:

{
  "templateId": "TEMPLATE_ID",
  "settings": {
    "credentials": {
      "enabled": true,
      "kind": "certificate",
      "title": "Certificate of completion",
      "publicFields": [
        { "variable": "recipient", "label": "Name" },
        { "variable": "course", "label": "Course" }
      ],
      "subjectKeyVariable": "email",
      "expiresInDays": 365
    }
  }
}

photoVariable (ID cards and badges, an image variable) and expiresVariable (a date variable, instead of expiresInDays) complete the setting; "credentials": null clears it. Bind a QR layer's payload to {{ credential.url }}, publish the template, then call template_render.

Errors

CodeStatusWhen
CREDENTIALS_SUSPENDED403The space's documents are suspended, so a template with verified documents on cannot render.
CREDENTIAL_NOT_FOUND404No document with that id, or it was deleted.
VALIDATION422The setting names a variable the template does not declare, or a render's expiry variable is not a date (fieldErrors names the variable).

The full list is on the Errors page.

  • Rendering API: the render request and response, bulk runs, credits.
  • Templates: QR code layers and publishing.
  • Variables: declaring the variables the setting names.
  • Errors: every error code.