Create Pass API

Overview

The Create Pass API allows you to programmatically generate and deploy digital passes for Google Wallet and Apple Wallet. This endpoint accepts pass details and returns a unique identifier that can be used to generate a shareable wallet pass URL.

Base URL

https://app.addtowallet.co

POST/api/card/create

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
cardTitle	`string`	Yes	Pass title (business or organization name)
header	`string`	Yes	Primary header (e.g., person name)
subheader	`string`	No	Secondary header text displayed below the main header (e.g., reward tier, event subtitle)

Design Elements

Platform-Specific Images

Use googleHeroImage and appleHeroImage to optimize images for each platform. If only heroImage is provided, it will be used as a fallback for both platforms. Platform-specific images take precedence over the general heroImage. Watermarking is handled automatically based on your plan; API users do not need to provide raw image URLs. For Apple event-ticket layout with a square thumbnail instead of the Apple strip, see Apple Thumbnail & Background below.

Design Elements

Name	Type	Required	Description
logoUrl	`string`	Yes	Logo image URL
rectangleLogo	`string`	No	Wide logo that replaces round logo and title where supported
heroImage	`string`	Yes	Fallback hero image for both platforms
googleHeroImage	`string`	No	Google-specific hero image (overrides heroImage for Google)
appleHeroImage	`string`	No	Apple-specific hero image (overrides heroImage for Apple)
hexBackgroundColor	`string`	Yes	Background color hex code
appleFontColor	`string`	Yes	Apple font color hex code

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.

Apple Thumbnail & Background

Name	Type	Required	Description
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.
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.

Content Elements

Name	Type	Required	Description
textModulesData	`array<TextModule>`	No	Text modules rendered on the pass. Maximum 3 items allowed. Each TextModule object requires: id (string, required), header (string, required), and body (string, required). Valid ID formats: `r1start`, `r1middle`, `r1end` (lowercase, case-sensitive). The API gracefully handles invalid items by automatically removing them instead of failing the request. Items with unknown ID formats (e.g., r2start, r3middle), empty/whitespace-only header or body fields, or duplicate IDs will be removed (duplicates keep first occurrence). If all items are invalid, an empty array will be returned. The API will only throw an error if more than 3 items are provided before cleaning.
linksModuleData	`array<Link>`	No	Interactive links displayed on the back of the pass. Each Link object requires: id (string, required), description (string, required), and uri (string, required). Supported URI formats: `tel:` (phone calls), `mailto:` (email), `http://` or `https://` (web links), and `geo:` (location/maps). The id must be unique within the array. The description is the text displayed to users. The uri is the target URL or action that will be triggered when the link is tapped.

Barcode Settings

Name	Type	Required	Description
barcodeType	`string`	No	Barcode type. Allowed values: `QR_CODE`, `AZTEC`, `CODE_128`, `PDF_417`, `NONE`. Default: `QR_CODE`
barcodeValue	`string`	No	Value encoded in barcode
barcodeAltText	`string`	No	Alt text displayed below barcode

Recipients enter the code on the AddToWallet hosted card or embed page before previewing or downloading the pass. You do not need to implement preview verification in your integration.

Access Protection (Optional)

Name	Type	Required	Description
accessCode	`string \| null`	No	When set, recipients must enter this code before previewing or downloading the pass. Values are limited to 10 characters. Send `null` or an empty string to remove protection.

Scheduled Notifications

Configure automatic notifications that trigger based on events, expiration dates, or location proximity. See the Notifications API documentation for complete details.

Notification Settings (Optional)

