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.
Issues 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-id
Idempotently creates or updates a pass matched by (templateId, externalId) (request payload).
GET
/api/v1/passes
Lists pass instances with pagination, status filtering (pass status), and search queries.
GET
/api/v1/passes/:id
Retrieves full details, dynamic attributes, externalId, serialNumber, and registration status.
PATCH / PUT
/api/v1/passes/:id
Updates dynamic fields, tier, or expiration date and pushes live updates to installed wallets.
POST
/api/v1/passes/voiding/:id/void
Voids a pass (request payload + VoidingReason) and dispatches a silent voided: true push update.
DELETE
/api/v1/passes/:id
Soft-deletes a pass and revokes active wallet installations.
POST
/api/v1/passes/export
Exports filtered pass records as a UTF-8 CSV or JSON download job.
POST
/api/v1/batch-pass-operations/create
Runs synchronous/queued bulk pass creation via Batch Operations API (also /update, /upsert, /activate, /deactivate, /delete).
POST
/api/v1/batch-processing
Submits an asynchronous large CSV/JSON bulk job tracked via Batch Processing API.
2. Templates & Mechanics
Verb
Path
Description
GET
/api/v1/templates
Lists workspace pass templates, pass kinds (PassKind), bundleId certificate bindings, and publication states.
GET
/api/v1/templates/:id
Returns template schema, visual layout configuration, and active mechanics.