Skip to content
REST-API-Referenz & SDKs

Passinstance Entwickler-Dokumentation

Erstellen Sie hochvolumige Apple Wallet (.pkpass) und Google Wallet Integrationen. Ausstellen, aktualisieren, scannen und Echtzeit-Benachrichtigungen über produktive REST-APIs übertragen.

API-Schlüssel erhalten
Live-Docs-Workbench — Codebeispiele aktualisieren sich während der Eingabe
Kernkonzepte

Architektur & Pass-Lebenszyklus

Die Passverwaltung folgt einem 6-stufigen Lebenszyklus: 1. Vorlage (visueller Bauplan) → 2. Pass (kryptografisch signierter Datensatz) → 3. Verteilung (sichere passAccessUrl) → 4. Wallet-Registrierung (Gerät registriert sich bei APNs / Google Push) → 5. Live-Updates (Echtzeit-Sperrbildschirm-Benachrichtigungen) → 6. Scan- & Einlösetelemetrie (Barcode-Validierung & Webhook-Stream).

1. VorlagePOST /api/v1/templates

Master-Layout, Barcode-Typ, Markenfarben und Schemafelder

Kernkonzepte

Pass-Mechaniken & Loyalty-Solutions-Engine

Verknüpfen Sie zustandsbehaftete Geschäftsmechaniken über 8 schlüsselfertige Lösungen hinweg mit Vorlagen (Treueprogramme, Stempelkarten, Coupons, Geschenkkarten/Prepaid, Event-Tickets, Mitgliedschaften, Mitarbeiterausweise, VIP-Karten). Regeln werden beim Scan oder API-Aufruf atomar ausgeführt.

LOYALTY_PROGRAM

LOYALTY_PROGRAM & Stufen

Punktegutschrift pro Scan (defaultChangeValue) mit automatischer Stufenprogression

STAMP_CARD

STAMP_CARD_ADD / DEDUCT

Verfolgt Stempelpositionen (0..maximumValue) mit onCap ('noop' | 'reset') und rewardClaimBehavior

PREPAID_CARD

PREPAID_CARD Ledger

ISO-4217-Prepaid-Ledger-Buchhaltung in kleinsten Währungseinheiten mit disallowNegativeBalance-Durchsetzung

VALID_ONCE_PER_DAY

VALID_ONCE_PER_DAY & RENEW

Zeitzonenbewusste tägliche Check-in-Limits und automatische Verlängerung von expirationDate beim Scan

Pass-Verwaltung

11 Endpunkte
POSThttps://api.passinstance.com/api/v1/passesAPI-Schlüssel
Pass-Verwaltung

Neuen Pass ausstellen

Erstellen und signieren Sie einen neuen Apple Wallet (.pkpass) & Google Wallet Pass aus einer Vorlage mit Kundenfeldern, Barcode und dynamischen Werten.

Header2 erforderlich • 1 fakultativ
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Erforderlich

Muss application/json sein.

Beispiel: application/json
Query-Parameter2 fakultativ

Nutzlast mit Vorlagen-ID, eindeutiger Seriennummer, Kundenfeldwerten und optionaler Barcode-Konfiguration.

Anfrage-Body1 erforderlich • 15 fakultativ
templateIdstring (UUID)
Erforderlich

Vorlagen-ID für den Pass.

Beispiel: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/upsert-by-external-idAPI-Schlüssel
Pass-Verwaltung

Pass per externer ID synchronisieren (Upsert)

Idempotentes Erstellen oder Aktualisieren eines Passes über (customerId, externalId) für nahtlose CRM-, POS- und E-Commerce-Synchronisation.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Anfrage mit templateId, externalId und dynamischen Pass-Attributen.

Anfrage-Body2 erforderlich • 3 fakultativ
templateIdstring (UUID)
Erforderlich

UUID der Zielvorlage.

Beispiel: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
externalIdstring
Erforderlich

Stabile externe CRM/POS-Kennung, eindeutig innerhalb Ihres Workspaces.

Beispiel: CRM-CUST-99201

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/batch-pass-operations/createAPI-Schlüssel
Pass-Verwaltung

Pässe im Batch ausstellen

