Skip to content
REST API-referentie & SDK's

Passinstance Documentatie voor Ontwikkelaars

Bouw grootschalige Apple Wallet (.pkpass) en Google Wallet integraties. Uitgeven, bijwerken, scannen en realtime meldingen versturen via productieklare REST-API's.

API-sleutels ophalen
Live docs-workbench — fragmenten worden bijgewerkt terwijl je typt
Kernbegrippen

Architectuur & Levenscyclus van passen

Pasbeheer volgt een levenscyclus in 6 fasen: 1. Sjabloon (visuele blauwdruk) → 2. Pas (cryptografisch ondertekend record) → 3. Distributie (beveiligde passAccessUrl) → 4. Wallet-registratie (apparaat meldt zich aan bij APNs / Google Push) → 5. Live updates (realtime meldingen) → 6. Scan- & inwisseltelemetrie (validatie & webhook-stream).

1. SjabloonPOST /api/v1/templates

Hoofdlay-out, streepjescodetype, merkkleuren en schemavelden

Kernbegrippen

Pasmechanica & Loyaliteitsoplossingen

Koppel stateful bedrijfsmechanica aan sjablonen voor 8 kant-en-klare oplossingen (Loyaliteit, Stempelkaarten, Coupons, Cadeau-/Prepaidkaarten, Evenementtickets, Lidmaatschappen, Personeelspassen, VIP-kaarten). Regels worden atomair uitgevoerd bij een scan of API-aanroep.

LOYALTY_PROGRAM

LOYALTY_PROGRAM & Niveaus

Puntenopbouw per scan (defaultChangeValue) met automatische niveauverhoging

STAMP_CARD

STAMP_CARD_ADD / DEDUCT

Houdt stempelposities bij (0..maximumValue) met onCap ('noop' | 'reset') en rewardClaimBehavior

PREPAID_CARD

PREPAID_CARD Grootboek

ISO 4217-grootboekadministratie voor prepaid in kleinste eenheden met disallowNegativeBalance-handhaving

VALID_ONCE_PER_DAY

VALID_ONCE_PER_DAY & RENEW

Tijdzonebewuste dagelijkse inchecklimieten en automatische verlenging van expirationDate bij scan

Pasbeheer

11 eindpunten
POSThttps://api.passinstance.com/api/v1/passesAPI-sleutel
Pasbeheer

Nieuwe pas uitgeven

Maak een nieuwe Apple Wallet- (.pkpass) en Google Wallet-pas aan op basis van een sjabloon met klantvelden, streepjescode en dynamische waarden.

Headers (kopteksten)2 vereist • 1 optioneel
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Vereist

Moet application/json zijn.

Voorbeeld: application/json
Queryparameters2 optioneel

Verzoekpayload met sjabloon-ID, uniek serienummer, klantveldwaarden en optionele streepjescodeconfiguratie.

Aanvraagtekst1 vereist • 15 optioneel
templateIdstring (UUID)
Vereist

Sjabloon-ID voor de pas.

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

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/upsert-by-external-idAPI-sleutel
Pasbeheer

Pas synchroniseren via externe ID (Upsert)

Maak of update op idempotente wijze een pas op basis van (customerId, externalId) voor naadloze CRM-, kassa- en e-commercesynchronisatie.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Verzoekpayload met templateId, externalId en dynamische pasattributen.

Aanvraagtekst2 vereist • 3 optioneel
templateIdstring (UUID)
Vereist

UUID van het doelsjabloon.

Voorbeeld: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
externalIdstring
Vereist

Stabiele externe CRM/POS-identificatie uniek binnen uw werkruimte.

Voorbeeld: CRM-CUST-99201

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/batch-pass-operations/createAPI-sleutel
Pasbeheer

Passen in bulk uitgeven

Geef meerdere wallet-passen uit in één atomaire batchbewerking met validatie en foutrapportage.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Verzoekpayload met een array van pasconfiguraties.

Aanvraagtekst1 vereist
passesarray of objects
Vereist

Array van pasitems met templateId, barcodeValue en additionalData.

Voorbeeld: [ { "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" } } ]

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/passesAPI-sleutel
Pasbeheer

Alle passen weergeven

Haal een gepagineerde lijst met passen op voor de geauthenticeerde klantwerkruimte met zoek- en statusfilters.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Queryparameters13 optioneel

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/passes/{id}API-sleutel
Pasbeheer

Pas ophalen

Haal volledige details, installatiestatus en downloadlinks op voor één pas via de unieke ID.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

De unieke UUID-identificatie van de pas.

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

Antwoordstatuscodes

PATCHhttps://api.passinstance.com/api/v1/passes/{id}API-sleutel
Pasbeheer

Pas bijwerken & pushmelding sturen

