Create Dynamic Pass Template API

Overview

The Create Dynamic Pass Template API allows you to create reusable templates for generating multiple passes with dynamic content. Templates define the structure and design of passes, while dynamic fields can be populated with different data for each individual pass created from the template.

🔗 Automatic User Group Creation

When this API is called, it automatically creates a linked user group in the Manage Users section of your dashboard. This group is used to organize and manage customers associated with passes created from this template. The response will include both the dynamicPassId and the groupIdof the created user group.

Base URL

https://app.addtowallet.co

POST/api/dynamicPass/template/

Authentication

All API requests must include your API key in the request headers:

"apikey": "your-api-key-here"

Request Parameters

The API accepts the following parameters in the request body JSON:

Request Parameters

Name	Type	Required	Description
name	`string`	Yes	A descriptive name for the template (max 100 characters)
templateData	`object`	Yes	The pass template configuration including design elements and dynamic field placeholders
dynamicFields	`array<string>`	Yes	An array of field names that can be dynamically populated when creating passes from this template
description	`string`	No	A detailed description of the template's purpose and usage

Template Data Structure

The templateData object follows the same structure as the Create Pass API, but supports dynamic field placeholders using double curly braces syntax: {fieldName}

Access code protection

You may include accessCode in templateData. Static values max 10 characters, or {dynamicFieldName} for per-recipient codes (must match a name in dynamicFields). Resolved values must be 10 characters or fewer. Recipients verify on the AddToWallet hosted card or embed page — you do not need to implement preview verification.

Dynamic Field Placeholders

Use {fieldName} syntax in any string field within templateData to create dynamic placeholders. When creating passes from this template, these placeholders will be replaced with actual values provided in the request.

⚠️ Text Modules Validation

The textModulesData field follows the same validation rules as the Create Pass API:

Valid IDs: Only r1start, r1middle, and r1end are accepted (lowercase, case-sensitive)
Maximum: 3 items allowed
Required fields: Each item must have non-empty header and body fields (after trimming)

Items with invalid IDs (e.g., r2start, r2end, r3middle) or empty headers/bodies will be automatically removed. If all items are invalid, an empty array will be used.

Apple Thumbnail & Background (optional)

Sending thumbnailImage and/or backgroundImage enables Apple event-ticket layout automatically — do not send a layout switch field.
Google: still use googleHeroImage / heroImage; thumbnail does not replace the Google hero.
Apple: when thumbnail/background are set, appleHeroImage is not used for the Apple strip.
backgroundImage is optional; Apple falls back to hexBackgroundColor.
With thumbnailImage, textModulesData renders in a three-column auxiliary row; without thumbnail, fields use the secondary row.
On update, send null or an empty string to remove an image; when both are cleared, the pass reverts to strip layout.
When backgroundImage is set, set explicit appleFontColor and appleLabelColor for readable text.
Dynamic placeholders are supported — e.g. "thumbnailImage": "{photoUrl}" inside templateData (must match a name in dynamicFields).

Apple Thumbnail & Background

Name	Type	Required	Description
templateData.thumbnailImage	`string`	No	Apple square thumbnail image URL (~90×90 in Wallet). Sending this and/or backgroundImage enables Apple event-ticket layout automatically — no layout field needed.
templateData.backgroundImage	`string`	No	Optional Apple full-card background image (180×220 aspect). Also enables event-ticket layout when set alone. Apple falls back to hexBackgroundColor when omitted.

All parameters from the Create Pass API are supported
Any string value can contain dynamic field placeholders
Dynamic fields are case-sensitive and must match exactly
Unused dynamic fields in the template will remain as placeholders

Request Example

curl -X POST 'https://api.addtowallet.co/api/dynamicPass/template/' \
  -H 'apikey: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Employee Business Card Template",
    "description": "A template for employee business cards with dynamic employee information",
    "templateData": {
      "logoUrl": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png",
      "rectangleLogo": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png",
      "cardTitle": "{companyName}",
      "header": "{employeeName}",
      "subheader": "{department}",
      "textModulesData": [
        { "id": "r1start", "header": "Position", "body": "{position}" },
        { "id": "r1middle", "header": "Department", "body": "{department}" },
        { "id": "r1end", "header": "Phone", "body": "{phone}" }
      ],
      "linksModuleData": [
        {
          "id": "r1",
          "description": "Call {employeeName}",
          "uri": "tel:{phone}"
        },
        {
          "id": "r2",
          "description": "Email {employeeName}",
          "uri": "mailto:{email}"
        },
        {
          "id": "r3",
          "description": "Visit our website",
          "uri": "{websiteUrl}"
        }
      ],
      "barcodeType": "QR_CODE",
      "barcodeValue": "{employeeId}",
      "barcodeAltText": "Employee ID: {employeeId}",
      "hexBackgroundColor": "#141f31",
      "appleFontColor": "#FFFFFF",
      "heroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png",
      "googleHeroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png",
      "appleHeroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png"
    },
    "dynamicFields": ["companyName","employeeName","position","department","phone","email","employeeId","websiteUrl"]
  }'

Response

Upon successful creation, the API returns a JSON object containing:

dynamicPassId (string): A unique identifier for the created template
groupId (string): The ID of the automatically created user group in the Manage Users section (API calls only)
message (string): A success message confirming the template and user group creation (API calls only)

Response Example

{
  "dynamicPassId": "686d0d92c2f0bc5cdf25c834",
  "groupId": "66b6005bb7bddce8f05a3392",
  "message": "Dynamic pass template created with auto-generated user group for API access"
}

