Overview
Every validation request processed by Passinstance generates an immutable audit record containing the evaluated decision, reasonCode, step-by-step ruleTrace, operator metadata, and pre/post pass balances. You can review scan histories visually in the Dashboard under Scanner (/scanner), inspect individual scan receipts, query idempotent operation outcomes, perform non-mutating pass lookups, or stream full CSV exports for accounting reconciliation.
Important: Read-only lookup routes (
GET /api/v1/scans/pass?barcode=...orGET /api/v1/scans/pass/:barcodeValue) allow POS terminals and customer service desks to inspect pass status,externalId, tier, and balance without recording a scan event, incrementing counters, or voiding single-use vouchers.
Architecture & Audit Lookup Flow
Scan Lookup, Audit & Export Endpoints
| Method | Endpoint | Auth / Guard | Description |
|---|---|---|---|
| GET | /api/v1/scans/pass | x-scanner-key | Read-only pass lookup via ?barcode=... query parameter (recommended for URL-shaped payloads). Does not create a scan record. |
| GET | /api/v1/scans/pass/:barcodeValue | x-scanner-key | Read-only pass lookup by path parameter returning IPassLookupResponse. |
| GET | /api/v1/scans/result/:scanId | x-scanner-key | Retrieves the complete result and ruleTrace of a specific scan by its UUID scanId. |
| GET | /api/v1/scans/operations/:idempotencyKey | x-scanner-key | Retrieves the stored request payload receipt for a previously submitted x-idempotency-key. |
| GET | /api/v1/validation/scans | Workspace JWT / API Key | Lists paginated workspace scan logs for the Dashboard (/scanner). |
| GET | /api/v1/validation/scans/:scanId | Workspace JWT / API Key | Fetches a single workspace scan audit record and trace for Dashboard inspection. |
| GET | /api/v1/validation/configs/:id/scans/export | Workspace JWT / API Key | Exports scan history scoped to a specific ScannerConfiguration as CSV. |
| GET | /api/v1/validation/scans/export | Workspace JWT / API Key | Exports workspace-wide scan and redemption logs as CSV. |
| GET | /api/v1/validation/scan-results/export/csv | Workspace JWT / API Key | Streams the full scan audit trail including rule evaluation outcomes (text/csv). |
Decision Outcomes (request payload) vs. Persisted scan status
The API returns a high-level decision enum (SUCCESS | FAILED | ALREADY_USED | ALREADY_VOIDED | EXPIRED | INVALID | PENDING) in request payload, while persisting the granular scan status (SUCCESS | FAILED | PENDING | INVALID | EXPIRED | ALREADY_USED | ALREADY_VOIDED | CHECK_IN_SUCCESS | CHECK_OUT_SUCCESS | ALREADY_CHECKED_IN | ALREADY_CHECKED_OUT) on the underlying scan record:
Decision (request payload) | Status | Typical reasonCode | Recommended Staff / POS Action |
|---|---|---|---|
SUCCESS | ACCEPTED | RULE_ACCEPTED | Grant entry (CHECK_IN_SUCCESS / CHECK_OUT_SUCCESS), apply discount, or confirm balance deduction. |
ALREADY_VOIDED | REJECTED | PASS_VOIDED_AFTER_SCAN | Deny redemption; pass was already consumed in a prior single-use scan. |
ALREADY_USED | REJECTED | ONCE_PER_DAY_LIMIT_REACHED | Inform passholder that their daily or check-in (ALREADY_CHECKED_IN / ALREADY_CHECKED_OUT) allowance has been used. |
EXPIRED | REJECTED | PASS_EXPIRED | Direct customer to renew their membership or claim an active campaign offer. |
FAILED | REJECTED | OUT_OF_BALANCE / GEOFENCE_MISMATCH | Check ruleTrace details (e.g., insufficient prepaid balance or wrong checkpoint). |
INVALID | REJECTED | PASS_NOT_FOUND / INVALID_NONCE | Barcode does not belong to this workspace/template or anti-replay nonce expired. |
PENDING | PENDING | OPERATOR_INPUT_REQUIRED | Prompt cashier to complete required fields in scanForm (such as transaction amount). |
Inspecting a Completed Scan (GET /api/v1/scans/result/:scanId)
{
"scanId": "scan_01hxyz7712ab",
"idempotencyKey": "idem_reg04_20261116_0091",
"timestamp": "2026-11-16T09:42:11.000Z",
"decision": "ALREADY_USED",
"status": "REJECTED",
"reasonCode": "ONCE_PER_DAY_LIMIT_REACHED",
"ruleTrace": [
{ "rule": "PassStatusRule", "passed": true, "durationMs": 1 },
{ "rule": "ExpirationRule", "passed": true, "durationMs": 1 },
{
"rule": "OncePerDayRule",
"passed": false,
"reasonCode": "ONCE_PER_DAY_LIMIT_REACHED",
"lastScanAt": "2026-11-16T06:15:04.000Z",
"durationMs": 3
}
],
"passSnapshot": {
"id": "pass_gym_8821",
"templateId": "tmpl_gym_member",
"serialNumber": "PI-GYM-8821",
"externalId": "crm_member_8821",
"status": "ACTIVE"
}
}
Non-Mutating Pass Lookup (GET /api/v1/scans/pass)
Before submitting a mutating scan or POS debit, a terminal can query the current state of a pass via GET /api/v1/scans/pass?barcode=PI-GFT-550192 (prefer ?barcode= over the path param whenever barcodes contain slashes or URLs):
/api/v1/scans/pass?barcode=PI-GFT-550192
{
"passId": "pass_gft_550192",
"templateId": "tmpl_giftcard_eur",
"templateName": "Retail Gift Card",
"serialNumber": "PI-GFT-550192",
"externalId": "shopify_cust_550192",
"status": "ACTIVE",
"storedValue": "75.00",
"expirationDate": "2027-12-31T23:59:59.000Z",
"isExpired": false,
"isVoided": false,
"barcodeValue": "PI-GFT-550192",
"attributes": {
"holderName": "Elena Rostova"
},
"checkedAt": "2026-11-16T10:15:00.000Z"
}
Exporting Scan Logs to CSV
For shift reconciliation, finance audits, or BI ingestion, export scan histories directly as UTF-8 CSV streams (Content-Type: text/csv; charset=utf-8):
-
Single Configuration Export:
GET /api/v1/validation/configs/:id/scans/export?from=2026-11-01&to=2026-11-16 -
All Configurations Export:
GET /api/v1/validation/scans/export?templateId=tmpl_loyalty_01 -
Full Audit Results Export:
GET /api/v1/validation/scan-results/export/csv
See Scanning & Redemption Reports and Data Exports & Reporting for analytics aggregation options.