Werk dynamische velden, kleuren of streepjescode van een pas bij en verstuur automatisch APNs- en Google Wallet-pushmeldingen naar geïnstalleerde apparaten.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

De unieke UUID van de bij te werken pas.

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

Verzoekpayload-velden om op de pas te wijzigen. Geïnstalleerde apparaten ontvangen directe achtergrondupdates.

Aanvraagtekst13 optioneel

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/voiding/{id}/voidAPI-sleutel
Pasbeheer

Pas deactiveren

Markeer een pas als ongeldig of opnieuw geactiveerd in Apple Wallet en Google Wallet met directe pushsynchronisatie.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idUUID
Vereist

Unieke pasinstantie-ID om ongeldig te maken of te reactiveren.

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

Verzoekpayload voor het instellen van de status, auditreden en wallet-distributieopties.

Aanvraagtekst1 vereist • 1 optioneel
voidedboolean
Vereist

Stel in op true om de pas ongeldig te maken, of false om deze opnieuw te activeren.

Voorbeeld: true

Antwoordstatuscodes

DELETEhttps://api.passinstance.com/api/v1/passes/{id}API-sleutel
Pasbeheer

Pas verwijderen

Verwijder een pas definitief uit uw workspace en trek actieve Apple Wallet- en Google Wallet-installaties in.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

Unieke UUID van de te verwijderen pas.

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

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/useAPI-sleutel
Pasbeheer

Mechanica-actie uitvoeren

Voer een atomaire pasmechanica-operatie uit: INCREMENT (stempelkaart), DECREMENT, DEBIT (prepaid-tegoed), CREDIT of VALIDATE (eenmalige coupon).

Headers (kopteksten)3 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Vereist

Moet application/json zijn.

Voorbeeld: application/json
Idempotency-Keystring
Vereist

Verplichte UUID om atomaire uitvoering te garanderen en dubbele tegoed- of stempelafschrijvingen te voorkomen.

Voorbeeld: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Padparameters1 vereist
idstring (UUID)
Vereist

De unieke UUID van de te bewerken pas.

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

Verzoekpayload met de mechanica-actie, optioneel decimaal bedrag, operator-ID en locatie.

Aanvraagtekst1 vereist • 4 optioneel
actionstring (enum)
Vereist

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

Voorbeeld: INCREMENT

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/adjust-valueAPI-sleutel
Pasbeheer

Passaldo aanpassen

Schrijf saldo of spaarpunten handmatig bij (CREDIT) of af (DEBIT) op een pas met transactie-auditlogboek.

Headers (kopteksten)3 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Vereist

Moet application/json zijn.

Voorbeeld: application/json
Idempotency-Keystring
Vereist

Verplichte UUID om atomaire aanpassing te waarborgen en dubbel bijschrijven te voorkomen.

Voorbeeld: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Padparameters1 vereist
idUUID
Vereist

Doel-pasinstantie-ID.

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

Aanpassingspayload die CREDIT- of DEBIT-operatie, bedrag en reden specificeert.

Aanvraagtekst2 vereist • 2 optioneel
actionstring
Vereist

Transactieactie: 'CREDIT' om waarde toe te voegen, of 'DEBIT' om af te schrijven.

Voorbeeld: CREDIT
amountstring
Vereist

Numeriek bedrag om bij te schrijven of af te schrijven als tekenreeks.

Voorbeeld: 25.00

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/mechanics/redeemAPI-sleutel
Pasbeheer

Beloning van pasmechanica inwisselen

Wissel een verdiende loyaliteits- of stempelkaartbeloning op een pas in via de geconfigureerde pasmechaniek met idempotentiebescherming.

Headers (kopteksten)1 vereist • 1 optioneel
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx

Inwisselverzoek met passId, mechanicId en optioneel idempotencyKey.

Aanvraagtekst2 vereist • 3 optioneel
passIdstring (UUID)
Vereist

UUID van de pas waarmee de beloning wordt ingewisseld.

Voorbeeld: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
mechanicIdstring (UUID)
Vereist

UUID van de pasmechaniekregel gekoppeld aan het sjabloon.

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

Antwoordstatuscodes

Zoeken & analyse

4 eindpunten
GEThttps://api.passinstance.com/api/v1/passes/searchAPI-sleutel
Zoeken & analyse

Passen doorzoeken

Voer een full-text zoekopdracht uit op uitgegeven passen op serienummer, externe ID, e-mailadres, houdernaam of attributen.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Queryparameters1 vereist
querystring
Vereist

Zoekopdracht (maximaal 500 tekens).

Voorbeeld: Jane Doe

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/passes/statistics/{templateId}API-sleutel
Zoeken & analyse

Passtatistieken ophalen

Haal geaggregeerde uitgifte-, activatie-, wallet-installatie- en verzilveringsstatistieken op voor een specifiek passjabloon.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
templateIdstring (UUID)
Vereist

