Skip to content
REST API Reference & SDKs

Passinstance Developer Documentation

Build high-volume Apple Wallet (.pkpass) and Google Wallet integrations. Issue, update, scan, and broadcast real-time lockscreen notifications via production-grade REST APIs.

Get API Keys
Live docs workbench — snippets update as you type
Core Concepts

Architecture & Pass Lifecycle

Pass management follows a 6-stage lifecycle: 1. Template (visual blueprint) → 2. Pass (cryptographically signed record) → 3. Distribution (secure passAccessUrl) → 4. Wallet Registration (device enrolls with APNs / Google Push) → 5. Live Updates (real-time lockscreen notifications) → 6. Scan & Redemption Telemetry (barcode validation & webhook stream).

1. TemplatePOST /api/v1/templates

Master layout, barcode type, branding colors, and schema fields

Core Concepts

Pass Mechanics & Loyalty Solutions Engine

Attach stateful business mechanics to templates across 8 turnkey solutions (Loyalty, Stamp Cards, Coupons, Gift/Prepaid Cards, Event Tickets, Memberships, Employee IDs, VIP Cards). Rules execute atomically on scan or API call.

LOYALTY_PROGRAM

LOYALTY_PROGRAM & Tiers

Points accrual per scan (defaultChangeValue) with automated tier upgrade progression

STAMP_CARD

STAMP_CARD_ADD / DEDUCT

Tracks stamp positions (0..maximumValue) with onCap ('noop' | 'reset') and rewardClaimBehavior

PREPAID_CARD

PREPAID_CARD Ledger

ISO 4217 minor-unit prepaid ledger accounting with disallowNegativeBalance enforcement

VALID_ONCE_PER_DAY

VALID_ONCE_PER_DAY & RENEW

Timezone-aware daily check-in limits and automatic expirationDate extension on scan

Pass Management

11 endpoints
POSThttps://api.passinstance.com/api/v1/passesAPI Key
Pass Management

Create Pass

Create and issue a new Apple Wallet (.pkpass) & Google Wallet pass from a template with customer fields, barcode, and dynamic values.

Headers2 required • 1 optional
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Required

Must be application/json.

Example: application/json
Query Parameters2 optional

Request payload containing template ID, unique serial number, customer field values, and optional barcode configuration.

Request Body1 required • 15 optional
templateIdstring (UUID)
Required

Template ID for the pass.

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

Response Status Codes

POSThttps://api.passinstance.com/api/v1/passes/upsert-by-external-idAPI Key
Pass Management

Create or Update Pass by External ID

Idempotently create or update a pass keyed on (customerId, externalId) for seamless CRM, POS, and e-commerce synchronization.

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1

Request payload containing templateId, externalId, and dynamic pass attributes.

Request Body2 required • 3 optional
templateIdstring (UUID)
Required

Target template UUID.

Example: tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
externalIdstring
Required

Stable external CRM/POS identifier unique within your workspace.

Example: CRM-CUST-99201

Response Status Codes

POSThttps://api.passinstance.com/api/v1/batch-pass-operations/createAPI Key
Pass Management

Batch Create Passes

Issue multiple wallet passes in an atomic batch operation with validation and failure reporting.

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1

Request payload containing an array of pass configurations.

Request Body1 required
passesarray of objects
Required

Array of pass items with templateId, barcodeValue, and additionalData.

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

Response Status Codes

GEThttps://api.passinstance.com/api/v1/passesAPI Key
Pass Management

List Passes by Template

Retrieve a paginated list of passes for the authenticated customer workspace with search and status filters.

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1
Query Parameters13 optional

Response Status Codes

GEThttps://api.passinstance.com/api/v1/passes/{id}API Key
Pass Management

Get Pass Details

Get full details, installation status, and download links for a single pass by its unique ID.

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1
Path Parameters1 required
idstring (UUID)
Required

The unique UUID identifier of the pass.

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

Response Status Codes

PATCHhttps://api.passinstance.com/api/v1/passes/{id}API Key
Pass Management

Update Pass

Update pass dynamic fields, colors, or barcode and automatically broadcast APNs and Google Wallet push notifications to installed devices.

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1
Path Parameters1 required
idstring (UUID)
Required