Using the Template

Once created, you can use this template to generate passes by calling Add User with the returned groupId and providing values for the dynamic fields defined in the template. Look up the group any time with List User Groups, or manage it from your dashboard's Manage Users section.

Error Code	Description
400	BAD_REQUEST - Missing required fields or invalid data format
401	UNAUTHORIZED - Valid API key required
500	SERVER_ERROR - Database error or unexpected server issue

Create Dynamic Pass Template API

Overview

🔗 Automatic User Group Creation

Base URL

https://app.addtowallet.co

POST/api/dynamicPass/template/

Authentication

All API requests must include your API key in the request headers:

"apikey": "your-api-key-here"

Request Parameters

The API accepts the following parameters in the request body JSON:

Request Parameters

Name	Type	Required	Description
name	`string`	Yes	A descriptive name for the template (max 100 characters)
templateData	`object`	Yes	The pass template configuration including design elements and dynamic field placeholders
dynamicFields	`array<string>`	Yes	An array of field names that can be dynamically populated when creating passes from this template
description	`string`	No	A detailed description of the template's purpose and usage

Template Data Structure

The templateData object follows the same structure as the Create Pass API, but supports dynamic field placeholders using double curly braces syntax: {fieldName}

Access code protection

Dynamic Field Placeholders

⚠️ Text Modules Validation

The textModulesData field follows the same validation rules as the Create Pass API:

Valid IDs: Only r1start, r1middle, and r1end are accepted (lowercase, case-sensitive)
Maximum: 3 items allowed
Required fields: Each item must have non-empty header and body fields (after trimming)

Items with invalid IDs (e.g., r2start, r2end, r3middle) or empty headers/bodies will be automatically removed. If all items are invalid, an empty array will be used.

Apple Thumbnail & Background (optional)

Sending thumbnailImage and/or backgroundImage enables Apple event-ticket layout automatically — do not send a layout switch field.
Google: still use googleHeroImage / heroImage; thumbnail does not replace the Google hero.
Apple: when thumbnail/background are set, appleHeroImage is not used for the Apple strip.
backgroundImage is optional; Apple falls back to hexBackgroundColor.
With thumbnailImage, textModulesData renders in a three-column auxiliary row; without thumbnail, fields use the secondary row.
On update, send null or an empty string to remove an image; when both are cleared, the pass reverts to strip layout.
When backgroundImage is set, set explicit appleFontColor and appleLabelColor for readable text.
Dynamic placeholders are supported — e.g. "thumbnailImage": "{photoUrl}" inside templateData (must match a name in dynamicFields).

Apple Thumbnail & Background

Name	Type	Required	Description
templateData.thumbnailImage	`string`	No	Apple square thumbnail image URL (~90×90 in Wallet). Sending this and/or backgroundImage enables Apple event-ticket layout automatically — no layout field needed.
templateData.backgroundImage	`string`	No	Optional Apple full-card background image (180×220 aspect). Also enables event-ticket layout when set alone. Apple falls back to hexBackgroundColor when omitted.

All parameters from the Create Pass API are supported
Any string value can contain dynamic field placeholders
Dynamic fields are case-sensitive and must match exactly
Unused dynamic fields in the template will remain as placeholders

Request Example

curl -X POST 'https://api.addtowallet.co/api/dynamicPass/template/' \
  -H 'apikey: your-api-key-here' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Employee Business Card Template",
    "description": "A template for employee business cards with dynamic employee information",
    "templateData": {
      "logoUrl": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png",
      "rectangleLogo": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png",
      "cardTitle": "{companyName}",
      "header": "{employeeName}",
      "subheader": "{department}",
      "textModulesData": [
        { "id": "r1start", "header": "Position", "body": "{position}" },
        { "id": "r1middle", "header": "Department", "body": "{department}" },
        { "id": "r1end", "header": "Phone", "body": "{phone}" }
      ],
      "linksModuleData": [
        {
          "id": "r1",
          "description": "Call {employeeName}",
          "uri": "tel:{phone}"
        },
        {
          "id": "r2",
          "description": "Email {employeeName}",
          "uri": "mailto:{email}"
        },
        {
          "id": "r3",
          "description": "Visit our website",
          "uri": "{websiteUrl}"
        }
      ],
      "barcodeType": "QR_CODE",
      "barcodeValue": "{employeeId}",
      "barcodeAltText": "Employee ID: {employeeId}",
      "hexBackgroundColor": "#141f31",
      "appleFontColor": "#FFFFFF",
      "heroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png",
      "googleHeroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png",
      "appleHeroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png"
    },
    "dynamicFields": ["companyName","employeeName","position","department","phone","email","employeeId","websiteUrl"]
  }'

Response

Upon successful creation, the API returns a JSON object containing:

dynamicPassId (string): A unique identifier for the created template
groupId (string): The ID of the automatically created user group in the Manage Users section (API calls only)
message (string): A success message confirming the template and user group creation (API calls only)

Response Example

{
  "dynamicPassId": "686d0d92c2f0bc5cdf25c834",
  "groupId": "66b6005bb7bddce8f05a3392",
  "message": "Dynamic pass template created with auto-generated user group for API access"
}

Using the Template

Error Code	Description
400	BAD_REQUEST - Missing required fields or invalid data format
401	UNAUTHORIZED - Valid API key required
500	SERVER_ERROR - Database error or unexpected server issue