Skip to content
Help Center Guide · Pass IssuanceOnboarding Phase 5
8 min readVerified 2026-11-16

Bulk Pass Creation

Upload CSV files via Batch Operations or FTP/SFTP Import, map columns to custom properties, and inspect job progress.

In This Guide

Interactive UI Walkthroughs

Open in 6-Phase Onboarding Guide

Inspect exact dashboard panels, controls, and zoomed callouts related to this guide.

Zoomed UI focus
Key UI elements

Batch Import jobs panel (Zoomed)

Launch a 'New import job' from the template Overview and monitor Running, Failed, and Completed CSV batch processing runs.

Overview

When onboarding hundreds or hundreds of thousands of cardholders simultaneously, Passinstance provides an asynchronous, fault-tolerant CSV batch ingestion pipeline powered by Batch Jobs API (/api/v1/batch-processing) and in-memory cache-backed background job queue worker queues. Operators can upload UTF-8 spreadsheets through the Dashboard (Batch Operations -> Import Passes), trigger automated FTP/SFTP Imports, or orchestrate the 6-stage CSV pipeline programmatically via REST API.

Batch import job counters and new import CTA
Batch import job counters and new import CTA

System Architecture: CSV Batch Issuance & background job queue Worker Pipeline

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
CSV BATCH ISSUANCE & ASYNC WORKER PIPELINE
STAGE 01 DASHBOARD CSV UPLOAD / API (Batch Jobs API)
1
GET/api/v1/batch-processing/templates/:templateId/sample-csv
2
POST/api/v1/batch-processing (Multipart UTF-8 CSV Upload)
3
POST/api/v1/batch-processing/templates/:templateId/field-mapping-recommendations
STAGE 02 SCHEMA MAPPING & PRE-FLIGHT DRY-RUN VALIDATION
4
PUT/api/v1/batch-processing/:id/field-mapping (Bind CSV headerskeys)
5
POST/api/v1/batch-processing/:id/validate
Checks required Custom Properties, ISO dates, numeric types & externalIds
Reports row-by-row syntax or schema errors prior to database mutation
STAGE 03 ASYNC WORKER PIPELINE (in-memory cache)
Streams validated CSV chunks in bounded transactions
Generates Pass records, serialNumber, authenticationToken & smart links
Compiles downloadable result ledger: GET/api/v1/batch-processing/:id/result.csv

Prerequisites Checklist

Prerequisites: Before starting a bulk CSV import job, verify the following requirements:

1. The target Template must be in PUBLISHED status.

2. Your CSV file must be encoded in UTF-8 without malformed delimiters or unescaped quotes.

3. Include email and/or phone columns if you plan to dispatch Pass Download Links automatically via Delivery Center campaigns after generation.

4. Configure your External ID source in Template Settings (externalId) if you want idempotent deduplication across repeated imports.

Step-by-Step CSV Import Workflow (Bulk Pass Wizard)

In the Dashboard under Batch -> Batch Processing (/batch-processing), the wizard guides operators through five stages (Template -> Upload CSV -> Map Fields -> Sendout options (optional) -> Process):

  1. 1
    Template: Choose the target PUBLISHED / PRODUCTION template (or open Passes -> Import directly from a template).
  2. 2
    Upload CSV: Drop a UTF-8 CSV file or download the dynamic Sample CSV (GET /api/v1/batch-processing/templates/:templateId/sample-csv) pre-populated with headers matching your template's Custom Properties and system fields (externalId, expirationDate, etc.).
  3. 3
    Map Fields: Review automatic confidence-scored column mapping recommendations (POST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendations) linking headers (e.g. Customer_ID, First_Name) to externalId or attributes.* keys.
  4. 4
    Sendout options (when enabled): Choose an Email/SMS delivery template if new passes should be sent automatically upon completion.
  5. 5
    Process: Validate and start the background job queue job (batch job status: NEW, READY_TO_RUN, INTEGRATION_MAPPING_COMPLETE, SENDOUT_PENDING, RUNNING, COMPLETED, COMPLETED_WITH_ERRORS, FAILED, CANCELLED, PAUSED), then download /result.csv containing every generated serialNumber, externalId, bundleId, and download link.

Batch Processing REST API Reference (Batch Jobs API)

All batch CSV job endpoints are mounted under /api/v1/batch-processing (supporting batch job type: CREATE_PASSES, UPDATE_PASSES, DELETE_PASSES, IMPORT_DATA, EXPORT_DATA, MIGRATION and batch data source: CSV_UPLOAD, API, SEGMENT, QUERY, MANUAL):