Name	Type	Required	Description
notificationValues	`array<string> \| string`	No	One or more scheduled notifications to enable. When both upcomingNotification and expiryNotification are provided, upcomingNotification is set first and automatically switches to expiryNotification 24 hours after the start date. A single string remains supported for backward compatibility. Allowed values: `upcomingNotification`, `expiryNotification`, `locationNotification`, `beaconNotification` (Apple Wallet iBeacon only; supply `appleBeacons` or `beacons`)
appleBeacons	`array<Beacon>`	No	Apple only: up to 10 iBeacon rows (alias `beacons`). Use with `beaconNotification`; optional `relevantText` per row.
proximityUUID	`string`	Yes	iBeacon UUID
major	`number`	Yes	0–65535
minor	`number`	Yes	0–65535
relevantText	`string`	No	Optional lock-screen text near this beacon
startDate	`string (ISO 8601)`	Conditional	Required for upcomingNotification
endDate	`string (ISO 8601)`	Conditional	Required for expiryNotification
locations	`array<Location> \| Location`	No	Merchant locations for proximity notifications (up to 10). Use optional <code>message</code> per location for Apple Wallet custom lock-screen text.
latitude	`number`	Yes	Latitude -90 to 90
longitude	`number`	Yes	Longitude -180 to 180
message	`string`	No	Apple only: custom text when user is near this location
altitude	`number`	No	Optional altitude in meters

{
  "logoUrl": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png",
  "cardTitle": "Your Business Name",
  "header": "Amy Jane",
  "subheader": "Senior Developer",
  "textModulesData": [
    {
      "id": "r1start",
      "header": "Phone",
      "body": "+1 8888888888"
    },
    {
      "id": "r1end",
      "header": "Email",
      "body": "[email protected]"
    }
  ],
  "linksModuleData": [
    {
      "id": "r1",
      "description": "Call Us",
      "uri": "tel:+1 8287489293"
    },
    {
      "id": "r2",
      "description": "Email Us",
      "uri": "mailto:[email protected]"
    },
    {
      "id": "r3",
      "description": "Visit our website",
      "uri": "https://app.addtowallet.co"
    },
    {
      "id": "r4",
      "description": "Visit our office",
      "uri": "geo:https://maps.google.com/?q=123+Main+Street,+Anytown,+CA"
    }
  ],
  "barcodeType": "QR_CODE",
  "barcodeValue": "",
  "barcodeAltText": "",
  "hexBackgroundColor": "#141f31",
  "appleFontColor": "#FFFFFF",
  "heroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png",
  "rectangleLogo": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png",
  "googleHeroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png",
  "appleHeroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png",
  "notificationValues": [
    "upcomingNotification",
    "expiryNotification",
    "locationNotification"
  ],
  "startDate": "2025-01-01T09:00:00Z",
  "endDate": "2025-01-02T09:00:00Z",
  "locations": [
    {
      "latitude": 37.774929,
      "longitude": -122.419416
    },
    {
      "latitude": 37.331,
      "longitude": -122.029,
      "message": "Store nearby on 3rd floor"
    }
  ],
  "accessCode": "VIP2026"
}

Response

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

