Google Sheet Extension
PDF to Pass
Image to Pass
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.
All API requests must include your API key in the request headers:
"apikey": "your-api-key-here"
The API accepts the following parameters in the request body JSON:
| 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) |
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.
| 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 |
thumbnailImage and/or backgroundImage enables Apple event-ticket layout automatically — do not send a layout switch field.googleHeroImage / heroImage; thumbnail does not replace the Google hero.appleHeroImage is not used for the Apple strip.backgroundImage is optional; Apple falls back to hexBackgroundColor.thumbnailImage, textModulesData renders in a three-column auxiliary row; without thumbnail, fields use the secondary row.null or an empty string to remove an image; when both are cleared, the pass reverts to strip layout.backgroundImage is set, set explicit appleFontColor and appleLabelColor for readable text.| 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. |
| 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: 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: 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. |
| 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.
| 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. |
Configure automatic notifications that trigger based on events, expiration dates, or location proximity. See the Notifications API documentation for complete details.
| 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"
}Upon successful creation, the API returns a JSON object containing:
https://app.addtowallet.co/card/){
"msg": "Pass added successfully!",
"cardId": "66b6005bb7bddce8f05a3392",
"shareUrl": "https://app.addtowallet.co/card/66b6005bb7bddce8f05a3392"
}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.
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:
https://app.addtowallet.co/card/{cardId}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.
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 |