> ## Documentation Index > Fetch the complete documentation index at: https://docs.passlet.io/llms.txt > Use this file to discover all available pages before exploring further. # Record a scan > Validates a pass and records the scan attempt. Identify the pass by `qrPayload` (the scanned QR content) or `passId`. The outcome is returned as `result` (`accepted`, `duplicate`, `unknown`, `ambiguous`, `denied` or `reversal`) plus a machine-readable `reasonCode`; non-accepted attempts are recorded and still return `200`. An `ambiguous` result includes `candidates[]` so the operator can pick a pass and re-submit with `passId`. Use `scanContextKey` to scope duplicate detection to a context (e.g. one event day), and pass a unique `externalRef` to make retries idempotent (replays return `idempotentReplay: true`). Requires the `scans:write` scope on the access token. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/scans openapi: 3.1.0 info: title: Passlet API (Public) version: 0.1.0 description: >- Public integration API for Passlet — every route callable with a `plt_*` access token. Each operation lists the required access-token scope. license: name: UNLICENSED identifier: UNLICENSED servers: - url: https://api.passlet.io description: Production security: [] paths: /v1/scans: post: tags: - scans summary: Record a scan description: >- Validates a pass and records the scan attempt. Identify the pass by `qrPayload` (the scanned QR content) or `passId`. The outcome is returned as `result` (`accepted`, `duplicate`, `unknown`, `ambiguous`, `denied` or `reversal`) plus a machine-readable `reasonCode`; non-accepted attempts are recorded and still return `200`. An `ambiguous` result includes `candidates[]` so the operator can pick a pass and re-submit with `passId`. Use `scanContextKey` to scope duplicate detection to a context (e.g. one event day), and pass a unique `externalRef` to make retries idempotent (replays return `idempotentReplay: true`). Requires the `scans:write` scope on the access token. operationId: postV1Scans requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RecordScanRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PublicRecordScanResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiError' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ApiError' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ApiError' '503': description: Service unavailable content: application/json: schema: $ref: '#/components/schemas/ApiError' security: - bearerAuth: [] components: schemas: RecordScanRequest: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: qrPayload: type: string minLength: 1 maxLength: 2048 passId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Pass identifier projectId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' scanContextKey: type: string minLength: 1 maxLength: 128 validityDate: type: string pattern: ^\d{4}-\d{2}-\d{2}$ scannedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO 8601 timestamp deviceId: type: string maxLength: 128 externalRef: type: string minLength: 1 maxLength: 255 context: type: object properties: gate: type: string maxLength: 64 lane: type: string maxLength: 64 location: type: string maxLength: 255 sessionId: type: string maxLength: 255 note: type: string maxLength: 500 additionalProperties: {} PublicRecordScanResponse: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: result: type: string enum: - accepted - duplicate - unknown - ambiguous - denied - reversal reasonCode: anyOf: - type: string enum: - valid - stale_identifier - already_scanned - not_active - expired - revoked - wrong_scope - not_valid_context - out_of_window - quota_exhausted - cooldown - no_match - multiple_matches - type: 'null' scan: anyOf: - type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ passId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Pass identifier - type: 'null' projectId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' templateVersionId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' redemptionSnapshot: anyOf: - type: object properties: windows: minItems: 1 maxItems: 366 type: array items: type: object properties: start: type: string pattern: >- ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d(:[0-5]\d(\.\d+)?)?(Z|[+-]([01]\d|2[0-3]):[0-5]\d)$ end: type: string pattern: >- ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d(:[0-5]\d(\.\d+)?)?(Z|[+-]([01]\d|2[0-3]):[0-5]\d)$ maxUses: type: integer minimum: 1 maximum: 100000 additionalProperties: false maxUses: type: integer minimum: 1 maximum: 100000 perPeriod: type: object properties: unit: type: string enum: - day - week - month count: type: integer minimum: 1 maximum: 100000 timezone: type: string pattern: >- ^(?:UTC|GMT|[A-Za-z_]+\/[A-Za-z0-9_+-]+(?:\/[A-Za-z0-9_+-]+)?)$ description: IANA timezone identifier required: - unit - count - timezone additionalProperties: false minIntervalMinutes: type: integer minimum: 1 maximum: 527040 activation: type: object properties: basis: type: string const: firstScan validForHours: type: integer minimum: 1 maximum: 87840 required: - basis - validForHours additionalProperties: false additionalProperties: false - type: 'null' scanContextKey: anyOf: - type: string maxLength: 128 - type: 'null' scannedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO 8601 timestamp recordedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO 8601 timestamp result: type: string enum: - accepted - duplicate - unknown - ambiguous - denied - reversal reasonCode: anyOf: - type: string enum: - valid - stale_identifier - already_scanned - not_active - expired - revoked - wrong_scope - not_valid_context - out_of_window - quota_exhausted - cooldown - no_match - multiple_matches - type: 'null' reversesScanId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' deviceId: anyOf: - type: string maxLength: 128 - type: 'null' source: type: string enum: - mobile_app - api - manual_admin matchedBy: anyOf: - type: string enum: - scanner_qr_payload - pass_id - identifier - apple_serial - google_object_id - type: 'null' context: type: object propertyNames: type: string additionalProperties: {} externalRef: anyOf: - type: string maxLength: 255 - type: 'null' reason: anyOf: - type: string maxLength: 500 - type: 'null' matchedCount: type: integer minimum: 0 maximum: 9007199254740991 createdAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO 8601 timestamp required: - id - passId - projectId - templateVersionId - redemptionSnapshot - scanContextKey - scannedAt - recordedAt - result - reasonCode - reversesScanId - deviceId - source - matchedBy - context - externalRef - reason - matchedCount - createdAt additionalProperties: false - type: 'null' pass: anyOf: - type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Pass identifier externalPassId: type: string label: type: string status: type: string enum: - QUEUED - ISSUING - ISSUED - VOID - FAILED - EXPIRED projectId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' projectName: anyOf: - type: string - type: 'null' templateVersionId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' templateName: anyOf: - type: string - type: 'null' templateVersionNumber: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' expiresAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO 8601 timestamp - type: 'null' acceptedScanCount: type: integer minimum: 0 maximum: 9007199254740991 lastAcceptedScanAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO 8601 timestamp - type: 'null' scanContextKey: anyOf: - type: string - type: 'null' contextAcceptedScanCount: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' contextLastAcceptedScanAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO 8601 timestamp - type: 'null' photoUrl: anyOf: - type: string format: uri - type: 'null' variables: type: object propertyNames: type: string additionalProperties: {} description: >- Stored pass input variables used for scanner/operator inspection required: - id - externalPassId - label - status - projectId - projectName - templateVersionId - templateName - templateVersionNumber - expiresAt - acceptedScanCount - lastAcceptedScanAt - scanContextKey - contextAcceptedScanCount - contextLastAcceptedScanAt - photoUrl - variables additionalProperties: false - type: 'null' candidates: type: array items: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: Pass identifier externalPassId: type: string label: type: string status: type: string enum: - QUEUED - ISSUING - ISSUED - VOID - FAILED - EXPIRED projectId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' projectName: anyOf: - type: string - type: 'null' templateVersionId: anyOf: - type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ - type: 'null' templateName: anyOf: - type: string - type: 'null' templateVersionNumber: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' expiresAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO 8601 timestamp - type: 'null' acceptedScanCount: type: integer minimum: 0 maximum: 9007199254740991 lastAcceptedScanAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO 8601 timestamp - type: 'null' scanContextKey: anyOf: - type: string - type: 'null' contextAcceptedScanCount: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' contextLastAcceptedScanAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ description: ISO 8601 timestamp - type: 'null' photoUrl: anyOf: - type: string format: uri - type: 'null' variables: type: object propertyNames: type: string additionalProperties: {} description: >- Stored pass input variables used for scanner/operator inspection required: - id - externalPassId - label - status - projectId - projectName - templateVersionId - templateName - templateVersionNumber - expiresAt - acceptedScanCount - lastAcceptedScanAt - scanContextKey - contextAcceptedScanCount - contextLastAcceptedScanAt - photoUrl - variables additionalProperties: false message: type: string priorScanCount: default: 0 type: integer minimum: 0 maximum: 9007199254740991 isFirstScan: default: false type: boolean idempotentReplay: default: false type: boolean required: - result - reasonCode - scan - pass - message - priorScanCount - isFirstScan - idempotentReplay additionalProperties: false ApiError: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: errorCode: type: string enum: - UNAUTHORIZED - FORBIDDEN - TOKEN_EXPIRED - TOKEN_INVALID - CSRF_TOKEN_INVALID - TENANT_EXPIRED - TENANT_NOT_FOUND - ORGANIZATION_REQUIRED - TENANT_SUSPENDED - VALIDATION_ERROR - INVALID_INPUT - MISSING_REQUIRED_FIELD - INVALID_FORMAT - NOT_FOUND - PASS_NOT_FOUND - TEMPLATE_NOT_FOUND - WEBHOOK_NOT_FOUND - NOTIFICATION_NOT_FOUND - CONFLICT - VERSION_CONFLICT - DUPLICATE_PASS - IDEMPOTENCY_CONFLICT - TEMPLATE_VERSION_NOT_NEWER - SCAN_REVERSAL_WINDOW_EXPIRED - WEBHOOK_MANAGED_EXTERNALLY - PASS_ALREADY_ISSUED - PASS_ALREADY_VOIDED - PASS_NOT_ISSUED - PASS_ISSUING_FAILED - APPLE_SIGNING_FAILED - APPLE_APNS_FAILED - GOOGLE_API_FAILED - GOOGLE_JWT_FAILED - PROVIDER_UNAVAILABLE - LINK_EXPIRED - LINK_REVOKED - LINK_INVALID - TOKEN_SIGNATURE_INVALID - TOKEN_CLOCK_SKEW - RATE_LIMITED - TOO_MANY_REQUESTS - INTERNAL_ERROR - SERVICE_UNAVAILABLE - JOB_FAILED description: Machine-readable error code message: type: string description: Human-readable error message correlationId: type: string description: Request correlation ID for debugging details: description: Additional error details type: object propertyNames: type: string additionalProperties: {} required: - errorCode - message - correlationId additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: plt_ description: >- Passlet access token (`plt_*`) sent as `Authorization: Bearer ` or `X-API-Key`. Authorized scopes are listed per operation under `x-required-scopes`. ````