The unique UUID of the pass to update.

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

Request payload fields to modify on the pass. Installed devices will receive instant background updates.

Request Body13 optional

Response Status Codes

POSThttps://api.passinstance.com/api/v1/passes/voiding/{id}/voidAPI Key
Pass Management

Void Pass

Mark a pass as voided or reactivated across Apple Wallet and Google Wallet with instant push propagation.

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1
Path Parameters1 required
idUUID
Required

Unique pass instance ID to void or reactivate.

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

Request payload controlling voided state, audit reason, and wallet propagation options.

Request Body1 required • 1 optional
voidedboolean
Required

Set to true to void the pass, or false to reactivate it.

Example: true

Response Status Codes

DELETEhttps://api.passinstance.com/api/v1/passes/{id}API Key
Pass Management

Delete Pass

Delete a pass record by UUID and revoke its active wallet installations.

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1
Path Parameters1 required
idstring (UUID)
Required

Unique pass UUID to delete.

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

Response Status Codes

POSThttps://api.passinstance.com/api/v1/passes/{id}/useAPI Key
Pass Management

Update Pass Loyalty or Balance

Execute an atomic pass mechanic operation: INCREMENT (stamp card), DECREMENT, DEBIT (prepaid balance), CREDIT, or VALIDATE (single-use coupon).

Headers3 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Required

Must be application/json.

Example: application/json
Idempotency-Keystring
Required

Mandatory UUID to ensure atomic execution and prevent duplicate balance or stamp deductions.

Example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Path Parameters1 required
idstring (UUID)
Required

The unique UUID of the pass to operate upon.

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

Request payload containing the mechanic action, optional decimal amount, operator ID, and location.

Request Body1 required • 4 optional
actionstring (enum)
Required

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

Example: INCREMENT

Response Status Codes

POSThttps://api.passinstance.com/api/v1/passes/{id}/adjust-valueAPI Key
Pass Management

Adjust Pass Stored Value

Manually credit (add) or debit (deduct) stored value or reward points on a pass with transaction audit logging.

Headers3 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Typestring
Required

Must be application/json.

Example: application/json
Idempotency-Keystring
Required

Mandatory UUID to ensure atomic adjustment and prevent double-crediting.

Example: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
Path Parameters1 required
idUUID
Required

Target pass instance ID.

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

Adjustment payload specifying CREDIT or DEBIT operation, amount, and reason.

Request Body2 required • 2 optional
actionstring
Required

Transaction action: 'CREDIT' to add value, or 'DEBIT' to deduct value.

Example: CREDIT
amountstring
Required

Numeric amount to credit or debit as a string.

Example: 25.00

Response Status Codes

POSThttps://api.passinstance.com/api/v1/mechanics/redeemAPI Key
Pass Management

Redeem Pass Reward

Redeem an earned loyalty or stamp card reward on a pass using its configured pass mechanic with idempotency protection.

Headers1 required • 1 optional
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_xxxxxxxxxxxxxxxxxxxxxxxx

Request payload specifying passId, mechanicId, and optional idempotencyKey.

Request Body2 required • 3 optional
passIdstring (UUID)
Required

UUID of the pass redeeming the reward.

Example: pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
mechanicIdstring (UUID)
Required

UUID of the pass mechanic rule attached to the template.

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

Response Status Codes

Search & Analytics

4 endpoints
GEThttps://api.passinstance.com/api/v1/passes/searchAPI Key
Search & Analytics

Search Passes

Search passes across your workspace by holder name, email, serial number, external ID, or custom attribute value.

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1
Query Parameters1 required
querystring
Required

Search query string (up to 500 characters).

Example: Jane Doe

Response Status Codes

GEThttps://api.passinstance.com/api/v1/passes/statistics/{templateId}API Key
Search & Analytics

Get Pass Statistics

Retrieve time-series pass issuance, active installation, and status increment statistics for a template.

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1
Path Parameters1 required
templateIdstring (UUID)
Required

Target template UUID.

Example: 8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b
Query Parameters2 optional

Response Status Codes

