Skip to content
Help Center Guide · Developer API
5 min readVerified 2026-11-16

API Reference

Navigate the full REST endpoint catalog across Passes, Templates, Scanner, Delivery, Webhooks, and Batch Operations.

In This Guide

Overview

The Passinstance REST API is organized into modular domain controllers mounted primarily under /api/v1 (with dedicated prefix-free mounts for POS /v1/pos/*, Pull Webhooks /webhook-payload, Inbound Vendor Webhooks /webhooks/*, Health probes /health/*, and Smart Links /s/:token & /d/:slug). Every endpoint uses standard HTTP verbs (GET, POST, PUT, PATCH, DELETE), enforces workspace tenant isolation from your API credential, and returns a deterministic JSON payload (API response (T) on workspace APIs).

Prerequisites: Generate a workspace API key (pi_live_... or pi_test_...) with the required API_KEY_SCOPE_VALUES (passes, templates, scans, webhooks, analytics, or *) at /settings/workspace/developer/api-credentials before calling /api/v1/* routes. Interactive OpenAPI documentation is available at GET /api/public/docs and /docs.

Request & Response Lifecycle

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
REST API REQUEST & ENVELOPE LIFECYCLE
PARTICIPATING SYSTEM ACTORS
P1 External Integration
P2 Passinstance /api/v1/*
P3 Wallet Providers & DB
STEP 1 REQUEST / ACTION POST/api/v1/passes
STEP 2 REQUEST / ACTION Validate DTO & Tenant Scope
STEP 3 REQUEST / ACTION Sign .pkpass (bundleId)
›
idempotencyKey
›
& Build Google Wallet JWT
STEP 4 RESPONSE 201 Created
›
API response (request payload)
STEP 5 REQUEST / ACTION PATCH/api/v1/passes/:id
STEP 6 REQUEST / ACTION Commit Field Update
STEP 7 RESPONSE 200 OK
›
7. Enqueue APNs & Google Push

Domain-by-Domain REST Endpoint Catalog

1. Passes, Upserts & Batch Operations

VerbPathDescription
POST/api/v1/passesIssues a pass instance (request payload: templateId, optional externalId, idempotencyKey, attributes) signed with the template certificate (bundleId = Apple passTypeIdentifier).
POST/api/v1/passes/upsert-by-external-idIdempotently creates or updates a pass matched by (templateId, externalId) (request payload).
GET/api/v1/passesLists pass instances with pagination, status filtering (pass status), and search queries.
GET/api/v1/passes/:idRetrieves full details, dynamic attributes, externalId, serialNumber, and registration status.
PATCH / PUT/api/v1/passes/:idUpdates dynamic fields, tier, or expiration date and pushes live updates to installed wallets.
POST/api/v1/passes/voiding/:id/voidVoids a pass (request payload + VoidingReason) and dispatches a silent voided: true push update.
DELETE/api/v1/passes/:idSoft-deletes a pass and revokes active wallet installations.
POST/api/v1/passes/exportExports filtered pass records as a UTF-8 CSV or JSON download job.
POST/api/v1/batch-pass-operations/createRuns synchronous/queued bulk pass creation via Batch Operations API (also /update, /upsert, /activate, /deactivate, /delete).
POST/api/v1/batch-processingSubmits an asynchronous large CSV/JSON bulk job tracked via Batch Processing API.

2. Templates & Mechanics

VerbPathDescription
GET/api/v1/templatesLists workspace pass templates, pass kinds (PassKind), bundleId certificate bindings, and publication states.
GET/api/v1/templates/:idReturns template schema, visual layout configuration, and active mechanics.
POST/api/v1/templates/:id/publishPublishes draft changes (request payload) and dispatches batched push updates (GET .../publish-risk-check beforehand).
GET/api/v1/templates/:templateId/attributesLists dynamic field keys and types required when issuing passes (supports OAuth templates:read).
POST/api/v1/mechanics/redeemRedeems an unlocked loyalty or stamp card reward (request payload: UUID passId, mechanicId).
GET/api/v1/mechanics/:mechanicId/passes/:passId/ledgerReturns the transaction ledger for a pass's stored-value or loyalty mechanic (GET /api/v1/balance-changes for tenant feed).

3. Scans, Devices & POS Validation

VerbPathDescription
POST/api/v1/scansEvaluates a barcode/NFC scan against the 14-rule Validation Rules Engine (ScanMode & scan status).
POST/api/v1/scans/prepareIssues a short-lived cryptographic scan nonce for anti-replay protection.
GET/api/v1/scans/passRead-only pass lookup by ?barcode=... (or path param GET /api/v1/scans/pass/:barcodeValue).
POST/api/v1/scans/pass/:passId/useDirectly executes a request payload action (INCREMENT, DECREMENT, DEBIT, CREDIT, VALIDATE, NOOP, SET).
GET/api/v1/scans/result/:scanIdRetrieves the audit record and ruleTrace of a completed scan.
GET/api/v1/scans/offline-datasetCursor-paginated pass snapshot (offline scan dataset) for offline handheld scanners.
POST/v1/pos/redeemPrefix-free POS endpoint executing atomic PosOperation commands (DISCOUNT, ADD_POINTS, DEDUCT_VALUE, ADD_STAMPS, VOID, CUSTOM).
POST/api/v1/reader/redeemProcesses hardware NFC reader redemptions authenticated via X-Reader-Secret (POST /api/v1/reader/validate for entry validation).

4. Push Notifications, Webhooks & Workflows

VerbPathDescription
POST/api/v1/push-notifications/templates/:id/sendDispatches an immediate notification to all devices registered for a template (request payload on /passes/:id/schedule).
POST/api/v1/push-notifications/segmentationTargets a filtered pass segment (request payload) with localized push updates.
POST/api/v1/push-notifications/batchSends batch notifications across pass lists or CSV uploads (request payload).
GET / POST/api/v1/webhooksRetrieves webhook overview or manages outgoing HTTPS push webhook endpoints (/api/v1/webhooks/subscriptions).
GET/webhook-payloadPrefix-free Pull API (GET /api/v3/webhook-payload also supported) polling unacknowledged events for firewall-restricted receivers.
POST/webhook-payload/acknowledgePrefix-free acknowledgment ({ upTo, webhookId }, or POST /api/v3/webhook-payload/acknowledge).
GET / POST/api/v1/workflowsLists or creates automated event-driven workflows (Workflow Engine API, alongside /api/v1/automations).

5. Analytics, Billing & Privacy Governance

VerbPathDescription
GET/api/v1/analyticsMulti-series telemetry report (passes, registrations, walletAppsShare; see /api/v1/analytics/passes/overview).
GET/api/v1/analytics/wallet-installationsDevice-level and pass-level Apple Wallet vs. Google Wallet installation matrix (request payload).
GET/api/v1/billing/subscriptionReturns active subscription plan, billing cycle, and renewal status.
GET/api/v1/billing/invoices/:id/downloadStreams PDF tax invoice (application/pdf).
POST/api/v1/customer/:customerId/privacy-settings/data-subject-exportGenerates a GDPR-compliant personal data archive for a passholder.

Standard API response (T) Envelope & Status Codes

Success Envelope (200 OK / 201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "pass_01hxyz8821",
    "templateId": "tmpl_vip_member",
    "serialNumber": "PI-VIP-8821",
    "externalId": "crm_cust_44910",
    "bundleId": "pass.com.passinstance.vip",
    "status": "ACTIVE",
    "passAccessUrl": "https://api.passinstance.com/s/vip-8821-x9a2"
  },
  "meta": {
    "requestId": "req_99481a2b7c",
    "timestamp": "2026-11-16T10:10:00.000Z"
  }
}

Standard HTTP Status Codes

Status CodeMeaningResolution
200 OK / 201 CreatedRequest succeeded synchronously.Read result payload from data.
400 Bad RequestDTO validation failure or violated domain constraint.Inspect errorCode, messageKey, and details array.
401 UnauthorizedMissing, expired, or invalid API key / Bearer token.Verify x-api-key or Authorization header (and pi_test_ vs pi_live_ workspace match).
403 ForbiddenValid key lacks required scope (e.g., missing 'passes') or tenant access.Check assigned scopes via GET /api/v1/api-keys.
404 Not FoundTarget resource ID does not exist in the authenticated workspace.Verify UUID / serialNumber / externalId and workspace environment.
409 ConflictDuplicate externalId, serialNumber, or concurrent idempotency collision.Use /api/v1/passes/upsert-by-external-id or supply a unique idempotencyKey.
429 Too Many Requests1-second burst or quota rate limit exceeded.Respect Retry-After and RateLimit-Reset response headers.

Browse full schema definitions in the Developer Documentation Hub and API Overview & Authentication.

Related Product & Developer Documentation

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.