Overview
Passinstance provides native support for creating and configuring pass templates programmatically via JSON payloads. Rather than configuring visual layouts, barcode encodings, colors, and dynamic attributes manually in the Visual Editor, developers and platform integrators can submit complete template schemas to the REST API (POST /api/v1/templates or POST /api/v1/templates/import).
The backend template engine processes incoming JSON through the normalization and validation pipeline with automatic schema normalization, validating pass geometries, enforcing Apple Wallet and Google Wallet color invariants, and registering custom properties.
System Architecture: JSON Template Ingestion Pipeline
JSON Schema Specification for request payload
A valid JSON template definition must conform to the request payload structure accepted by POST /api/v1/templates:
| Top-Level Property | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Human-readable name of the template (e.g., "Artisan Coffee Club"). Max 255 chars. |
kind | PassKind | Yes | Pass type geometry: storeCard, coupon, eventTicket, boardingPass, generic, or posterGeneric. |
organizationName | string | Yes | Organization name rendered on Apple and Google Wallet passes. |
description | string | Yes | Accessible description of the pass required by Apple PassKit. |
status | template status | No | Initial status. Defaults to PUBLISHED upon programmatic creation. |
colors | request payload | No | Object containing backgroundColor, foregroundColor, labelColor, and stripColor. |
barcode | request payload | No | Barcode configuration (format, messageEncoding, altText, addSecurityAnimation). |
fields | request payload | No | Field collections grouped by zone (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields). |
locations | request payload[] | No | Array of up to 10 GPS coordinates triggering lockscreen notifications. |
beacons | request payload[] | No | Array of up to 10 Bluetooth iBeacons for indoor proximity detection. |
expiration | request payload | No | Pass validity and expiration strategy (none, fixed, or duration). |
The colors Sub-Object
Apple Wallet strictly mandates CSS RGB format (rgb(r, g, b)) for colors and rejects hex values or alpha channels. When importing JSON via Passinstance, the normalizer accepts either hex or RGB syntax and serializes the exact required format for each wallet provider:
{
"backgroundColor": "rgb(24, 24, 27)",
"foregroundColor": "rgb(255, 255, 255)",
"labelColor": "rgb(161, 161, 170)",
"stripColor": "rgb(255, 255, 255)"
}
The barcode Sub-Object
{
"format": "PKBarcodeFormatQR",
"messageEncoding": "UTF_8",
"altText": "{cardNumber}",
"addSecurityAnimation": true
}
Supported formats include: PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec, PKBarcodeFormatCode128, PKBarcodeFormatCode39, PKBarcodeFormatCodabar, PKBarcodeFormatEAN13, PKBarcodeFormatI2of5, and PKBarcodeFormatNone.
Validation & Normalization Rules (normalizeTemplateImport)
When raw JSON is submitted to POST /api/v1/templates/import, the backend executes normalizeTemplateImport:
-
1
Pass Kind Normalization: Translates legacy or alternative style names (such as
store_card->storeCard,event_ticket->eventTicket,boarding_pass->boardingPass). -
2
Transit Type Detection: For
boardingPasspasses, mapstransitTypestrings (PKTransitTypeAir,PKTransitTypeTrain,PKTransitTypeBus,PKTransitTypeBoat,PKTransitTypeGeneric). -
3
Field Placement Clamping: Validates that fields placed in
auxiliaryFieldscomply with pass kind rules (e.g.,couponpasses reject auxiliary fields and redirect them tosecondaryFields). -
4
Barcode Fallback Assignment: If a 1D barcode (
Code 128,Code 39,EAN-13) is configured without a fallback, the normalizer automatically assignsPKBarcodeFormatQRas the Apple Watch fallback barcode. -
5
System Key Stripping: Silently strips dangerous tenant or internal system keys (
id,customerId,tenantId,certificateId,version,status,passes,createdAt,updatedAt,archivedAt).
API Reference: Creating a Template from JSON
HTTP Request
/api/v1/templates
{
"name": "Acme VIP Club",
"kind": "storeCard",
"organizationName": "Acme Retail Group",
"description": "Acme VIP Rewards Card",
"colors": {
"backgroundColor": "rgb(15, 23, 42)",
"foregroundColor": "rgb(248, 250, 252)",
"labelColor": "rgb(148, 163, 184)"
},
"barcode": {
"format": "PKBarcodeFormatQR",
"messageEncoding": "UTF_8",
"altText": "{externalId}"
},
"fields": {
"headerFields": [
{
"key": "tier",
"label": "TIER",
"value": "VIP Platinum",
"textAlignment": "PKTextAlignmentRight"
}
],
"primaryFields": [
{
"key": "holder",
"label": "MEMBER",
"value": "{firstName} {lastName}"
}
],
"secondaryFields": [
{
"key": "balance",
"label": "POINTS",
"value": "{pointsBalance}",
"numberStyle": "PKNumberStyleDecimal"
}
],
"backFields": [
{
"key": "terms",
"label": "TERMS & CONDITIONS",
"value": "Valid at all participating Acme stores. Points expire after 12 months of inactivity."
}
]
},
"locations": [
{
"latitude": 40.712776,
"longitude": -74.005974,
"maxDistance": 250,
"relevantText": "Welcome to Acme Flagship! Scan your pass at checkout."
}
]
}
HTTP Response (201 Created)
{
"success": true,
"data": {
"id": "tmpl_01h9x8k7m6n5p4q3r2s1",
"groupId": "grp_01h9x8k7m6n5p4q3r2s1",
"name": "Acme VIP Club",
"kind": "storeCard",
"status": "PUBLISHED",
"versionNumber": 1,
"rowKind": "PRODUCTION",
"createdAt": "2026-11-16T20:30:00.000Z",
"updatedAt": "2026-11-16T20:30:00.000Z"
},
"statusCode": 201
}
Common JSON Ingestion Errors & Resolutions
| HTTP Status | Error Message | Root Cause & Resolution |
|---|---|---|
| 400 Bad Request | Template icon is required | When creating templates via JSON without existing seed assets, an icon asset or data URI must be provided, or assign an existing workspace asset ID. |
| 400 Bad Request | Invalid color format: must be rgb(r, g, b) | A color string contained alpha channels (rgba(0,0,0,0.5)) or malformed syntax. Supply standard rgb(r, g, b) or 6-digit hex (#RRGGBB). |
| 400 Bad Request | Auxiliary fields are not supported on coupon passes | The payload submitted auxiliaryFields for a coupon pass kind. Move auxiliary fields into secondaryFields or change the pass kind to storeCard. |
| 413 Payload Too Large | Import payload exceeds 5MB limit | The JSON payload exceeded maximum upload size limit (5 MB), usually due to embedded base64 image strings. Upload images via the image asset endpoint instead. |
Continue to Import from Apple Pass Designer to import existing .passdesign projects, or explore Dynamic Fields & Personalization to configure attribute variables.
