Die Passinstance REST API gliedert sich in modulare Domänen-Controller, die überwiegend unter /api/v1 eingebunden sind (ergänzt um eigene präfixfreie Routen für POS /v1/pos/*, Pull-Webhooks /webhook-payload, eingehende Anbieter-Webhooks /webhooks/*, Health-Probes /health/* sowie Smart-Links /s/:token und /d/:slug). Jeder Endpunkt verwendet Standard-HTTP-Verben (GET, POST, PUT, PATCH, DELETE), erzwingt anhand Ihrer API-Zugangsdaten die Mandantenisolation des Arbeitsbereichs und gibt ein deterministisches JSON-Payload zurück (API response (T) bei Arbeitsbereich-APIs).
Voraussetzungen: Erstellen Sie unter /settings/workspace/developer/api-credentials einen Arbeitsbereich-API-Schlüssel (pi_live_... oder pi_test_...) mit den benötigten API_KEY_SCOPE_VALUES (passes, templates, scans, webhooks, analytics oder *), bevor Sie /api/v1/*-Routen aufrufen. Eine interaktive OpenAPI-Dokumentation steht unter GET /api/public/docs und /docs bereit.
Stellt eine Pass-Instanz aus (request payload: templateId, optional externalId, idempotencyKey, attributes), signiert mit dem Vorlagen-Zertifikat (bundleId = Apple passTypeIdentifier).
POST
/api/v1/passes/upsert-by-external-id
Erstellt oder aktualisiert idempotent einen Pass, der über (templateId, externalId) zugeordnet wird (request payload).
GET
/api/v1/passes
Listet Pass-Instanzen mit Paginierung, Statusfilterung (pass status) und Suchabfragen auf.
GET
/api/v1/passes/:id
Ruft vollständige Details, dynamische Attribute, externalId, serialNumber und Registrierungsstatus ab.
PATCH / PUT
/api/v1/passes/:id
Aktualisiert dynamische Felder, Stufe oder Ablaufdatum und sendet Live-Updates an installierte Wallets.
POST
/api/v1/passes/voiding/:id/void
Entwertet einen Pass (request payload + VoidingReason) und versendet ein stilles voided: true-Push-Update.
DELETE
/api/v1/passes/:id
Löscht einen Pass per Soft-Delete und widerruft aktive Wallet-Installationen.
POST
/api/v1/passes/export
Exportiert gefilterte Pass-Datensätze als UTF-8-CSV- oder JSON-Download-Job.
POST
/api/v1/batch-pass-operations/create
Führt synchrone/gequeute Massen-Pass-Erstellungen über Batch Operations API aus (ebenfalls /update, /upsert, /activate, /deactivate, /delete).
POST
/api/v1/batch-processing
Übermittelt einen asynchronen großen CSV-/JSON-Stapelauftrag, verfolgt über Batch Processing API.
2. Vorlagen & Mechaniken
Verb
Pfad
Beschreibung
GET
/api/v1/templates
Listet Pass-Vorlagen des Arbeitsbereichs, Pass-Typen (PassKind), bundleId-Zertifikatsbindungen und Veröffentlichungsstatus auf.
GET
/api/v1/templates/:id
Liefert Vorlagenschema, visuelles Layout und aktive Mechaniken zurück.
POST
/api/v1/templates/:id/publish
Veröffentlicht Entwurfsänderungen (request payload) und versendet gebündelte Push-Updates (vorab GET .../publish-risk-check).
GET
/api/v1/templates/:templateId/attributes
Listet dynamische Feldschlüssel und -typen auf, die bei der Pass-Ausstellung benötigt werden (unterstützt OAuth templates:read).
POST
/api/v1/mechanics/redeem
Löst eine freigeschaltete Treue- oder Stempelkarten-Prämie ein (request payload: UUID passId, mechanicId).