Create a credential
Templates, versions and fields — defining what a credential says before anybody holds one.
Before a credential can be issued, something has to say what it contains. For wallet credentials that is a template; for diplomas and certificates it is an achievement. Both work the same way: a definition with versions, where publishing a version freezes what it means for everyone who receives it.
POST/v1/templates
Creates the template and its first draft version.
POST /v1/templates
curl -X POST https://api.nomi-tech.com/v1/templates \
-H "Authorization: Bearer nomi_sk_live_EXAMPLE" \
-H "Content-Type: application/json" \
-d '{
"key": "membership_platinum",
"name": "Platinum membership",
"kind": "membership",
"definition": {
"fields": [
{ "key": "tier", "label": "Tier", "source": "attributes.tier", "placement": "primary" },
{ "key": "member", "label": "Member", "source": "displayName", "placement": "secondary" },
{ "key": "since", "label": "Since", "source": "attributes.memberSince", "placement": "auxiliary", "format": "date" }
],
"style": {
"backgroundColor": "#0A0A0A",
"foregroundColor": "#FFFFFF",
"labelColor": "#DFFF00"
},
"barcode": { "format": "qr", "source": "serial" },
"validity": { "duration": "P1Y" }
}
}'Fields come from the subject
Each field names a source — a path on the subject, such as displayName or attributes.tier. That is what makes a credential follow a record instead of freezing a copy of it: correct somebody's tier on the subject and every credential of theirs shows the new one.
| Property | Values | Notes |
|---|---|---|
kind | membership, employee_id, student_id, loyalty, event, benefit, access, generic | What sort of credential this is. Drives the wallet's own pass style. |
placement | header, primary, secondary, auxiliary, back | Where the field sits on the pass. |
format | text, date, number, currency | How the value is rendered, in the holder's locale. |
barcode.format | qr, code128, pdf417, aztec | What the scanner at the door reads. |
validity.duration | An ISO-8601 duration, e.g. P1Y | How long a credential issued from this version lasts. |
Versions
A template is created as a draft. POST /v1/templates/{id}/versions/{versionId}/publish is what makes it issuable, and it is a separate act on purpose: what a published version says is what a credential will show for years, so nothing publishes it by accident. Editing a published version means creating a new one — credentials already issued keep the version they were issued against.