Skip to content
Help Center Guide · Pass Templates
4 min readVerified 2026-11-16

Create a Template from JSON

Import and provision pass templates programmatically using JSON definitions, schema validation, and normalization rules.

In This Guide

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

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
JSON TEMPLATE INGESTION PIPELINE
STAGE 01 EXTERNAL CLIENT / AUTOMATION SCRIPT
Submits JSON document via POST/api/v1/templates or POST.../templates/import
Encodes pass kinds, colors, field layout zones, barcodes, and relevancy rules
STAGE 02 TEMPLATE INGESTION & NORMALIZATION PIPELINE
normalizeTemplateImport (template-import-export.util.ts)
1
Payload Size Guard: Enforces maximum upload size limit = 5 * 1024 * 1024 (5 MB)
2
Security Sanitization: Strips system keys (id, customerId, version, etc.)
3
Prototype Pollution Check: Rejects __proto__, constructor, prototype
4
Color Normalization: Converts hex / RGB strings to canonical rgb(r, g, b)
5
Barcode & Transit Mapping: Translates Apple PassKit enums to canonical formats
STAGE 03 DATABASE RECONCILER (Template Engine)
Persists Template entity with status: PUBLISHED
Creates relational entities: Field[], Color, Barcode, Location[]
Initializes database high-speed search index on Pass.attributes for declared properties
STAGE 04A APPLE WALLET COMPILATION
Generates base pass.json dictionary and packages default seed icons/images
STAGE 04B GOOGLE WALLET CLASS CREATION
Creates Google Wallet Class via SDK (e.g., LoyaltyClass, EventClass)

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 PropertyTypeRequiredDescription
namestringYesHuman-readable name of the template (e.g., "Artisan Coffee Club"). Max 255 chars.
kindPassKindYesPass type geometry: storeCard, coupon, eventTicket, boardingPass, generic, or posterGeneric.
organizationNamestringYesOrganization name rendered on Apple and Google Wallet passes.
descriptionstringYesAccessible description of the pass required by Apple PassKit.
statustemplate statusNoInitial status. Defaults to PUBLISHED upon programmatic creation.
colorsrequest payloadNoObject containing backgroundColor, foregroundColor, labelColor, and stripColor.
barcoderequest payloadNoBarcode configuration (format, messageEncoding, altText, addSecurityAnimation).
fieldsrequest payloadNoField collections grouped by zone (headerFields, primaryFields, secondaryFields, auxiliaryFields, backFields, additionalInfoFields).
locationsrequest payload[]NoArray of up to 10 GPS coordinates triggering lockscreen notifications.
beaconsrequest payload[]NoArray of up to 10 Bluetooth iBeacons for indoor proximity detection.
expirationrequest payloadNoPass 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:

JSON
{
  "backgroundColor": "rgb(24, 24, 27)",
  "foregroundColor": "rgb(255, 255, 255)",
  "labelColor": "rgb(161, 161, 170)",
  "stripColor": "rgb(255, 255, 255)"
}

The barcode Sub-Object

JSON
{
  "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. 1
    Pass Kind Normalization: Translates legacy or alternative style names (such as store_card -> storeCard, event_ticket -> eventTicket, boarding_pass -> boardingPass).
  2. 2
    Transit Type Detection: For boardingPass passes, maps transitType strings (PKTransitTypeAir, PKTransitTypeTrain, PKTransitTypeBus, PKTransitTypeBoat, PKTransitTypeGeneric).
  3. 3
    Field Placement Clamping: Validates that fields placed in auxiliaryFields comply with pass kind rules (e.g., coupon passes reject auxiliary fields and redirect them to secondaryFields).
  4. 4
    Barcode Fallback Assignment: If a 1D barcode (Code 128, Code 39, EAN-13) is configured without a fallback, the normalizer automatically assigns PKBarcodeFormatQR as the Apple Watch fallback barcode.
  5. 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

POST /api/v1/templates
Headers
X-API-Key <API_KEY>
Content-Type application/json
JSON
{
  "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)

JSON
{
  "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 StatusError MessageRoot Cause & Resolution
400 Bad RequestTemplate icon is requiredWhen 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 RequestInvalid 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 RequestAuxiliary fields are not supported on coupon passesThe payload submitted auxiliaryFields for a coupon pass kind. Move auxiliary fields into secondaryFields or change the pass kind to storeCard.
413 Payload Too LargeImport payload exceeds 5MB limitThe 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.

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.