---
title: Verified documents | Bannx
description: Give every certificate, ID card or event badge you render its own public verify page. A QR code on the document opens it, and anyone can check that it is genuine, still valid and issued by you.
source: https://bannx.com/docs/verified-documents
---

Copy page

# 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:

| Kind | For | Photo on the verify page |
| --- | --- | --- |
| **Certificate** | Course completion, awards, training and CPD, diplomas | No |
| **ID card** | Membership, staff, student and volunteer cards | Yes, optional |
| **Event badge** | Conference badges and name tags | Yes, optional |

Issuing documents is free. Each render costs its normal [credits](https://bannx.com/docs/rendering#credits).

## [Turn it on](https://bannx.com/docs/verified-documents#turn-it-on)

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

| Setting | What it does |
| --- | --- |
| **Issue verified documents** | The switch. Off, renders issue nothing. |
| **Kind** | Certificate, ID card or Event badge. |
| **Title** | Shown at the top of the verify page, e.g. "Certificate of completion" (up to 80 characters). Without one, the page shows the kind. |
| **Public fields** | The variables the verify page shows, each with a label: `recipient` as "Name", `course` as "Course". Up to 12. Only these are public; see [Privacy](https://bannx.com/docs/verified-documents#privacy). |
| **Photo** | ID cards and badges: an image variable holding the holder's photo. |
| **Expiry** | None, 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 key** | A variable that identifies the holder, such as `email` or `memberId`. It decides when a render reuses or replaces a document; see [Renewals and reuse](https://bannx.com/docs/verified-documents#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.

### [Put the link in a QR code](https://bannx.com/docs/verified-documents#put-the-link-in-a-qr-code)

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

```text
{{ credential.url }}
```

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

| Value | Example | Use it for |
| --- | --- | --- |
| `{{ credential.url }}` | `https://bannx.com/verify/4kT9…` | The QR code's value, or a printed link |
| `{{ credential.code }}` | `4KT9XW2P` | 8 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](https://bannx.com/docs/verified-documents#check-a-document-from-code) |

`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](https://bannx.com/docs/verified-documents#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](https://bannx.com/docs/verified-documents#what-issues-a-document)

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

| Issues a document | Does not (sample values) |
| --- | --- |
| `POST /api/v1/templates/:id/render` and the API-key `GET` render | The editor canvas and previews |
| `template_render` over [MCP](https://bannx.com/docs/integrations/mcp) | Thumbnails and OG images |
| [Bulk runs](https://bannx.com/docs/rendering#bulk-rendering): one per row | [Signed image URLs](https://bannx.com/docs/rendering#signed-image-urls) (`/r/…`) |
| **Download** on the template's page | Embeds and public forms |
| [Zapier](https://bannx.com/docs/integrations/zapier) and [n8n](https://bannx.com/docs/integrations/n8n) renders, which go through the Render API | Downloads 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`](https://bannx.com/docs/rendering#retrying-safely) returns the first answer, with the same document.

When the space's documents are [suspended](https://bannx.com/docs/verified-documents#reports-and-suspension), renders of templates with verified documents on are refused with `403` `CREDENTIALS_SUSPENDED`. Templates without them keep rendering.

## [Renewals and reuse](https://bannx.com/docs/verified-documents#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](https://bannx.com/docs/verified-documents#bulk).

## [The verify page](https://bannx.com/docs/verified-documents#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:

| Status | Banner | Meaning |
| --- | --- | --- |
| `valid` | Valid document | Issued through bannx and not revoked. |
| `expired` | Expired | Genuine, but past its expiry date. |
| `revoked` | Revoked | The issuer withdrew it. The reason they gave is shown. |
| `replaced` | Replaced by a newer document | The issuer issued an updated version; the page links to it. |
| `suspended` | Issuer suspended | bannx 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](https://bannx.com/docs/verified-documents#verified-issuer), 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](https://bannx.com/docs/verified-documents#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](https://bannx.com/docs/verified-documents#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](https://bannx.com/docs/verified-documents#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:

```text
_bannx-verify.acme.edu   TXT   bannx-verify=<token>
```

3. 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](https://bannx.com/docs/verified-documents#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]](https://bannx.com/cdn-cgi/l/email-protection#9ffcf0f1ebfefcebdffdfef1f1e7b1fcf0f2) from the space owner's account.

## [Privacy](https://bannx.com/docs/verified-documents#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](https://bannx.com/docs/verified-documents#api)

### [The render response](https://bannx.com/docs/verified-documents#the-render-response)

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

```json
{
  "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"`](https://bannx.com/docs/rendering#render-every-page-carousels) 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](https://bannx.com/docs/verified-documents#bulk)

A [bulk run](https://bannx.com/docs/rendering#bulk-rendering) 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:

```bash
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:

```json
{
  "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](https://bannx.com/docs/verified-documents#check-a-document-from-code)

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

```bash
curl https://bannx.com/api/v1/credentials/4kT9xw2pQm7LbR1sVd8eZc
```

```json
{
  "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" }
}
```

| Field | Notes |
| --- | --- |
| `status` | `valid`, `expired`, `revoked`, `replaced` or `suspended`, worked out when you ask. |
| `kind` | `certificate`, `idcard` or `badge`. |
| `fields` | The public fields as `{ label, value }`, in your order. Empty while the issuer is suspended. |
| `revokedAt`, `revokedReason` | Set when `status` is `revoked`. |
| `replacedBy` | The id of the newer document, when `status` is `replaced`. |
| `fileSha256` | SHA-256 (hex) of the rendered file. |
| `previewUrl` | The rendered image, for PNG and WebP documents. |
| `issuer.verifiedDomain` | Set only while the issuer has a [verified domain](https://bannx.com/docs/verified-documents#verified-issuer); `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](https://bannx.com/docs/api).

### [From an agent (MCP)](https://bannx.com/docs/verified-documents#from-an-agent-mcp)

An agent turns the setting on with `template_apply_ops` and `settings`:

```json
{
  "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](https://bannx.com/docs/verified-documents#errors)

| Code | Status | When |
| --- | --- | --- |
| `CREDENTIALS_SUSPENDED` | 403 | The space's documents are suspended, so a template with verified documents on cannot render. |
| `CREDENTIAL_NOT_FOUND` | 404 | No document with that id, or it was deleted. |
| `VALIDATION` | 422 | The 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](https://bannx.com/docs/errors) page.

## [Related docs](https://bannx.com/docs/verified-documents#related-docs)

- [Rendering API](https://bannx.com/docs/rendering): the render request and response, bulk runs, credits.
- [Templates](https://bannx.com/docs/templates): QR code layers and publishing.
- [Variables](https://bannx.com/docs/variables): declaring the variables the setting names.
- [Errors](https://bannx.com/docs/errors): every error code.