Bulk distribution

For graduations, workforce certifications, or any cohort issuance, the Distributions wizard lets you upload a CSV of recipients and mint credentials in batches.

A distribution is a campaign (e.g. “Spring 2026 BSc cohort”). It groups together one or more batches, each of which is a CSV upload that produces one credential offer per row. Splitting into multiple batches is useful when you’re staging issuance over time (e.g. rolling out by faculty) — the distribution lives on as the parent grouping.

Prerequisites

• An active credential configuration (see Creating your first credential config).
• Quota — bulk distributions count against your agreement’s credential meter for the current billing period; units are consumed as recipients claim, not when you upload the batch. Check Usage (portal sidebar) if you’re issuing a large batch.

Step 1 — Create the distribution

Portal sidebar → Distributions → New Distribution. Pick the credential configuration the distribution will issue, name the distribution, and create it.

The distribution starts empty. From the distribution detail page, click New Batch.

Step 2 — The wizard

Configure

• Credential configuration — locked to the parent distribution’s config.
• Expiry date — when the offers expire (not the credentials). Recipients who haven’t claimed by this date will see “offer expired” and you’ll need to issue them a new one.
• Notification subject + body — the email recipients receive. Pre-filled from the credential config defaults; override per-batch if you want.

Upload

Drop or browse for a CSV. Required columns:

• email — the recipient’s address. Used for the notification.

The remaining columns map to the claim placeholders in your credential configuration. For example, if the configuration’s claims template uses {{given_name}} and {{family_name}}, the CSV needs columns named given_name and family_name.

The wizard shows the expected column hints based on the parent configuration. Extra columns are ignored; missing required columns surface as validation errors.

Use the Download sample CSV link on the upload step to get a ready-made template for the selected configuration — the exact expected headers plus one example row to replace with your data.

Review

Cyfher validates every row against the credential configuration’s claims schema. The review page shows:

• Total recipient count.
• Any rows that failed validation (with the specific field error).
• The first few rows as a preview.

If anything fails validation, fix the CSV and re-upload — nothing has been committed yet. When the preview is clean, click Commit Batch.

Step 3 — Commit

Committing locks in the recipient list. Cyfher pre-mints the offer state for each row but does not yet send notifications. You can:

• Distribute — sends notification emails to every recipient.
• Pause / Resume — useful for staged rollouts; paused batches don’t send further notifications.
• Cancel — voids unclaimed offers in the batch. Already-claimed credentials are unaffected.

Step 4 — Distribute

Click Distribute. Cyfher sends notification emails to each recipient. Each email contains a one-time claim link that opens the holder’s wallet to redeem the credential.

The batch detail page shows a live stats grid:

• Total — recipients in the batch.
• Claimed — credential issued to the holder’s wallet.
• Pending — offers not yet claimed or expired (total minus claimed minus expired).
• Expired — offer expired before the holder claimed.

The per-offer table below the grid lists each recipient’s status alongside a Notified column (the date the notification email was dispatched) and a Claimed column. There is no open/click tracking.

CSV format example

email,given_name,family_name,awarded_at
alice@example.com,Alice,Doe,2026-05-15
bob@example.com,Bob,Smith,2026-05-15

Column headers must exactly match the flat claim keys in your credential configuration’s claims_schema (plus the required email column). Cyfher reads the columns verbatim — there is no nested/dot-notation expansion. Any header that doesn’t match a schema key (or email) is reported as an “Unrecognized columns (will be ignored)” warning and dropped from the offer claims.

API equivalent

The wizard wraps the Distributions, Batches, and Offers APIs. See Issuing a credential for the API call sequence — bulk distribution uses the same endpoints, just with many rows in the offers array (or paginated via POST /api/t/:slug/batches/:id/offers multiple times).