StepHTTP Method & EndpointPurpose
1. Sample CSVGET /api/v1/batch-processing/templates/:templateId/sample-csvDownloads a dynamic UTF-8 CSV header template tailored to the template's Custom Properties.
2. Upload CSVPOST /api/v1/batch-processingUploads a multipart CSV file or JSON batch job definition (status: NEW / READY_TO_RUN).
3. Auto-Map ColumnsPOST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendationsAnalyzes CSV header columns and returns confidence-scored attribute mapping suggestions.
4. Save MappingPUT /api/v1/batch-processing/:id/field-mappingPersists the confirmed CSV column-to-attribute mapping dictionary on the job.
5. Dry-Run ValidatePOST /api/v1/batch-processing/:id/validatePerforms a non-destructive validation pass over CSV rows and returns row-level warnings/errors.
6. Start WorkerPOST /api/v1/batch-processing/:id/startEnqueues the background job queue background worker job (status: RUNNING) to issue passes asynchronously.
7. Export ResultsGET /api/v1/batch-processing/:id/result.csvStreams a CSV report appending generated passId, serialNumber, download links, and row status.

Example: Request Field Mapping Recommendations

POST /api/v1/batch-processing/templates/tmpl_01hxyz987654321/field-mapping-recommendations Headers: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "csvHeaders": [
    "Customer_ID",
    "First_Name",
    "Last_Name",
    "Loyalty_Points",
    "Card_Expiry"
  ]
}

HTTP Response (200 OK)

JSON
{
  "success": true,
  "data": {
    "recommendations": [
      { "csvColumn": "Customer_ID", "targetField": "externalId", "confidence": 0.98, "matchType": "SYSTEM" },
      { "csvColumn": "First_Name", "targetField": "attributes.firstName", "confidence": 0.96, "matchType": "CUSTOM_PROPERTY" },
      { "csvColumn": "Last_Name", "targetField": "attributes.lastName", "confidence": 0.96, "matchType": "CUSTOM_PROPERTY" },
      { "csvColumn": "Loyalty_Points", "targetField": "attributes.pointsBalance", "confidence": 0.89, "matchType": "CUSTOM_PROPERTY" },
      { "csvColumn": "Card_Expiry", "targetField": "expirationDate", "confidence": 0.94, "matchType": "SYSTEM" }
    ]
  },
  "statusCode": 200
}

Example: Confirm Field Mapping & Validate Job

PUT /api/v1/batch-processing/job_batch_77123/field-mapping Headers: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "duplicateStrategy": "UPSERT_BY_EXTERNAL_ID",
  "mappings": {
    "Customer_ID": "externalId",
    "First_Name": "attributes.firstName",
    "Last_Name": "attributes.lastName",
    "Loyalty_Points": "attributes.pointsBalance",
    "Card_Expiry": "expirationDate"
  }
}

Then validate and start the background job queue worker:

POST /api/v1/batch-processing/job_batch_77123/validate POST /api/v1/batch-processing/job_batch_77123/start

JSON
{
  "success": true,
  "data": {
    "id": "job_batch_77123",
    "status": "RUNNING",
    "jobType": "CREATE_PASSES",
    "dataSource": "CSV_UPLOAD",
    "totalRows": 5000,
    "processedRows": 0
  },
  "statusCode": 200
}

Troubleshooting & Frequently Asked Questions

How do I check when a bulk processing job fails?

When an asynchronous CSV batch import encounters an issue, inspect the job status and logs through either the Dashboard or the REST API:

  1. 1
    Dashboard Job Drawer: Navigate to Batch -> Batch Processing (/batch-processing). Completed jobs with errors display a badge labeled Completed with errors (COMPLETED_WITH_ERRORS), while halted jobs display Failed (FAILED).
  2. 2
    Download Error Log: Click on the job card and select Download Error CSV or fetch GET /api/v1/batch-processing/:id/result.csv. The resulting spreadsheet contains every source CSV row appended with a status column (SUCCESS, SKIPPED, or FAILED) and an errorMessage column explaining the failure (for example: "Missing required custom property: firstName", "Invalid ISO 8601 date format", or "Duplicate externalId").
  3. 3
    Inspect Job Details via API: Call GET /api/v1/batch-processing/:id with your Bearer API key. The JSON response returns the request payload including totalRows, processedRows, successfulRows, failedRows, and the errorDetails[] array containing exact row indices and validation error codes.
  4. 4
    Pre-Flight Validation Check: Before enqueueing a 100k-row job, always call POST /api/v1/batch-processing/:id/validate. This dry-run step verifies header mappings and attribute schemas without creating database records, reporting syntax errors before workers start.

Why did my bulk processing run create fewer passes than rows in the file?

If your input CSV contained 5,000 rows but the job reports only 4,820 passes created, check the following verified platform behaviors:

  1. 1
    External ID Deduplication (duplicateStrategy): If your template enforces external ID uniqueness and you set duplicateStrategy to SKIP, rows sharing an externalId with an existing active pass in your workspace (or repeated earlier within the same CSV file) are skipped to prevent duplicate issuance. To overwrite existing passes instead, select duplicateStrategy: "UPSERT_BY_EXTERNAL_ID".
  2. 2
    Empty or Trailing Blank Rows: Spreadsheet editors (Excel, Google Sheets) often export trailing blank rows with trailing commas. The Passinstance CSV parser automatically discards empty rows without incrementing the generated pass counter.
  3. 3
    Pre-Validation Attribute Rejections: Rows containing invalid data types (such as non-numeric text in a number attribute, invalid email syntax, or unparseable date strings) fail individual row validation and are logged to the failure ledger without halting the entire job.
  4. 4
    Active Pass Quota Exhaustion (PASS_LIMIT_REACHED): If your workspace reaches 100% of its subscription plan's active pass limit during processing, subsequent rows will fail with PASS_LIMIT_REACHED. Check Company Settings -> Usage & Billing to verify your remaining quota.

