---
title: "Create scan"
method: POST
path: "/api/v1/scans"
tags: ["Scans"]
---

# Create scan

`POST /api/v1/scans`

## Request body

- CreateScan
  - `scan` ScanAttributes
    - `readerId` string — UUID of the reader that scanned the pass
    - `passId` string — ID (uuid or ext_id) of the pass that was scanned
    - `scanType` 'nfc' | 'barcode' — Type of scan: nfc or barcode
    - `loyalty` object
      - `balance` number — Balance to add or redeem. Can't be used together with balanceOverride.
      - `balanceOverride` number — Balance to override the pass balance with. Can't be used together with balance.
      - `message` string — Notification message to send after the operation

## Response `200`

OK

- InternalValidationResponse
  - `validationResponse` ValidationResponse
    - `status` 'successful' | 'failed' — Status of the validation: 'successful' or 'failed'
    - `statusDetail` string — Detailed status of the validation including error details
    - `readerInstructions` union
      - object
        - `message` string — Message to be displayed by the reader.
      - object
        - `VTAPaction` object
          - `led` string — Color of the LED to be displayed by the reader
          - `beep` string — Sound to be played by the reader
          - `message` string — Message to be displayed by the reader (not currently supported)
          - `success` boolean — Whether the scan was successfully validated
    - `loyalty` object
      - `balanceChange` string — Amount of points added or subtracted from the balance
      - `updatedBalance` string — Updated balance after the operation
      - `operation` string — Operation performed: 'add', 'redeem', 'stamp' or 'balanceOverride'
  - `scanInfo` ScanInfo
    - `scanId` string — UUID of the scan
    - `scanType` 'nfc' | 'barcode' — Type of scan: nfc or barcode
    - `scanValue` string — The raw value read by the reader during the scan. For NFC, this is the encoded NFC message. For barcodes, this is the encoded barcode value.
    - `validationType` 'internalValidation' | 'externalValidation' — Type of validation: 'internal' for PassEntry Validation or 'external' for Third-Party Validation.
    - `status` 'successful' | 'failed' — Status of the validation: 'successful' or 'failed'
    - `statusDetail` string — Detailed status of the validation including error details
    - `scannedAt` string — ISO8601 timestamp of the scan
    - `passId` string — UUID of the pass that was scanned
    - `passExtId` string — External ID of the pass that was scanned
    - `readerId` string — UUID of the reader that scanned the pass

## Other responses

- `401` — Error: Unauthorized
- `422` — Error: Unprocessable Entity

---

[API](https://skmtc.net/passentry/apis/passentry-api.md) · [All operations](https://skmtc.net/passentry/apis/passentry-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/passentry/passentry-api/versions/2c7dc0306b04/schema)