Mehrere Wallet-Pässe in einer atomaren Batch-Operation mit Validierung und Fehlerberichterstattung ausstellen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Anfrage mit einem Array von Pass-Konfigurationen.

Anfrage-Body1 erforderlich
passesarray of objects
Erforderlich

Array von Pass-Einträgen mit templateId, barcodeValue und additionalData.

Beispiel: [ { "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b", "barcodeValue": "BULK-001", "additionalData": { "name": "Member #001" } }, { "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b", "barcodeValue": "BULK-002", "additionalData": { "name": "Member #002" } } ]

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/passesAPI-Schlüssel
Pass-Verwaltung

Alle Pässe auflisten

Paginierte Liste von Pässen für den authentifizierten Kunden-Workspace mit Such- und Statusfiltern abrufen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Query-Parameter13 fakultativ

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/passes/{id}API-Schlüssel
Pass-Verwaltung

Pass abrufen

Vollständige Details, Installationsstatus und Download-Links für einen einzelnen Pass über seine eindeutige ID abrufen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Die eindeutige UUID-Kennung des Passes.

Beispiel: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Antwort-Statuscodes

PATCHhttps://api.passinstance.com/api/v1/passes/{id}API-Schlüssel
Pass-Verwaltung

Pass aktualisieren & Push senden

Dynamische Felder, Farben oder Barcodes eines Passes aktualisieren und automatisch APNs- und Google Wallet-Push-Benachrichtigungen an installierte Geräte senden.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Die eindeutige UUID des zu aktualisierenden Passes.

Beispiel: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Felder zur Änderung am Pass. Installierte Geräte erhalten sofortige Hintergrund-Updates.

Anfrage-Body13 fakultativ

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/voiding/{id}/voidAPI-Schlüssel
Pass-Verwaltung

Pass deaktivieren

Einen Pass in Apple Wallet und Google Wallet mit sofortiger Push-Weitergabe als ungültig markieren oder reaktivieren.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idUUID
Erforderlich

Eindeutige Pass-Instanz-ID zum Ungültigmachen oder Reaktivieren.

Beispiel: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Nutzlast zur Steuerung des Void-Status, Audit-Grundes und der Wallet-Verteilungsoptionen.

Anfrage-Body1 erforderlich • 1 fakultativ
voidedboolean
Erforderlich

Auf true setzen, um den Pass ungültig zu machen, oder false zum Reaktivieren.

Beispiel: true

Antwort-Statuscodes

DELETEhttps://api.passinstance.com/api/v1/passes/{id}API-Schlüssel
Pass-Verwaltung

Pass löschen

Einen Pass dauerhaft aus Ihrem Workspace löschen und registrierte Apple-Wallet- und Google-Wallet-Installationen widerrufen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Eindeutige UUID des zu löschenden Passes.

Beispiel: b1d972dc-eccf-4f87-ab21-25939d9213d8

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/useAPI-Schlüssel
Pass-Verwaltung

Mechanik-Aktion anwenden

Atomare Pass-Mechanik-Operation ausführen: INCREMENT (Stempelkarte), DECREMENT, DEBIT (Prepaid-Guthaben), CREDIT oder VALIDATE (Einmal-Coupon).

Header3 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Erforderlich

Muss application/json sein.

Beispiel: application/json
Idempotency-Keystring
Erforderlich

Verpflichtende UUID zur Sicherstellung einer atomaren Ausführung und zur Vermeidung doppelter Guthaben- oder Stempelabbuchungen.

Beispiel: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Die eindeutige UUID des zu bearbeitenden Passes.

Beispiel: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Anfrage mit Mechanik-Aktion, optionalem Dezimalbetrag, Operator-ID und Standort.

Anfrage-Body1 erforderlich • 4 fakultativ
actionstring (enum)
Erforderlich

INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE oder NOOP.

Beispiel: INCREMENT

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/adjust-valueAPI-Schlüssel
Pass-Verwaltung

Pass-Guthaben anpassen

Guthaben oder Prämienpunkte auf einem Pass manuell gutschreiben (CREDIT) oder abbuchen (DEBIT) inklusive Transaktions-Audit-Protokollierung.

Header3 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Erforderlich

