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/Passes

REST API v1

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

POSThttps://api.passinstance.com/api/v1/passes

Bearer

Issue a new 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

Authorizationstring

Required

Bearer <token> or X-API-Key header.

example: Bearer eyJhbGciOiJIUzI1NiIsInR5c...

Content-Typestring

Required

Must be application/json.

example: application/json

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

Request Body1 required • 10 optional

templateIdstring (UUID)

Required

Template ID for the pass.

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

Response Status Codes

201Created

ApiResponseDto<Pass> with passAccessUrl and downloadUrl.

400Bad Request

Validation failure on CreatePassDto.

401Unauthorized

Missing or invalid Bearer token / API key.

GEThttps://api.passinstance.com/api/v1/passes

Bearer

List all passes

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

Query Parameters5 optional

Response Status Codes

200OK

PaginatedApiResponseDto with list of passes.

GEThttps://api.passinstance.com/api/v1/passes/{id}

Bearer

Retrieve a pass

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

Path Parameters1 required

idstring (UUID)

Required

The unique UUID identifier of the pass.

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

Response Status Codes

200OK

ApiResponseDto<PassDto> with complete pass payload.

404Not Found

Pass does not exist or belongs to another customer workspace.

PATCHhttps://api.passinstance.com/api/v1/passes/{id}

Bearer

Update pass & push notify

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

Path Parameters1 required

idstring (UUID)

Required

The unique UUID of the pass to update.

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

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

Request Body6 optional

Response Status Codes

200OK

ApiResponseDto<PassDto> with updated pass data.

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

Bearer

Apply mechanic action

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

Path Parameters1 required

idstring (UUID)

Required

The unique UUID of the pass to operate upon.

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

UsePassDto 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

200OK

ApiResponseDto with execution details and new balance/stamp count.

400Bad Request

Insufficient balance or invalid action.

Related:Adjust pass stored value

POSThttps://api.passinstance.com/api/v1/passes/{id}/adjust-value

Bearer

Adjust pass stored value

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

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

200OK

ApiResponseDto returning scan/transaction record with previous and resulting value.

Related:Apply mechanic action

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

Bearer

Deactivate a pass

Mark a pass as voided/deactivated across Apple Wallet and Google Wallet with instant push sync.

Path Parameters1 required

idUUID

Required

Unique pass instance ID to deactivate.

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

Response Status Codes

200OK

ApiResponseDto<PassDto> with voided=true status.

POST/passes

Passes

Request

curl -X POST https://api.passinstance.com/api/v1/passes \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -d '{
    "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b",
    "serialNumber": "MEMBER-2024-8891",
    "name": "Acme VIP Customer Pass",
    "organizationName": "Acme Rewards",
    "backgroundColor": "#1b2d3c",
    "foregroundColor": "#ffffff",
    "labelColor": "#7db4f0",
    "barcode": {
      "value": "PI-8891-JD-VIP",
      "alternativeText": "8891-VIP"
    },
    "images": {
      "icon": "https://assets.passinstance.com/media/icon.png",
      "logo": "https://assets.passinstance.com/media/logo.png",
      "strip": "https://assets.passinstance.com/media/strip.png"
    },
    "relevantDate": "2026-08-25T18:00:00.000Z"
  }'

Response

CreatedApiResponseDto<Pass> with passAccessUrl and downloadUrl.

{
  "success": true,
  "data": {
    "id": "pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b",
    "serialNumber": "MEMBER-2024-8891",
    "name": "Acme VIP Customer Pass",
    "organizationName": "Acme Rewards",
    "backgroundColor": "#1b2d3c",
    "foregroundColor": "#ffffff",
    "labelColor": "#7db4f0",
    "barcode": {
      "value": "PI-8891-JD-VIP",
      "alternativeText": "8891-VIP"
    },
    "images": {
      "icon": "https://assets.passinstance.com/media/icon.png",
      "logo": "https://assets.passinstance.com/media/logo.png",
      "strip": "https://assets.passinstance.com/media/strip.png"
    },
    "relevantDate": "2026-08-25T18:00:00.000Z",
    "status": "ACTIVE",
    "voided": false,
    "downloadUrl": "https://passinstance.com/p/pass_9a8b7c6d",
    "passAccessUrl": "https://passinstance.com/p/pass_9a8b7c6d",
    "createdAt": "2026-08-21T20:30:00.000Z",
    "updatedAt": "2026-08-21T20:30:00.000Z"
  },
  "description": "Pass created successfully",
  "errors": [],
  "statusCode": 201
}

Envelope: ApiResponseDto<T>HTTPS (TLS 1.3)