cardId (string): A unique identifier for the created pass
msg (string): A success message confirming the pass creation
shareUrl (string): The complete shareable URL for the pass. If a custom domain is configured and enabled for your account, this URL will use your custom domain. Otherwise, it will use the default domain (https://app.addtowallet.co/card/)

Response Example

{
  "msg": "Pass added successfully!",
  "cardId": "66b6005bb7bddce8f05a3392",
  "shareUrl": "https://app.addtowallet.co/card/66b6005bb7bddce8f05a3392"
}

Shareable Pass URL

The API response includes a shareUrl field containing the complete shareable URL for the pass. This URL can be shared directly with users, embedded in emails, or used in QR codes to facilitate easy pass distribution.

Custom Domain Support

If you have a custom domain configured and enabled in your account settings, the shareUrl will automatically use your custom domain instead of the default domain. This allows you to maintain your brand identity when sharing passes.

Alternatively, you can manually construct the URL using the following formats:

Default Domain:

https://app.addtowallet.co/card/{cardId}

Custom Domain (if configured):

https://yourdomain.com/{cardId}

Replace yourdomain.com with your configured custom domain URL.

Note: To use a custom domain, enable it in your account settings. The shareUrl will automatically reflect your custom domain when enabled.

Error Codes

The API may return the following error status codes:

Status Code	Error	Description
400	Bad Request	Missing required fields, invalid parameter values, or invalid image dimensions (hero images must be at least 200x100 pixels)
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions or exceeding usage limits
429	Too Many Requests	API rate limit exceeded. Try again later
500	Internal Server Error	Unexpected server error. Please contact support

Create Pass API

Overview

Base URL

https://app.addtowallet.co

POST/api/card/create

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
cardTitle	`string`	Yes	Pass title (business or organization name)
header	`string`	Yes	Primary header (e.g., person name)
subheader	`string`	No	Secondary header text displayed below the main header (e.g., reward tier, event subtitle)

Design Elements

Platform-Specific Images

Design Elements

Name	Type	Required	Description
logoUrl	`string`	Yes	Logo image URL
rectangleLogo	`string`	No	Wide logo that replaces round logo and title where supported
heroImage	`string`	Yes	Fallback hero image for both platforms
googleHeroImage	`string`	No	Google-specific hero image (overrides heroImage for Google)
appleHeroImage	`string`	No	Apple-specific hero image (overrides heroImage for Apple)
hexBackgroundColor	`string`	Yes	Background color hex code
appleFontColor	`string`	Yes	Apple font color hex code

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.

Apple Thumbnail & Background

Name	Type	Required	Description
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.
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.

Content Elements

Name	Type	Required	Description
textModulesData	`array<TextModule>`	No	Text modules rendered on the pass. Maximum 3 items allowed. Each TextModule object requires: id (string, required), header (string, required), and body (string, required). Valid ID formats: `r1start`, `r1middle`, `r1end` (lowercase, case-sensitive). The API gracefully handles invalid items by automatically removing them instead of failing the request. Items with unknown ID formats (e.g., r2start, r3middle), empty/whitespace-only header or body fields, or duplicate IDs will be removed (duplicates keep first occurrence). If all items are invalid, an empty array will be returned. The API will only throw an error if more than 3 items are provided before cleaning.
linksModuleData	`array<Link>`	No	Interactive links displayed on the back of the pass. Each Link object requires: id (string, required), description (string, required), and uri (string, required). Supported URI formats: `tel:` (phone calls), `mailto:` (email), `http://` or `https://` (web links), and `geo:` (location/maps). The id must be unique within the array. The description is the text displayed to users. The uri is the target URL or action that will be triggered when the link is tapped.

Barcode Settings

Name	Type	Required	Description
barcodeType	`string`	No	Barcode type. Allowed values: `QR_CODE`, `AZTEC`, `CODE_128`, `PDF_417`, `NONE`. Default: `QR_CODE`
barcodeValue	`string`	No	Value encoded in barcode
barcodeAltText	`string`	No	Alt text displayed below barcode

Recipients enter the code on the AddToWallet hosted card or embed page before previewing or downloading the pass. You do not need to implement preview verification in your integration.

Access Protection (Optional)

Name	Type	Required	Description
accessCode	`string \| null`	No	When set, recipients must enter this code before previewing or downloading the pass. Values are limited to 10 characters. Send `null` or an empty string to remove protection.

Scheduled Notifications

Configure automatic notifications that trigger based on events, expiration dates, or location proximity. See the Notifications API documentation for complete details.

Notification Settings (Optional)

Name	Type	Required	Description
notificationValues	`array<string> \| string`	No	One or more scheduled notifications to enable. When both upcomingNotification and expiryNotification are provided, upcomingNotification is set first and automatically switches to expiryNotification 24 hours after the start date. A single string remains supported for backward compatibility. Allowed values: `upcomingNotification`, `expiryNotification`, `locationNotification`, `beaconNotification` (Apple Wallet iBeacon only; supply `appleBeacons` or `beacons`)
appleBeacons	`array<Beacon>`	No	Apple only: up to 10 iBeacon rows (alias `beacons`). Use with `beaconNotification`; optional `relevantText` per row.
proximityUUID	`string`	Yes	iBeacon UUID
major	`number`	Yes	0–65535
minor	`number`	Yes	0–65535
relevantText	`string`	No	Optional lock-screen text near this beacon
startDate	`string (ISO 8601)`	Conditional	Required for upcomingNotification
endDate	`string (ISO 8601)`	Conditional	Required for expiryNotification
locations	`array<Location> \| Location`	No	Merchant locations for proximity notifications (up to 10). Use optional <code>message</code> per location for Apple Wallet custom lock-screen text.
latitude	`number`	Yes	Latitude -90 to 90
longitude	`number`	Yes	Longitude -180 to 180
message	`string`	No	Apple only: custom text when user is near this location
altitude	`number`	No	Optional altitude in meters

{
  "logoUrl": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png",
  "cardTitle": "Your Business Name",
  "header": "Amy Jane",
  "subheader": "Senior Developer",
  "textModulesData": [
    {
      "id": "r1start",
      "header": "Phone",
      "body": "+1 8888888888"
    },
    {
      "id": "r1end",
      "header": "Email",
      "body": "[email protected]"
    }
  ],
  "linksModuleData": [
    {
      "id": "r1",
      "description": "Call Us",
      "uri": "tel:+1 8287489293"
    },
    {
      "id": "r2",
      "description": "Email Us",
      "uri": "mailto:[email protected]"
    },
    {
      "id": "r3",
      "description": "Visit our website",
      "uri": "https://app.addtowallet.co"
    },
    {
      "id": "r4",
      "description": "Visit our office",
      "uri": "geo:https://maps.google.com/?q=123+Main+Street,+Anytown,+CA"
    }
  ],
  "barcodeType": "QR_CODE",
  "barcodeValue": "",
  "barcodeAltText": "",
  "hexBackgroundColor": "#141f31",
  "appleFontColor": "#FFFFFF",
  "heroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png",
  "rectangleLogo": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatelogo.png",
  "googleHeroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png",
  "appleHeroImage": "https://s3.amazonaws.com/i.addtowallet.co/assets/realestatehero.png",
  "notificationValues": [
    "upcomingNotification",
    "expiryNotification",
    "locationNotification"
  ],
  "startDate": "2025-01-01T09:00:00Z",
  "endDate": "2025-01-02T09:00:00Z",
  "locations": [
    {
      "latitude": 37.774929,
      "longitude": -122.419416
    },
    {
      "latitude": 37.331,
      "longitude": -122.029,
      "message": "Store nearby on 3rd floor"
    }
  ],
  "accessCode": "VIP2026"
}

Response

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

cardId (string): A unique identifier for the created pass
msg (string): A success message confirming the pass creation
shareUrl (string): The complete shareable URL for the pass. If a custom domain is configured and enabled for your account, this URL will use your custom domain. Otherwise, it will use the default domain (https://app.addtowallet.co/card/)

Response Example

{
  "msg": "Pass added successfully!",
  "cardId": "66b6005bb7bddce8f05a3392",
  "shareUrl": "https://app.addtowallet.co/card/66b6005bb7bddce8f05a3392"
}

Shareable Pass URL

Custom Domain Support

Alternatively, you can manually construct the URL using the following formats:

Default Domain:

https://app.addtowallet.co/card/{cardId}

Custom Domain (if configured):

https://yourdomain.com/{cardId}

Replace yourdomain.com with your configured custom domain URL.

Note: To use a custom domain, enable it in your account settings. The shareUrl will automatically reflect your custom domain when enabled.

Error Codes

The API may return the following error status codes:

Status Code	Error	Description
400	Bad Request	Missing required fields, invalid parameter values, or invalid image dimensions (hero images must be at least 200x100 pixels)
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions or exceeding usage limits
429	Too Many Requests	API rate limit exceeded. Try again later
500	Internal Server Error	Unexpected server error. Please contact support