Muss application/json sein.

Beispiel: application/json
Idempotency-Keystring
Erforderlich

Verpflichtende UUID zur Sicherstellung atomarer Anpassung und Vermeidung doppelter Gutschriften.

Beispiel: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Pfad-Parameter1 erforderlich
idUUID
Erforderlich

Ziel-Pass-Instanz-ID.

Beispiel: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Anpassungs-Nutzlast mit CREDIT- oder DEBIT-Operation, Betrag und Begründung.

Anfrage-Body2 erforderlich • 2 fakultativ
actionstring
Erforderlich

Transaktionsaktion: 'CREDIT' zum Hinzufügen oder 'DEBIT' zum Abziehen von Guthaben.

Beispiel: CREDIT
amountstring
Erforderlich

Numerischer Betrag zum Gutschreiben oder Abbuchen als Zeichenkette.

Beispiel: 25.00

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/mechanics/redeemAPI-Schlüssel
Pass-Verwaltung

Pass-Mechanik-Prämie einlösen

Verdiente Treue- oder Stempelkarten-Prämie auf einem Pass mithilfe der konfigurierten Pass-Mechanik mit Idempotenzschutz einlösen.

Header1 erforderlich • 1 fakultativ
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx

Einlösungsanfrage mit passId, mechanicId und optionalem idempotencyKey.

Anfrage-Body2 erforderlich • 3 fakultativ
passIdstring (UUID)
Erforderlich

UUID des Passes, der die Prämie einlöst.

Beispiel: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
mechanicIdstring (UUID)
Erforderlich

UUID der an die Vorlage gebundenen Pass-Mechanik-Regel.

Beispiel: mech_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

Antwort-Statuscodes

Suche & Analysen

4 Endpunkte
GEThttps://api.passinstance.com/api/v1/passes/searchAPI-Schlüssel
Suche & Analysen

Pässe durchsuchen

Volltextsuche über ausgestellte Pässe nach Seriennummer, externer ID, E-Mail-Adresse, Inhabername oder benutzerdefinierten Attributen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Query-Parameter1 erforderlich
querystring
Erforderlich

Suchbegriff oder Abfragezeichenfolge (bis zu 500 Zeichen).

Beispiel: Jane Doe

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/passes/statistics/{templateId}API-Schlüssel
Suche & Analysen

Pass-Statistiken abrufen

Aggregierte Ausstellungs-, Aktivierungs-, Wallet-Installations- und Einlösestatistiken für eine bestimmte Pass-Vorlage abrufen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
templateIdstring (UUID)
Erforderlich

UUID der Zielvorlage.

Beispiel: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Query-Parameter2 fakultativ

Antwort-Statuscodes

GEThttps://api.passinstance.com/api/v1/passes/{id}/historyAPI-Schlüssel
Suche & Analysen

Pass-Statusverlauf abrufen

Chronologischen Audit-Verlauf der Statusänderungen, Punkte-/Saldoaktualisierungen, Scans und Entwertungen eines Passes abrufen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Pass UUID.

Beispiel: b1d972dc-eccf-4f87-ab21-25939d9213d8
Query-Parameter1 fakultativ

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/exportAPI-Schlüssel
Suche & Analysen

Pässe als CSV exportieren

UTF-8-CSV-Export (text/csv; charset=utf-8) ausgewählter Pass-Instanzen anhand der Pass-IDs streamen.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Anfrage zur Angabe von 1 bis 2.000 Pass-UUIDs und dem Exportformat.

Anfrage-Body2 erforderlich
passIdsstring[] (UUID v4)
Erforderlich

Array mit 1 bis 2.000 Pass-UUIDs für den CSV-Export.

Beispiel: ["pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"]
formatstring (enum)
Erforderlich

Export-Ausgabeformat ('csv').

Beispiel: csv

Antwort-Statuscodes

Pass-Zustellung

4 Endpunkte
GEThttps://api.passinstance.com/api/v1/passes/{id}/urisAPI-Schlüssel
Pass-Zustellung

Pass-Ressourcen-URLs abrufen

Direkte Download- und Verteilungs-URLs für einen Pass abrufen, einschließlich gehosteter PassFlow-Seite, .pkpass, Google-Wallet-JWT und QR-Code.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