Is a wait of several hours normal for bulk processing?

  • Standard Processing Speeds: background job queue worker queues in Passinstance typically generate between 500 and 2,000 passes per minute depending on whether dynamic Apple Wallet .pkpass cryptographic signatures and barcode images are generated synchronously or deferred to download time. A batch of 10,000 passes usually completes within 5 to 15 minutes.
  • When Several Hours Is Normal:

- Massive Ingestion Volumes: Extremely large imports (100,000 to 500,000+ passes) take several hours to ensure database connection pools and in-memory cache queues remain stable without throttling your workspace. - Immediate Outbound Sendouts: If you attached an Email or SMS delivery campaign to the batch job, outbound emails are throttled according to managed email delivery sending rate quotas (e.g., 14 to 50 emails/second) and custom SMTP server connection limits to protect your domain reputation.

  • When a Job Is Stalled or Needs Action:

- If a job remains in NEW or READY_TO_RUN for hours, the worker was never started. Click Start Job in the Dashboard or call POST /api/v1/batch-processing/:id/start. - If the job status is PAUSED, resume execution via POST /api/v1/batch-processing/:id/resume.

Can a pass expire a fixed number of days after issuance?

Yes. Passinstance supports both fixed calendar date expiration and dynamic rolling validity periods:

  1. 1
    Dynamic Rolling Duration (validityInDays): In the Visual Editor under Validity & Expiration, set the Expiration Strategy to Dynamic Duration and specify the number of days (e.g., 30, 90, or 365). When each pass is created via CSV import, API, or PassFlow form, Passinstance automatically computes:

expirationDate = issuanceTimestamp + (validityInDays * 86400 seconds).

  1. 2
    Per-Row Expiration Override: If individual customers have unique contract end dates, map a CSV column containing ISO 8601 timestamps (e.g. 2027-06-30T23:59:59Z) directly to the system expirationDate field during the Map Fields stage.
  2. 3
    Post-Issuance Extension: You can extend or modify expiration dates across thousands of live passes at any time using Bulk Operations.

How do I migrate existing customer data from another wallet provider or CRM?

Migrating from legacy systems (such as Airship, PassKit, Braze, or an internal database) to Passinstance is seamless:

  1. 1
    Export Legacy Records: Export your existing customer database to a UTF-8 CSV including member names, contact details, points balances, tier status, and historical card numbers.
  2. 2
    Set Up the Target Template: In Passinstance, build a matching template. Configure your custom properties (e.g., memberId, pointsBalance, tier) and barcode symbology (QR, Aztec, Code 128, or PDF417).
  3. 3
    Map Historical Identifiers to externalId: Map your legacy card number or customer UUID to Passinstance's system externalId. This ensures 1:1 continuity and prevents duplicate records.
  4. 4
    Execute CSV Batch Ingestion: Upload the CSV using the 5-step wizard. Set the import strategy to UPSERT_BY_EXTERNAL_ID so any pre-existing records update gracefully.
  5. 5
    Seamless Cardholder Transition: If your organization maintains the same Apple Pass Type Identifier and signing certificate, customers will receive updated passes without needing to delete their existing wallet passes. Alternatively, dispatch new smart download links via Delivery Center using the {passDownloadUrl} placeholder.

How do I clean up passes after an event ends?

After a concert, sports game, or seasonal campaign concludes, maintain workspace hygiene and free active quota:

  1. 1
    Locate Event Cohort: In the Dashboard under Passes (/passes), filter by the event template or use the Advanced Search Drawer to filter by expirationDate < today.
  2. 2
    Select All Matching Passes: Use the StickySelectionToolbar checkbox to select the current view, then click the prompt to select all passes matching the filter across all pages.
  3. 3
    Execute Bulk Void / Deactivate: Click Bulk actions -> Deactivate / Void (POST /api/v1/batch-pass-operations/deactivate). This sets pass status to VOIDED, renders an invalidated barcode banner on the lock screen, and disables scanner redemption while preserving historical scan records and check-in attendance data for compliance reporting.
  4. 4
    Soft Delete (DELETING -> SOFT): If you wish to purge the expired event passes from your active dashboard view, select Bulk actions -> Delete. Soft-deleted passes do not count toward your subscription active pass limits and free their externalId for future use, while remaining accessible in historical audit exports.

For direct JSON array batch operations without CSV files, see Bulk Operations. To distribute newly imported passes via email, see Email & SMS Delivery.

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.