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.

System Architecture: CSV Batch Issuance & background job queue Worker Pipeline
Prerequisites Checklist
Prerequisites: Before starting a bulk CSV import job, verify the following requirements:
1. The target
Templatemust be inPUBLISHEDstatus.2. Your CSV file must be encoded in UTF-8 without malformed delimiters or unescaped quotes.
3. Include
phonecolumns 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
Template: Choose the target
PUBLISHED/PRODUCTIONtemplate (or open Passes -> Import directly from a template). -
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
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) toexternalIdorattributes.*keys. -
4
Sendout options (when enabled): Choose an Email/SMS delivery template if new passes should be sent automatically upon completion.
-
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.csvcontaining every generatedserialNumber,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):
| Step | HTTP Method & Endpoint | Purpose |
|---|---|---|
| 1. Sample CSV | GET /api/v1/batch-processing/templates/:templateId/sample-csv | Downloads a dynamic UTF-8 CSV header template tailored to the template's Custom Properties. |
| 2. Upload CSV | POST /api/v1/batch-processing | Uploads a multipart CSV file or JSON batch job definition (status: NEW / READY_TO_RUN). |
| 3. Auto-Map Columns | POST /api/v1/batch-processing/templates/:templateId/field-mapping-recommendations | Analyzes CSV header columns and returns confidence-scored attribute mapping suggestions. |
| 4. Save Mapping | PUT /api/v1/batch-processing/:id/field-mapping | Persists the confirmed CSV column-to-attribute mapping dictionary on the job. |
| 5. Dry-Run Validate | POST /api/v1/batch-processing/:id/validate | Performs a non-destructive validation pass over CSV rows and returns row-level warnings/errors. |
| 6. Start Worker | POST /api/v1/batch-processing/:id/start | Enqueues the background job queue background worker job (status: RUNNING) to issue passes asynchronously. |
| 7. Export Results | GET /api/v1/batch-processing/:id/result.csv | Streams 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
{
"csvHeaders": [
"Customer_ID",
"First_Name",
"Last_Name",
"Loyalty_Points",
"Card_Expiry"
]
}
HTTP Response (200 OK)
{
"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
{
"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
{
"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
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
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 astatuscolumn (SUCCESS,SKIPPED, orFAILED) and anerrorMessagecolumn explaining the failure (for example: "Missing required custom property: firstName", "Invalid ISO 8601 date format", or "Duplicate externalId"). -
3
Inspect Job Details via API: Call
GET /api/v1/batch-processing/:idwith your Bearer API key. The JSON response returns therequest payloadincludingtotalRows,processedRows,successfulRows,failedRows, and theerrorDetails[]array containing exact row indices and validation error codes. -
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
External ID Deduplication (
duplicateStrategy): If your template enforces external ID uniqueness and you setduplicateStrategytoSKIP, rows sharing anexternalIdwith 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, selectduplicateStrategy: "UPSERT_BY_EXTERNAL_ID". -
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
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
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 withPASS_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
.pkpasscryptographic 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
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, or365). When each pass is created via CSV import, API, or PassFlow form, Passinstance automatically computes:
expirationDate = issuanceTimestamp + (validityInDays * 86400 seconds).
-
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 systemexpirationDatefield during the Map Fields stage. -
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
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
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
Map Historical Identifiers to
externalId: Map your legacy card number or customer UUID to Passinstance's systemexternalId. This ensures 1:1 continuity and prevents duplicate records. -
4
Execute CSV Batch Ingestion: Upload the CSV using the 5-step wizard. Set the import strategy to
UPSERT_BY_EXTERNAL_IDso any pre-existing records update gracefully. -
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
Locate Event Cohort: In the Dashboard under Passes (
/passes), filter by the event template or use the Advanced Search Drawer to filter byexpirationDate < today. -
2
Select All Matching Passes: Use the
StickySelectionToolbarcheckbox to select the current view, then click the prompt to select all passes matching the filter across all pages. -
3
Execute Bulk Void / Deactivate: Click Bulk actions -> Deactivate / Void (
POST /api/v1/batch-pass-operations/deactivate). This sets pass status toVOIDED, 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
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 theirexternalIdfor 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.