Pass UUID.

Beispiel: b1d972dc-eccf-4f87-ab21-25939d9213d8

Antwort-Statuscodes

GEThttps://api.passinstance.com/d/{slug}/infoÖffentlich
Pass-Zustellung

Gebrandete Download-Seite abrufen

Öffentliche gebrandete Pass-Download-Seite anhand des Slugs auflösen (präfixfrei GET /d/{slug}/info). Für authentifizierte Verwaltungssuche nutzen Sie GET /api/v1/download-pages/slug/{slug}.

Pfad-Parameter1 erforderlich
slugstring
Erforderlich

Eindeutiger Vanity-Slug der gehosteten Download-Seite.

Beispiel: acme-vip-2026
Query-Parameter2 fakultativ

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/enabledownloadAPI-Schlüssel
Pass-Zustellung

Pass-Download aktivieren

Den Download-Link eines Passes erneut aktivieren oder entsperren, wenn die Vorlage mit einer Einmal-Download-Sperre konfiguriert ist.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

UUID des Passes, dessen Download entsperrt werden soll.

Beispiel: b1d972dc-eccf-4f87-ab21-25939d9213d8

Optional timestamp specifying how long re-download remains unlocked.

Anfrage-Body1 fakultativ

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/send-emailAPI-Schlüssel
Pass-Zustellung

Pass per E-Mail senden

E-Mail mit dem Pass-Installationslink (Apple Wallet & Google Wallet) über die transaktionale E-Mail-Pipeline an den Inhaber senden.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idstring (UUID)
Erforderlich

UUID des Passes, der per E-Mail zugestellt werden soll.

Beispiel: b1d972dc-eccf-4f87-ab21-25939d9213d8

Recipient email address(es) and optional custom subject and message body.

Anfrage-Body4 fakultativ

Antwort-Statuscodes

Push-Benachrichtigungen

2 Endpunkte
POSThttps://api.passinstance.com/api/v1/passes/{id}/notificationsAPI-Schlüssel
Push-Benachrichtigungen

Sperrbildschirm-Benachrichtigung senden

Sofortige Push-Benachrichtigung und Sperrbildschirm-Nachricht an einen installierten Apple Wallet (.pkpass) oder Google Wallet Pass senden. Für geplante Sendungen oder Header-Anpassung nutzen Sie POST /api/v1/push-notifications/passes/{id}.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1
Pfad-Parameter1 erforderlich
idUUID
Erforderlich

Eindeutige Pass-Instanz-UUID, die die Benachrichtigung erhalten soll.

Beispiel: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d

Anfrage mit Nachrichtentext und optionalem Header-Titel.

Anfrage-Body1 erforderlich • 1 fakultativ
messagestring
Erforderlich

Textnachricht, die auf dem Sperrbildschirm des Nutzers angezeigt wird.

Beispiel: Your reward points have been updated! You now have 250 points.

Antwort-Statuscodes

POSThttps://api.passinstance.com/api/v1/passes/sendpushnotificationsAPI-Schlüssel
Push-Benachrichtigungen

Massen-Push-Benachrichtigungen senden

Sperrbildschirm-Push-Benachrichtigung gleichzeitig an eine ausgewählte Liste von Pass-IDs über APNs und Google Wallet senden.

Header1 erforderlich
X-API-Keystring
Erforderlich

Geheimer Workspace-API-Schlüssel (pi_live_... oder pi_test_...). Alternativ kann Authorization: ApiKey <key> gesendet werden.

Beispiel: pi_live_98a7b6c5d4e3f2a1

Target pass UUID array (up to 500 passes) and notification message text supporting {attribute} placeholders.

Anfrage-Body2 erforderlich
listOfPassesstring[] (UUID)
Erforderlich

Array mit 1 bis 500 Pass-UUIDs.

Beispiel: ["b1d972dc-eccf-4f87-ab21-25939d9213d8"]
pushNotificationTextstring
Erforderlich

Sperrbildschirm-Nachricht (unterstützt dynamische Platzhalter wie {holderName}).

Beispiel: Hi {holderName}, you unlocked a new reward!

Antwort-Statuscodes