List scans

GET

api

scans

List scans

curl --request GET \
  --url https://api.passentry.com/api/v1/scans \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "id": "0195ebee-62d2-7a98-83b7-1fe98465a401",
      "type": "scan",
      "attributes": {
        "scanType": "barcode",
        "scanValue": "factory_scan_value",
        "validationType": "internalValidation",
        "status": "failed",
        "statusDetail": "Pass is not active",
        "scannedAt": "2025-01-13T13:00:00Z"
      },
      "relationships": {
        "pass": {
          "data": {
            "id": "7882e98b-0eba-4625-9223-5221eb8dad7f",
            "type": "pass"
          }
        },
        "reader": {
          "data": {
            "id": "south-gate-1",
            "type": "reader"
          }
        }
      }
    },
    {
      "id": "0195ebee-62d1-72b3-bd35-a101b24878a9",
      "type": "scan",
      "attributes": {
        "scanType": "nfc",
        "scanValue": "factory_scan_value",
        "validationType": "internalValidation",
        "status": "failed",
        "statusDetail": "Pass is not active",
        "scannedAt": "2025-01-13T13:02:00Z"
      },
      "relationships": {
        "pass": {
          "data": {
            "id": "7882e98b-0eba-4625-9223-5221eb8dad7f",
            "type": "pass"
          }
        },
        "reader": {
          "data": {
            "id": "south-gate-1",
            "type": "reader"
          }
        }
      }
    },
    {
      "id": "0195ebee-62d0-77cb-b8b1-0a81f99efc2c",
      "type": "scan",
      "attributes": {
        "scanType": "barcode",
        "scanValue": "factory_scan_value",
        "validationType": "internalValidation",
        "status": "failed",
        "statusDetail": "Pass is not active",
        "scannedAt": "2025-01-13T13:05:00Z"
      },
      "relationships": {
        "pass": {
          "data": {
            "id": "7882e98b-0eba-4625-9223-5221eb8dad7f",
            "type": "pass"
          }
        },
        "reader": {
          "data": {
            "id": "south-gate-1",
            "type": "reader"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "7882e98b-0eba-4625-9223-5221eb8dad7f",
      "type": "pass",
      "attributes": {
        "downloadUrl": "https://www.example.com?pass=7882e98b-0eba-4625-9223-5221eb8dad7f",
        "passType": "generic",
        "createdAt": "2022-01-01T00:00:00Z",
        "status": "issued",
        "extId": "4312d68fd106e3e6dd15",
        "passTemplateUuid": "7f24e7371e67c7af15103815",
        "passTemplateName": "PassEntry Event",
        "nfc": null,
        "barcode": {},
        "passContent": {
          "fullName": "John Johnson"
        }
      }
    },
    {
      "id": "south-gate-1",
      "type": "reader",
      "attributes": {
        "name": "South Gate Reader",
        "readerType": "PassentryReader",
        "loggedIn": false,
        "qrEnabled": false,
        "mifareClassicNfcEnabled": false,
        "scanEnabled": true,
        "redeemEnabled": false,
        "addPointsEnabled": false,
        "ndefTagScanningEnabled": false,
        "lastSeenAt": "2020-03-13T13:00:00Z"
      }
    }
  ],
  "meta": {
    "totalCount": 3,
    "resultsPerPage": 25,
    "currentPage": 1,
    "totalPages": 1
  },
  "links": {
    "first": null,
    "prev": null,
    "next": null,
    "last": null
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

perPage

integer

Record limiter per page. Default is 100

entity

string

Filter by entity uuid

readerId

string

Filter by reader uuid

passId

string

Filter by pass uuid or ext_id

validationType

enum<string>

Filter by validation type

Available options:

internalValidation,

externalValidation

scanType

enum<string>

Filter by scan type

Available options:

nfc,

barcode

status

enum<string>

Filter by status

Available options:

successful,

failed

eventId

string

Filter by event uuid

passTemplateName

string

Filter by pass template name

groupTag

string

Filter by group tag

groupTags[]

string[]

Filter by multiple group tags. Use array notation: groupTags[]=tag1&groupTags[]=tag2

createdAfter

string

Filter by created after. Format: ISO 8601

createdBefore

string

Filter by created before. Format: ISO 8601

Response

Successful

data

object[]

Show child attributes

data.id

string

Auto-generated UUID of the scan

Example:

"0194a887-f880-703f-b8cf-16c1ea804b08"

data.type

string

Example:

"scan"

data.attributes

object

Show child attributes

data.attributes.scanType

enum<string>

Type of scan: nfc or barcode

Available options:

nfc,

barcode

data.attributes.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.

data.attributes.validationType

enum<string>

Type of validation: 'internal' for PassEntry Validation or 'external' for Third-Party Validation.

Available options:

internalValidation,

externalValidation

data.attributes.status

enum<string>

Status of the validation: 'successful' or 'failed'

Available options:

successful,

failed

data.attributes.statusDetail

string

Detailed status of the validation including error details

data.attributes.scannedAt

string

ISO8601 timestamp of the scan

data.relationships

object

Relationships to other resources.

Show child attributes

data.relationships.pass

object

Show child attributes

data.relationships.pass.data

object

Show child attributes

data.relationships.pass.data.id

string

Auto-generated UUID of the pass

Example:

"e89b1330fc391ec89656f3c664318cff8805471e"

data.relationships.pass.data.type

string

Example:

"pass"

data.relationships.reader

object

Show child attributes

data.relationships.reader.data

object

Show child attributes

data.relationships.reader.data.id

string

Reader ID

Example:

"CC202952"

data.relationships.reader.data.type

string

Example:

"reader"

meta

object

Show child attributes

meta.successfulScans

integer

Total count of successful scans

meta.failedScans

integer

Total count of failed scans

meta.readersCount

integer

Total count of readers

meta.totalCount

integer

Total count of records returned

meta.resultsPerPage

integer

Number of records returned per page. Set using the perPage query parameter.

meta.currentPage

integer

Index of current page

meta.totalPages

integer

Total pages returned

included

object[]

Option 1
Option 2

Show child attributes

included.id

string

Auto-generated UUID of the pass

Example:

"e89b1330fc391ec89656f3c664318cff8805471e"

included.type

string

Example:

"pass"

included.attributes

object

Show child attributes

included.attributes.downloadUrl

string

Unique download URL of the pass

included.attributes.passType

enum<string>

Pass Type

Available options:

generic,

eventTicket,

storeCard,

transit

included.attributes.deviceType

enum<string>

Available options:

android,

iphone

included.attributes.createdAt

string

In ISO8601 format, UTC

included.attributes.status

enum<string>

Pass Status

Available options:

issued,

active,

removed,

deactivated

included.attributes.extId

string | null

Pass External ID

included.attributes.groupTag

string | null

Tag used for grouping passes

included.attributes.groupTags

array | null

Tag used for grouping passes

included.attributes.addedAt

string | null

When pass has been added to wallet by the user. In ISO8601 format, UTC

included.attributes.removedAt

string | null

When pass has been removed from wallet by the user. In ISO8601 format, UTC

included.attributes.deactivatedAt

string | null

When pass has been deactivated. In ISO8601 format, UTC

included.attributes.expiresAt

string | null

Pass will expire at this time. In ISO8601 format, UTC

included.attributes.passTemplateUuid

string

UUID of corresponding pass template

included.attributes.passTemplateName

string

Name of corresponding pass template

included.attributes.nfc

string | null

If present, the NFC message to be conveyed when the pass is tapped

included.attributes.barcode

object

If present, the barcode type and value

Show child attributes

included.attributes.barcode.enabled

boolean

Barcode enabled

included.attributes.barcode.type

enum<string>

Barcode type

Available options:

qr,

code128,

aztec,

pdf417

included.attributes.barcode.source

enum<string>

Barcode source

Available options:

uuid,

extId,

custom

included.attributes.barcode.value

string

Barcode value

Example:

"123abcd"

included.attributes.barcode.displayText

boolean

If true, display the barcode value as text on the pass

included.attributes.latestMessage

string | null

If present, the last push message sent to the pass

included.attributes.passContent

object

Show child attributes

included.attributes.passContent.{key}

The templateKey identifies a pass field in the template (using the template field ID). Its value must be an object with a required value string, and may optionally include a localisation object that maps locale codes to translated values.

Example:

{
  "eventName": {
    "value": "Summer Festival",
    "localisation": {
      "es": { "value": "Festival de Verano" },
      "fr": { "value": "Festival d'Été" }
    }
  }
}

included.attributes.passDesign

object

Pass design values, present if pass template has been overridden for this pass, or if 'includePassDesign' query param is set to true

Show child attributes

included.attributes.passDesign.backgroundColor

string

Pass background color in hex format

Example:

"#EFEFEF"

included.attributes.passDesign.labelColor

string

Pass label color in hex format. Only valid for iphone passes

Example:

"#EFEFEF"

included.attributes.passDesign.textColor

string

Pass text color in hex format. Only valid for iphone passes

Example:

"#EFEFEF"

included.attributes.passDesign.bannerImageUrl

string

URL of pass banner image

included.attributes.passDesign.logoImageUrl

string

URL of pass logo image

included.attributes.locations

object[]

Locations, present if 'includeLocations' query param is set to true

Show child attributes

included.attributes.locations.name

string

Name of the location, used for display purposes only

Example:

"West Entrance"

included.attributes.locations.latitude

number<double>

Latitude of the location

Example:

51.54321132456805

included.attributes.locations.longitude

number<double>

Longitude of the location

Example:

-0.022901231803803924

included.attributes.locations.radius

integer

default:100

Effective geofence radius of the location in meters. Maximum is 1000 for eventTicket passes, 100 for other pass types. Currently only available on Apple devices, due to Android device restrictions.

Required range: 10 <= x <= 1000

Example:

90

included.attributes.locations.message

string

Message to display when user enters geofence. Currently only available on Apple devices, due to Android device restrictions.

Example:

"Welcome! Enjoy the show!"

included.attributes.locations.address

string

Geocoded address of the location. Used for display purposes only. This is calculated automatically from the latitude and longitude values

Example:

"Mick's Garage, Queens Yard, London, England, E9 5EN, United Kingdom"

included.attributes.beacons

object[]

Beacons, present if 'includeBeacons' query param is set to true

Show child attributes

included.attributes.beacons.proximityUuid

string

Unique identifier of the beacon

Example:

"E2C56DB5-DFFB-48D2-B060-D0F5A71096E0"

included.attributes.beacons.major

integer

Major Value, provides additional identification for a beacon

Example:

65535

included.attributes.beacons.minor

integer

Minor Value, provides additional identification for a beacon

Example:

8525

included.attributes.beacons.message

string | null

Message to display on lock screen when the user is in range of the beacon

Example:

"You're near my store"

included.attributes.beacons.name

string

Name of the beacon, used for display purposes only

Example:

"West Entrance"

included.attributes.passSource

object

Pass source, present if 'includePassDesign' query param is present, one of Apple/Google and current pass status is not 'active'.

Show child attributes

included.attributes.passSource.oneOf

object

Show child attributes

included.attributes.passSource.oneOf.appleBase64

string

Apple Wallet Pass Base64 string, to generate the pass, decode the string and save as a .pkpass file. Will prompt the user to download the pass to their Apple Wallet when opened on an iPhone.

included.attributes.passSource.oneOf.googleDownloadUrl

string

Google Wallet Pass download URL. Will prompt the user to download the pass to their Google Wallet when opened on an Android device.

links

object

Show child attributes

links.first

string | null

Path to first page, null if currentPage is first page

links.prev

string | null

Path to prev page, null if currentPage is first page

links.next

string | null

Path to next page, null if currentPage is last page

links.last

string | null

Path to last page, null if currentPage is last page

Loyalty

⌘I

List scans

curl --request GET \
  --url https://api.passentry.com/api/v1/scans \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "id": "0195ebee-62d2-7a98-83b7-1fe98465a401",
      "type": "scan",
      "attributes": {
        "scanType": "barcode",
        "scanValue": "factory_scan_value",
        "validationType": "internalValidation",
        "status": "failed",
        "statusDetail": "Pass is not active",
        "scannedAt": "2025-01-13T13:00:00Z"
      },
      "relationships": {
        "pass": {
          "data": {
            "id": "7882e98b-0eba-4625-9223-5221eb8dad7f",
            "type": "pass"
          }
        },
        "reader": {
          "data": {
            "id": "south-gate-1",
            "type": "reader"
          }
        }
      }
    },
    {
      "id": "0195ebee-62d1-72b3-bd35-a101b24878a9",
      "type": "scan",
      "attributes": {
        "scanType": "nfc",
        "scanValue": "factory_scan_value",
        "validationType": "internalValidation",
        "status": "failed",
        "statusDetail": "Pass is not active",
        "scannedAt": "2025-01-13T13:02:00Z"
      },
      "relationships": {
        "pass": {
          "data": {
            "id": "7882e98b-0eba-4625-9223-5221eb8dad7f",
            "type": "pass"
          }
        },
        "reader": {
          "data": {
            "id": "south-gate-1",
            "type": "reader"
          }
        }
      }
    },
    {
      "id": "0195ebee-62d0-77cb-b8b1-0a81f99efc2c",
      "type": "scan",
      "attributes": {
        "scanType": "barcode",
        "scanValue": "factory_scan_value",
        "validationType": "internalValidation",
        "status": "failed",
        "statusDetail": "Pass is not active",
        "scannedAt": "2025-01-13T13:05:00Z"
      },
      "relationships": {
        "pass": {
          "data": {
            "id": "7882e98b-0eba-4625-9223-5221eb8dad7f",
            "type": "pass"
          }
        },
        "reader": {
          "data": {
            "id": "south-gate-1",
            "type": "reader"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "7882e98b-0eba-4625-9223-5221eb8dad7f",
      "type": "pass",
      "attributes": {
        "downloadUrl": "https://www.example.com?pass=7882e98b-0eba-4625-9223-5221eb8dad7f",
        "passType": "generic",
        "createdAt": "2022-01-01T00:00:00Z",
        "status": "issued",
        "extId": "4312d68fd106e3e6dd15",
        "passTemplateUuid": "7f24e7371e67c7af15103815",
        "passTemplateName": "PassEntry Event",
        "nfc": null,
        "barcode": {},
        "passContent": {
          "fullName": "John Johnson"
        }
      }
    },
    {
      "id": "south-gate-1",
      "type": "reader",
      "attributes": {
        "name": "South Gate Reader",
        "readerType": "PassentryReader",
        "loggedIn": false,
        "qrEnabled": false,
        "mifareClassicNfcEnabled": false,
        "scanEnabled": true,
        "redeemEnabled": false,
        "addPointsEnabled": false,
        "ndefTagScanningEnabled": false,
        "lastSeenAt": "2020-03-13T13:00:00Z"
      }
    }
  ],
  "meta": {
    "totalCount": 3,
    "resultsPerPage": 25,
    "currentPage": 1,
    "totalPages": 1
  },
  "links": {
    "first": null,
    "prev": null,
    "next": null,
    "last": null
  }
}

Introduction

Entities

Pass Templates

Passes

Readers

Scans

Loyalty

Webhook Subscriptions

Webhooks

Batches

Authorizations

Query Parameters

Response