After you design your pass Template, you can then Generate the passes and Distribute them to your users.
Haven’t created your Template yet? Hop over to Design Passes.
You can generate passes by using the Reach API or by uploading a CSV file via the Reach dashboard.
CSV Batch Importer
To create passes via the CSV Batch Importer, you must upload a CSV file formatted with columns that match the field layout for your pass template. After uploading the CSV file in the Reach dashboard, you will receive a link to download the processed file appended with the pass URLs. You can then distribute the passes via email or the method of your choosing.
The URLs returned by the CSV Batch Importer are multi-use passes — they can be downloaded by multiple devices.
URLs are Dynamic
Viewable passes are not generated until the user interacts with the pass URL and installs the pass on a device. Due to the dynamic nature of pass URLs, keep in mind the following:
When a pass is created with specific values, the pass cannot be updated until after it has been installed.
If a template is changed before a pass is installed, the pass will have the newest template state.
Caution: Creating multiple passes with a single external ID will cause any pass after the first one that is installed to fail and send an error message. Make sure that each pass has a unique external ID.
Navigate to the Templates section in the Reach dashboard, select the template that will serve as the base model for your passes, then click the Edit Design button.
Click Field Layout in the header, and use the field names as the initial data in your CSV file. The field names for your template are located on the left side of the Field Layout screen:
Create a CSV file with a header row that specifies each field name, followed by rows specifying values for each field name. Each row represents a single pass.
The only date format accepted for Android templates is YYYY-MM-DD.
You will be able to map your CSV headers to the correct Field Names after import.
Here is the start of a valid CSV file corresponding to the template in the above images:
We recommend your CSV file contain no more than 500,000 rows. While we do not limit the number of passes you can create via batch import, the file size limit is 250 MB.
In addition to columns specifying each field name, you may also include columns for:
barcode_value: You can use this column to customize barcode values on a per-pass level.
externalId: The external identifier value specifies a user ID in a backend system (e.g. a CRM database), which may be used to map a pass to your data. For example, suppose a customer receives a pass with an
externalIdvalue that links to an ID in your backend loyalty system. If this customer makes a purchase that earns loyalty points, his or her pass can be updated with this new data. Because this field maps to a specific pass, it must be unique. Rows containing duplicate
externalIdvalues will not be processed.
Import and Field Mapping
Navigate to the Templates section in the Reach dashboard, and select the template you used for your CSV file fields.
Click the Batch Importer button.
Click the Select a .csv file button.
Only .csv files will be available for selection. Choose the file you wish to upload.
Matched CSV headers and Field Names will auto-select. Use the dropdown menu to select the correct Field Name per CSV header, or leave blank if there is no corresponding Field Name or if you wish to not match to the CSV header, e.g. a field name matches but you don’t want it displayed on the pass.
Click the Confirm Mapping button after you have completed mapping each field.
Enter your email address. This defaults to the email address in your reach.urbanairship.com account, but you can enter any valid email address. Make changes, if necessary, then click the Process CSV button.
When your CSV file has finished uploading/validating, an email confirmation and download link will be sent to the provided address.
The validation process will search for errors, and if any are detected, the
email will direct you to the offending line(s). Once your CSV file has finished
uploading/validating, an updated CSV file containing
Pass ID and
Download URL columns will be sent to the given address.
Each URL can be used to download the associated pass. The updated file will also be available via the Download CSV file button.
When you receive the processed CSV file, an additional column titled Download URL is added to the file. The URLs in the Dowload URL column are formatted like so:
In the above example URL,
is the internal reference ID that you will need when referencing this pass via
the Reach API.
URLs that are not activated will expire after 6 months.
Display Passes on Lock Screen
There are two ways to make your pass show up on a user’s lock screen: Relevant Location and Relevant Date. See Triggers for set up steps.
Relevant Location displays a shortcut to your pass on the user’s screen when the device is in the vicinity of certain location. The radius around the location where the shortcut appears is determined by Apple Wallet or Android Pay and varies by pass type. For instance, Boarding Passes will appear on the lock screen at around 2 miles, but Coupons will appear at a few hundred feet.
Relevant Date displays a shortcut to your pass on a user’s lock screen at a certain date and time. This is handy for certain types of passes, like Events and Boarding Passes. As with Relevant Location, the timing when the shortcut appears is determined by Apple Wallet or Android Pay and varies by pass type. Relevant Date is not supported on Coupons or Store Cards.
Link to Pass
A .pkpass file can be considered similar to a PDF, or any other document that you might link to. Right now, you can upload the .pkpass file to your web server, and link to it as you normally would.”
For Mobile Safari to recognize the file, your server has to be properly
configured to support the MIME-type
process for adding MIME-type support varies by web server vendor. Many
hosting companies provide a control panel interface which allows you to
easily add a new type.
Save to Android Pay
Pass creation via the API is the preferred method due to ease of use and implementation, but in some cases you may want to use the Save to Android Pay method.
Define the Origin URL in the project’s Settings API menu.
The template ID must match the template ID in Reach. This API call will accept the following optional JSON values:
Once the Save to Android Pay button is rendered on the page, a user can hover over it to display the currently logged in account, with an option to change to a different account. If not logged in, a log in window appears.
After clicking the button while logged in with a valid Google account, the
Google Object will be created and saved to the user’s wallet. Depending on how
you configure the
onSuccess JSON value, you can redirect to a different page
the card was successfully saved.
Send Test Pass
After you have saved your Template, send yourself a test pass. iOS devices must be running at minimum iOS 6 to view passes.
Navigate to the Templates section in the Reach dashboard, select a template, then click the Edit Design button.
Click the Send Test Pass button at the bottom of the screen, then:
- Apple: Enter an email address in the browser dialog that opens, then click the OK button.
- Android: Click the Save to Android Pay button. If not logged in, a log in window appears. After clicking the button while logged in with a valid Google account, the pass will be created and saved to the Google account’s wallet.
View the pass on your mobile device:
- Apple: Open the Mail app on your iOS device, open the “New Pass Generated…” email, tap the Wallet attachment to view the pass, then tap the Wallet attachment to save and view the pass.
- Android: Check the Android Pay application on your device, and open your saved pass to view it.