UUID van het doelsjabloon.

Voorbeeld: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Queryparameters2 optioneel

Antwoordstatuscodes

GEThttps://api.passinstance.com/api/v1/passes/{id}/historyAPI-sleutel
Zoeken & analyse

Passtatusgeschiedenis ophalen

Haal de chronologische auditgeschiedenis op van statuswijzigingen, punt-/saldoupdates, scans en ongeldigverklaringen van een pas.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

Pass UUID.

Voorbeeld: b1d972dc-eccf-4f87-ab21-25939d9213d8
Queryparameters1 optioneel

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/exportAPI-sleutel
Zoeken & analyse

Passen exporteren naar CSV

Stream een UTF-8 CSV-export (text/csv; charset=utf-8) van geselecteerde pasinstanties op basis van pas-ID.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

Verzoekpayload met 1 tot 2.000 pas-UUID's en het exportformaat.

Aanvraagtekst2 vereist
passIdsstring[] (UUID v4)
Vereist

Array van 1 tot 2.000 pas-UUID's om op te nemen in de CSV-export.

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

Uitvoerformaat voor export ('csv').

Voorbeeld: csv

Antwoordstatuscodes

Pasdistributie

4 eindpunten
GEThttps://api.passinstance.com/api/v1/passes/{id}/urisAPI-sleutel
Pasdistributie

Pasbron-URL's ophalen

Haal directe download- en distributie-URL's op voor een pas, inclusief gehoste PassFlow-pagina, .pkpass, Google Wallet-JWT en QR-code.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

Pass UUID.

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

Antwoordstatuscodes

GEThttps://api.passinstance.com/d/{slug}/infoOpenbaar
Pasdistributie

Gebrandete downloadpagina ophalen

Haal een openbare gebrandete pas-downloadpagina op via slug (zonder prefix GET /d/{slug}/info). Gebruik voor geauthenticeerd beheer GET /api/v1/download-pages/slug/{slug}.

Padparameters1 vereist
slugstring
Vereist

Unieke vanity-slug van de gehoste downloadpagina.

Voorbeeld: acme-vip-2026
Queryparameters2 optioneel

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/enabledownloadAPI-sleutel
Pasdistributie

Pasdownload inschakelen

Heractiveer of ontgrendel de downloadlink van een pas wanneer het sjabloon herhaalde downloads blokkeert.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

UUID van de pas waarvan de download moet worden ontgrendeld.

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

Optional timestamp specifying how long re-download remains unlocked.

Aanvraagtekst1 optioneel

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/{id}/send-emailAPI-sleutel
Pasdistributie

Pas per e-mail verzenden

Stuur een transactionele e-mail naar de pashouder met de directe installatielink voor Apple Wallet en Google Wallet.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idstring (UUID)
Vereist

UUID van de pas die per e-mail moet worden verzonden.

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

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

Aanvraagtekst4 optioneel

Antwoordstatuscodes

Pushmeldingen

2 eindpunten
POSThttps://api.passinstance.com/api/v1/passes/{id}/notificationsAPI-sleutel
Pushmeldingen

Vergrendelscherm-melding verzenden

Stuur direct een pushmelding op het vergrendelscherm naar een geïnstalleerde Apple Wallet- (.pkpass) of Google Wallet-pas. Gebruik voor geplande verzendingen of koptekstaanpassing POST /api/v1/push-notifications/passes/{id}.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1
Padparameters1 vereist
idUUID
Vereist

Unieke pasinstantie-UUID die de melding moet ontvangen.

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

Verzoekpayload met berichttekst en optionele kopteksttitel.

Aanvraagtekst1 vereist • 1 optioneel
messagestring
Vereist

Tekstbericht dat op het vergrendelscherm van de gebruiker wordt weergegeven.

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

Antwoordstatuscodes

POSThttps://api.passinstance.com/api/v1/passes/sendpushnotificationsAPI-sleutel
Pushmeldingen

Bulk-pushmeldingen verzenden

Stuur gelijktijdig een vergrendelscherm-pushmelding naar een geselecteerde lijst van pas-ID's via APNs en Google Wallet.

Headers (kopteksten)1 vereist
X-API-Keystring
Vereist

Geheime workspace-API-sleutel (pi_live_... of pi_test_...). U kunt ook Authorization: ApiKey <key> meesturen.

Voorbeeld: pi_live_98a7b6c5d4e3f2a1

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

Aanvraagtekst2 vereist
listOfPassesstring[] (UUID)
Vereist

Array van 1 tot 500 pas-UUID's.

Voorbeeld: ["b1d972dc-eccf-4f87-ab21-25939d9213d8"]
pushNotificationTextstring
Vereist

Vergrendelscherm-meldingstekst (ondersteunt dynamische variabelen zoals {holderName}).

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

Antwoordstatuscodes