For the latest version of this document go to the Developer Hub
We're thrilled to have you start using the Badge API! Follow these simple steps to get started:
Step 1: Log In to Your Badge Workspace
The Workspace is the user interface for managing all things Badge. If you don't have a Workspace or are not sure if you have access, contact your Account Manager to receive an email invite.
Step 2: Set Up Your API Key
Once you're logged in to a Workspace
Navigate to Settings > API Management.
Create an API key—this key can be used with Bearer authentication.
Step 3: Create a Pass Template
Apple Pass Type Identifier Required: Before creating a Pass Template, you must configure an Apple Pass Type Identifier. You can do this either manually in the Workspace or programmatically via the API:
A Pass Template is a boilerplate design for passes. Passes that are issued under a specific Pass Template will inherit its type (e.g., Membership/Loyalty, Gift Card, Event Ticket) and general layout.
You have two options for creating a Pass Template:
Manually Create a Pass Template: You can do this directly within the Workspace. Wherever you see a lightning bolt icon ⚡, you can add Custom Attributes, dynamic fields whose values can be set and updated via the API for each individual pass.
Programmatically Create a Pass Template: Use our API endpoints to configure an Apple Pass Identifier and for Pass Template creation and updating:
Custom Attributes allow you to vary each pass by making the values shown to passholders dynamic. There are two types of Custom Attributes:
User Attributes are shared across all passes belonging to a user (e.g., member name, points balance, loyalty tier). If you update a User Attribute, the change applies to all of that user's passes.
Pass Attributes are unique to a specific pass (e.g., ticket number, expiration date, unique reward code). Use these when managing multiple passes per user.
Step 4: Issue and Update Passes
Use the userPassUpsert API endpoint to issue and update passes based on the Pass Template you’ve created. The unique Pass Download Link included in the response can be shared with your user to install the pass. The Pass Download Link adapts to the user's device type and installs an Apple Wallet or Google Wallet pass accordingly.
To update user attributes in your template, ensure they are passed within the User data. Pass-specific attributes come into play when managing multiple passes per user (e.g., ticket numbers, expiration dates).
Here’s an example combining both User and Pass attributes:
curl --request POST \
--url https://api.trybadge.com/v0/rpc/userPassUpsert \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '
{
"passTemplateId": "a84f890a-2478-925f-38ba-673e833e526c",
"user": {
"id": "123456789012",
"email": "[email protected]",
"attributes": {
"memberBalance": "1000"
}
},
"pass": {
"id": "00000000001",
"attributes": {
"ticketNumber": "ABC123",
"ticketExpiration": "2025-12-31"
}
}
}'
Response
A successful call returns a pass.downloadUrl:
{
"pass": {
"downloadUrl": "https://api.trybadge.com/download?id=983402-858758-4c67-8cad-5d7fb95f5fb0&token=rLrcpSvUFqTIwy1FQA"
}
}This link is device-adaptive. When opened, it automatically installs an Apple Wallet or Google Wallet pass based on the user's device. You can distribute it via email, SMS, or any other channel.
Step 5: Send Push Notifications
When users have installed your passes, they become passholders who can receive campaigns from you.
Use passSendPushNotification to programmatically send push notifications to specific passes. Targeting logic, such as determining which passes should receive notifications, is typically managed on your side. Ensure you track the passId that you set for each pass when issuing them via the userPassUpsert endpoint, as this identifier will be needed to send notifications to the correct passholders.
To send a campaign to a large number of passholders at once, use the notificationBatchCreate endpoint rather than calling passSendPushNotification individually for each pass.
To mirror the Campaign functionality that is available in the Badge Workspace, you can combine a push notification with pass changes using userPassUpsert. For example, you can update a member's points balance and notify them of the change at the same time.
A few things to know about notification delivery:
Delivery is attempted for up to 24 hours after the scheduled send time.
A notification is considered failed if it is not delivered within that window (e.g., if the user's device is offline or a newer notification has already been sent).
Google Wallet passes have a daily delivery limit of 3 notifications per day (24 hours), per pass.