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

Developer Docs/Push & Delivery

REST API v1

All API Reference Passes Templates Scanner & Devices Push & Delivery Webhooks Batch Operations

Core Concepts

Architecture & Pass Lifecycle

Pass management follows a 5-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).

1. Template

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

2. Pass Instance

Signed digital pass containing member data and unique serial number

3. Distribution (passAccessUrl)

HTTPS web landing page for adding pass into Apple or Google Wallet

4. Wallet Registration

Device registers push token; pass is actively installed on device

5. Real-Time Updates

Server broadcasts background APNs / Google push on state change

Platform Guides

Apple Wallet vs. Google Wallet Matrix

Passinstance automatically signs .pkpass bundles for iOS and generates signed JWT objects for Google Wallet. Assets, barcodes, and lockscreen triggers adapt seamlessly across both operating systems.

Apple Wallet Signing

Cryptographic PKCS#7 signature using Apple Pass Type ID certificate

Google Wallet Issuer

Google Cloud Service Account REST JWT payload

Hero / Strip Artwork

Apple: 375×123 px (3:1) | Google: 1032×336 px (approx 3:1)

Universal Barcodes

QR Code and PDF417 supported natively on both mobile platforms

POSThttps://api.passinstance.com/api/v1/passes/{id}/notifications

Bearer

Send lock-screen notification

Send a real-time push notification and lock-screen message to an installed Apple Wallet (.pkpass) or Google Wallet pass.

Path Parameters1 required

idUUID

Required

Unique pass instance ID to receive the notification.

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

SendPushNotificationDto containing message body and optional header title.

Request Body1 required • 1 optional

messagestring

Required

Text message to display on the user's lock-screen (max 255 characters).

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

Response Status Codes

200OK

ApiResponseDto confirming delivery status to registered Apple & Google devices.

POST/passes/{id}/notifications

Push & Delivery

Request

curl -X POST https://api.passinstance.com/api/v1/passes/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/notifications \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Your reward points have been updated! You now have 250 points.",
    "title": "Points Update"
  }'

Response

OKApiResponseDto confirming delivery status to registered Apple & Google devices.

{
  "success": true,
  "data": {
    "id": "del_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "passId": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "status": "sent",
    "message": "Your reward points have been updated! You now have 250 points.",
    "title": "Points Update",
    "metrics": {
      "totalDevices": 1,
      "successCount": 1,
      "failureCount": 0
    }
  },
  "description": "Notification processed successfully",
  "errors": [],
  "statusCode": 200
}

Envelope: ApiResponseDto<T>HTTPS (TLS 1.3)