GEThttps://api.passinstance.com/api/v1/passes/{id}/historyAPI Key
Search & Analytics

Get Pass Status History

Retrieve the chronological lifecycle, wallet installation, scan, delivery, and balance activity timeline for a pass.

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1
Path Parameters1 required
idstring (UUID)
Required

Pass UUID.

Example: b1d972dc-eccf-4f87-ab21-25939d9213d8
Query Parameters1 optional

Response Status Codes

POSThttps://api.passinstance.com/api/v1/passes/exportAPI Key
Search & Analytics

Export Passes to CSV

Stream a UTF-8 CSV export (text/csv; charset=utf-8) of selected pass instances by pass ID.

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1

Request payload specifying 1 to 2,000 pass UUIDs and the export format.

Request Body2 required
passIdsstring[] (UUID v4)
Required

Array of 1 to 2,000 pass UUIDs to include in the CSV export.

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

Export output format ('csv').

Example: csv

Response Status Codes

Pass Delivery

4 endpoints
GEThttps://api.passinstance.com/api/v1/passes/{id}/urisAPI Key
Pass Delivery

Get Pass Resource URLs

Retrieve the canonical distribution URLs for a pass, including the hosted download page link, direct Apple Wallet (.pkpass) URL, Google Wallet save link, and QR code URL.

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1
Path Parameters1 required
idstring (UUID)
Required

Pass UUID.

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

Response Status Codes

GEThttps://api.passinstance.com/d/{slug}/infoPublic
Pass Delivery

Get Download Page Details

Resolve a public branded pass download page payload by slug (prefix-free GET /d/{slug}/info). For authenticated management lookup by slug, use GET /api/v1/download-pages/slug/{slug}.

Path Parameters1 required
slugstring
Required

Unique vanity slug of the hosted download page.

Example: acme-vip-2026
Query Parameters2 optional

Response Status Codes

POSThttps://api.passinstance.com/api/v1/passes/{id}/enabledownloadAPI Key
Pass Delivery

Enable Pass Download

Temporarily re-enable downloading for an already-installed pass when template re-download lock is active (defaults to a 10-minute window if enableDownloadUntil is omitted).

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1
Path Parameters1 required
idstring (UUID)
Required

Pass UUID to unlock for download.

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

Optional timestamp specifying how long re-download remains unlocked.

Request Body1 optional

Response Status Codes

POSThttps://api.passinstance.com/api/v1/passes/{id}/send-emailAPI Key
Pass Delivery

Send Pass by Email

Deliver a pass installation link directly to one or more recipient email addresses using your workspace email configuration.

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1
Path Parameters1 required
idstring (UUID)
Required

Pass UUID to deliver via email.

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

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

Request Body4 optional

Response Status Codes

Push Notifications

2 endpoints
POSThttps://api.passinstance.com/api/v1/passes/{id}/notificationsAPI Key
Push Notifications

Send Pass Push Notification

Send an immediate push notification and lock-screen message to an installed Apple Wallet (.pkpass) or Google Wallet pass. For scheduled sends or custom notification headers, use POST /api/v1/push-notifications/passes/{id}.

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1
Path Parameters1 required
idUUID
Required

Unique pass instance UUID to receive the notification.

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

Request payload containing message body and optional header title.

Request Body1 required • 1 optional
messagestring
Required

Text message to display on the user's lock-screen.

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

Response Status Codes

POSThttps://api.passinstance.com/api/v1/passes/sendpushnotificationsAPI Key
Push Notifications

Send Bulk Push Notifications

Send a personalized lock-screen push notification to up to 500 pass UUIDs in a single request and receive per-pass delivery results.

Headers1 required
X-API-Keystring
Required

Workspace secret API key (pi_live_... or pi_test_...). You may alternatively send Authorization: ApiKey <key>.

Example: pi_live_98a7b6c5d4e3f2a1

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

Request Body2 required
listOfPassesstring[] (UUID)
Required

Array of 1 to 500 pass UUIDs.

Example: ["b1d972dc-eccf-4f87-ab21-25939d9213d8"]
pushNotificationTextstring
Required

Lock-screen notification message (supports dynamic placeholders like {holderName}).

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

Response Status Codes