Overview
Passinstance replaces static PDF attachments and paper printouts with native digital Event Ticket passes inside Apple Wallet and Google Wallet. Event organizers, music festivals, sports arenas, and conference producers deliver high-throughput gate admissions, real-time schedule announcements, and venue navigation maps directly to attendee smartphones.
Backend Architecture & Pass Types
In the Passinstance backend, event tickets are modeled using native wallet primitives:
-
Pass Type (pass type):
eventTicket. -
Layout Variants (theme preference):
- posterEventTicket: Implements Apple's poster event layout with an edge-to-edge graphic (artwork asset slot) and clean metadata overlays. - bannerEventTicket: Classic horizontal strip banner with prominent seat and gate details.
-
Event Categorization (Apple Wallet event type):
- PKEventTypeLivePerformance: Concerts, theatre, comedy. - PKEventTypeSports: Stadium matches, tournaments. - PKEventTypeConference / PKEventTypeConvention / PKEventTypeWorkshop: Multi-day summits, trade shows, and workshops. - PKEventTypeMovie: Cinemas and film festivals. - PKEventTypeGeneric / PKEventTypeSocialGathering: General admission and social gatherings.
-
Multi-Ticket Order Grouping (
externalId&bundleId): Store each ticket's external order-line ID inexternalId, and group up to 10 family/VIP tickets into a sharedPass.bundleIdvia/api/v1/bundlesorPassProjectso guests can add all tickets in one.pkpassesdownload tap. -
Catalog Demo Blueprints:
event-ticketandconference-badge.
Apple Event Guide & MapKit Venue Integration
For venues and large festivals, Passinstance passes integrate with Apple Maps to surface localized navigation and event amenities:
Event Guide & Venue Action URLs (request payload)
-
venuePlaceID: Apple Maps Place Identifier. When present, Apple Wallet renders an interactive venue map, parking directions, and public transit links. -
venueMap: Custom static asset showing gate entrances, VIP lounges, restrooms, and emergency exits. -
Event Companion Action Links:
request payloadnatively accepts optional HTTPS/mailto/tel links rendered on modern Apple Event Tickets:bagPolicyURL,orderFoodURL,parkingInformationURL,purchaseParkingURL,directionsInformationURL,contactVenueEmail,contactVenuePhoneNumber, andcontactVenueWebsite. -
relevantDate/relevantDates: W3C ISO 8601 date(s). iOS automatically surfaces the event pass on the user's lock screen near doors open. -
Geofencing Coordinates (
locations): Latitude and longitude coordinates around the venue trigger lock-screen display when attendees arrive on site.
Turnstile & Gate Validation Engine
High-throughput gates require fast, offline-resilient validation:
Scanner Modes (ScanMode)
-
CHECK_IN: Marks the ticket scanned for admission. If presented again at a turnstile, the engine rejects the ticket with decisionALREADY_USED. -
CHECK_OUT: Supports temporary venue exit for smoking areas or lunch breaks. -
SAVE_ATTENDANCE: Logs session attendance (ideal for multi-track conference breakout rooms).
Sample Scan Validation Request
/api/v1/scans
{
"scannedBarcodeValue": "TKT-ARENA-90218-A"
}
Sample Validation Response (200 OK)
{
"decision": "SUCCESS",
"status": "ACCEPTED",
"passSnapshot": {
"id": "pass_tkt_90218",
"templateId": "tmpl_event_5521",
"serialNumber": "TKT-ARENA-90218-A",
"status": "ACTIVE",
"attributes": {
"section": "104",
"row": "F",
"seat": "18",
"gate": "Gate C"
}
}
}
Real-Time Schedule Push Updates
When weather delays occur, artists change, or gate assignments shift:
-
1
Update the template or individual passes via
PATCH /api/v1/passes/:idor CSV batch update. -
2
Modify the
gateoreventDatefield. -
3
Apple Wallet and Google Wallet receive instant updates:
- Apple Wallet displays a lock-screen banner: "Gate changed to Gate D" (via changeMessage: "Gate changed to %@"). - Google Wallet updates the live card widget and notifies the user.
Prerequisites: Use 2D Aztec (
PKBarcodeFormatAztec) or QR (PKBarcodeFormatQR) barcode symbologies for event tickets. Aztec barcodes feature high error correction and can be decoded rapidly by optical laser and camera scanners even on dim mobile phone screens.
Explore our Event Tickets Use Case and Events & Ticketing.
