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

REST API v1

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

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

Bearer

Create a pass template

Design and register a new reusable pass template with visual branding, barcode type, NFC configuration, and layout fields.

CreateTemplateDto configuration matching backend Swagger schema (/api/docs#/Templates/TemplateController_create).

Request Body6 required • 4 optional

namestring

Required

Template display name.

example: VIP Loyalty Card Template

descriptionstring

Required

Detailed description of the pass purpose and tier perks.

example: Exclusive loyalty and rewards card for VIP customers

organizationNamestring

Required

Organization / brand name printed on the card header.

example: Acme Rewards

kindstring (enum)

Required

storeCard, coupon, eventTicket, generic, boardingPass, or membership.

example: storeCard

statusstring (enum)

Required

ACTIVE, DRAFT, or ARCHIVED.

example: ACTIVE

preferredStyleSchemestring (enum)

Required

LIGHT or DARK.

example: DARK

Response Status Codes

201Created

ApiResponseDto<{ id: string }> returned upon template creation.

400Bad Request

DTO validation failure (missing required fields or invalid enum).

401Unauthorized

Missing or invalid Bearer authentication header.

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

Bearer

List all templates

Retrieve a paginated list of pass templates belonging to the authenticated workspace customer context.

Query Parameters3 optional

Response Status Codes

200OK

Paginated list of templates.

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

Bearer

Get template details

Retrieve full details of a pass template including colors, barcode settings, layout fields, and mechanic rules.

Path Parameters1 required

idUUID

Required

Unique template identifier.

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

Response Status Codes

200OK

ApiResponseDto<Template> with complete layout and branding configuration.

POST/templates

Templates

Request

curl -X POST https://api.passinstance.com/api/v1/templates \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Loyalty Card Template",
    "description": "Exclusive loyalty and rewards card for VIP customers",
    "organizationName": "Acme Rewards",
    "kind": "storeCard",
    "status": "ACTIVE",
    "preferredStyleScheme": "DARK",
    "colors": {
      "backgroundColor": "#1b2d3c",
      "foregroundColor": "#ffffff",
      "labelColor": "#7db4f0"
    },
    "barcode": {
      "format": "QR",
      "message": "https://passinstance.com/p/{serialNumber}",
      "altText": "Scan at checkout"
    },
    "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"
    },
    "fields": {
      "headers": [{ "key": "tier", "label": "TIER", "value": "Gold VIP" }],
      "primary": [{ "key": "memberName", "label": "MEMBER", "value": "{name}" }],
      "secondary": [{ "key": "points", "label": "POINTS", "value": "0" }],
      "auxiliary": [{ "key": "memberSince", "label": "MEMBER SINCE", "value": "2026" }],
      "back": [{ "key": "terms", "label": "Terms & Conditions", "value": "Valid at all participating stores." }]
    }
  }'

Response

CreatedApiResponseDto<{ id: string }> returned upon template creation.

{
  "success": true,
  "data": {
    "id": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b"
  },
  "description": "Template successfully created!",
  "errors": [],
  "statusCode": 201
}

Envelope: ApiResponseDto<T>HTTPS (TLS 1.3)