Scan Groups

Scan groups allow you to define sets of scan configurations that can be assigned to access devices. Each scan group specifies which events and ticket types a device is permitted to scan.

Please note: GROUP events and ROOT events should not be assigned to scan groups.

The Scan Group object

Required attributes

Name
_id
Type
string
Description
The ID of the scan group.
Name
name
Type
string
Description
The name of the scan group.
Name
sellerId
Type
string
Description
The ID of the seller of the scan group.
Name
createdAt
Type
string date-time
Description
An ISO Timestamp indicating when the resource was created.
Name
updatedAt
Type
string date-time
Description
An ISO Timestamp indicating when the resource was updated.

Optional attributes

Name
scanConfig
Type
object
Description
The scan configuration of the scan group.
Required nested attributes (1)
Name
mode
Type
enum(lock, default)
Description
The mode of the scan config.
Optional nested attributes (6)
Name
events
Type
array<object>
Description
The events settings of the scan config.
Required nested attributes (1)
Name
eventId
Type
string
Description
The ID of the event.
Optional nested attributes (4)
Name
allowAllTicketTypes
Type
boolean
Description
Whether an all ticket type available or not.
Name
allowedTicketTypeIds
Type
array<string>
Description
The array of the allowed ticket type IDs.
Name
timeslotSettings
Type
object
Description
Optional nested attributes (2)
Name
beforeMinutes
Type
number
Description
Minutes before a timeslot when tickets become valid for this event.
Name
afterMinutes
Type
number
Description
Minutes after a timeslot when tickets remain valid for this event.
Name
eventTimeSettings
Type
object
Description
Required nested attributes (1)
Name
active
Type
boolean
Description
Whether the event time window is enforced for this event.
Optional nested attributes (2)
Name
beforeHours
Type
number
Description
Hours before the event start when tickets become valid for this event.
Name
afterHours
Type
number
Description
Hours after the event end when tickets remain valid for this event.
Name
scanZoneId
Type
string
Description
The ID of the scan zone.
Name
scanTypes
Type
object
Description
The scan types enabled on the device. At least one of checkin or checkout must be true.
One of — Only one of the following types
Required attributes
Name
checkin
Type
enum(true)
Description
Whether check-in scanning is enabled.
Name
checkout
Type
boolean
Description
Whether check-out scanning is enabled.
Name
enableMultiCheckin
Type
boolean
Description
Whether a ticket is allowed to be checked in more than once, given the corresponding count of checkouts were created.
Name
checkTimeslots
Type
boolean
Description
Whether to validate the ticket's timeslot against the current time.
Name
tapAndGo
Type
object
Description
The tap and go configuration of the scan group.
Required nested attributes (1)
Name
enabled
Type
boolean
Description
Whether tap and go is enabled.
Optional nested attributes (1)
Name
eventIds
Type
array<string>
Description
The IDs of events available for tap and go selection.
Name
deviceSettings
Type
object
Description
The device behaviour settings of the scan group.
Optional nested attributes (5)
Name
colorSettings
Type
object
Description
The color overrides for each scan feedback type.
Optional nested attributes (5)
Name
success
Type
enum(green)
Description
The color shown for a success scan result. Fixed to green and cannot be overridden.
Name
declined
Type
enum(red)
Description
The color shown for a declined scan result. Fixed to red and cannot be overridden.
Name
repeated
Type
enum(green, orange, red, blue, pink)
Description
The color shown for a repeated scan result.
Name
highlighted
Type
enum(green, orange, red, blue, pink)
Description
The color shown for a highlighted scan result.
Name
actionRequired
Type
enum(green, orange, red, blue, pink)
Description
The color shown for a actionRequired scan result.
Name
enableSoundFeedback
Type
boolean
Description
Whether scan sound feedback is enabled.
Name
enableHapticFeedback
Type
boolean
Description
Whether haptic feedback is enabled.
Name
scanRevealInterval
Type
enum(1, 3, 5, 10, 15, 30)
Description
The scan result display duration in seconds.
Name
ticketSyncInterval
Type
enum(5, 15, 30, 60, 300, 600, 900)
Description
The ticket data synchronization interval in seconds.

Example

{
  "_id": "507f191e810c19729de860ea",
  "name": "Some fancy Name",
  "sellerId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "scanConfig": {
    "mode": "lock",
    "events": [
      {
        "eventId": "507f191e810c19729de860ea",
        "allowAllTicketTypes": false,
        "allowedTicketTypeIds": [
          "string"
        ],
        "timeslotSettings": {
          "beforeMinutes": 0,
          "afterMinutes": 0
        },
        "eventTimeSettings": {
          "active": false,
          "beforeHours": 0,
          "afterHours": 0
        }
      }
    ],
    "scanZoneId": "507f191e810c19729de860ea",
    "scanTypes": {
      "checkin": true,
      "checkout": true
    },
    "enableMultiCheckin": true,
    "checkTimeslots": true,
    "tapAndGo": {
      "enabled": true,
      "eventIds": [
        "string"
      ]
    }
  },
  "deviceSettings": {
    "colorSettings": {
      "success": "green",
      "declined": "red",
      "repeated": "green",
      "highlighted": "green",
      "actionRequired": "green"
    },
    "enableSoundFeedback": true,
    "enableHapticFeedback": true,
    "scanRevealInterval": 1,
    "ticketSyncInterval": 5
  }
}

POST/api/scan-groups

Create a Scan Group

Payload

Required attributes

Name
name
Type
string
Description
The name of the scan group.
Name
scanConfig
Type
object
Description
The scan configuration of the scan group.
Required nested attributes (1)
Name
mode
Type
enum(lock, default)
Description
The mode of the scan config.
Optional nested attributes (6)
Name
events
Type
array<object>
Description
The events settings of the scan config.
Required nested attributes (1)
Name
eventId
Type
string
Description
The ID of the event.
Optional nested attributes (4)
Name
allowAllTicketTypes
Type
boolean
Description
Whether an all ticket type available or not.
Name
allowedTicketTypeIds
Type
array<string>
Description
The array of the allowed ticket type IDs.
Name
timeslotSettings
Type
object
Description
Optional nested attributes (2)
Name
beforeMinutes
Type
number
Description
Minutes before a timeslot when tickets become valid for this event.
Name
afterMinutes
Type
number
Description
Minutes after a timeslot when tickets remain valid for this event.
Name
eventTimeSettings
Type
object
Description
Required nested attributes (1)
Name
active
Type
boolean
Description
Whether the event time window is enforced for this event.
Optional nested attributes (2)
Name
beforeHours
Type
number
Description
Hours before the event start when tickets become valid for this event.
Name
afterHours
Type
number
Description
Hours after the event end when tickets remain valid for this event.
Name
scanZoneId
Type
string
Description
The ID of the scan zone.
Name
scanTypes
Type
object
Description
The scan types enabled on the device. At least one of checkin or checkout must be true.
One of — Only one of the following types
Required attributes
Name
checkin
Type
enum(true)
Description
Whether check-in scanning is enabled.
Name
checkout
Type
boolean
Description
Whether check-out scanning is enabled.
Name
enableMultiCheckin
Type
boolean
Description
Whether a ticket is allowed to be checked in more than once, given the corresponding count of checkouts were created.
Name
checkTimeslots
Type
boolean
Description
Whether to validate the ticket's timeslot against the current time.
Name
tapAndGo
Type
object
Description
The tap and go configuration of the scan group.
Required nested attributes (1)
Name
enabled
Type
boolean
Description
Whether tap and go is enabled.
Optional nested attributes (1)
Name
eventIds
Type
array<string>
Description
The IDs of events available for tap and go selection.

Optional attributes

Name
deviceSettings
Type
object
Description
The device behaviour settings of the scan group.
Optional nested attributes (5)
Name
colorSettings
Type
object
Description
The color overrides for each scan feedback type.
Optional nested attributes (5)
Name
success
Type
enum(green)
Description
The color shown for a success scan result. Fixed to green and cannot be overridden.
Name
declined
Type
enum(red)
Description
The color shown for a declined scan result. Fixed to red and cannot be overridden.
Name
repeated
Type
enum(green, orange, red, blue, pink)
Description
The color shown for a repeated scan result.
Name
highlighted
Type
enum(green, orange, red, blue, pink)
Description
The color shown for a highlighted scan result.
Name
actionRequired
Type
enum(green, orange, red, blue, pink)
Description
The color shown for a actionRequired scan result.
Name
enableSoundFeedback
Type
boolean
Description
Whether scan sound feedback is enabled.
Name
enableHapticFeedback
Type
boolean
Description
Whether haptic feedback is enabled.
Name
scanRevealInterval
Type
enum(1, 3, 5, 10, 15, 30)
Description
The scan result display duration in seconds.
Name
ticketSyncInterval
Type
enum(5, 15, 30, 60, 300, 600, 900)
Description
The ticket data synchronization interval in seconds.

Request

POST

/api/scan-groups

const response = await fetch('https://vivenu.com/api/scan-groups', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "name": "Some fancy Name",
    "scanConfig": {
      "mode": "lock",
      "events": [
        {
          "eventId": "507f191e810c19729de860ea",
          "allowAllTicketTypes": false,
          "allowedTicketTypeIds": [
            "string"
          ],
          "timeslotSettings": {
            "beforeMinutes": 0,
            "afterMinutes": 0
          },
          "eventTimeSettings": {
            "active": false,
            "beforeHours": 0,
            "afterHours": 0
          }
        }
      ],
      "scanZoneId": "507f191e810c19729de860ea",
      "scanTypes": {
        "checkin": true,
        "checkout": true
      },
      "enableMultiCheckin": true,
      "checkTimeslots": true,
      "tapAndGo": {
        "enabled": true,
        "eventIds": [
          "string"
        ]
      }
    },
    "deviceSettings": {
      "colorSettings": {
        "success": "green",
        "declined": "red",
        "repeated": "green",
        "highlighted": "green",
        "actionRequired": "green"
      },
      "enableSoundFeedback": true,
      "enableHapticFeedback": true,
      "scanRevealInterval": 1,
      "ticketSyncInterval": 5
    }
  }),
})

const data = await response.json()

Response (201)

{
  "_id": "507f191e810c19729de860ea",
  "name": "Some fancy Name",
  "sellerId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "scanConfig": {
    "mode": "lock",
    "events": [
      {
        "eventId": "507f191e810c19729de860ea",
        "allowAllTicketTypes": false,
        "allowedTicketTypeIds": [
          "string"
        ],
        "timeslotSettings": {
          "beforeMinutes": 0,
          "afterMinutes": 0
        },
        "eventTimeSettings": {
          "active": false,
          "beforeHours": 0,
          "afterHours": 0
        }
      }
    ],
    "scanZoneId": "507f191e810c19729de860ea",
    "scanTypes": {
      "checkin": true,
      "checkout": true
    },
    "enableMultiCheckin": true,
    "checkTimeslots": true,
    "tapAndGo": {
      "enabled": true,
      "eventIds": [
        "string"
      ]
    }
  },
  "deviceSettings": {
    "colorSettings": {
      "success": "green",
      "declined": "red",
      "repeated": "green",
      "highlighted": "green",
      "actionRequired": "green"
    },
    "enableSoundFeedback": true,
    "enableHapticFeedback": true,
    "scanRevealInterval": 1,
    "ticketSyncInterval": 5
  }
}

GET/api/scan-groups/:id

Get a Scan Group

Request

GET

/api/scan-groups/:id

const response = await fetch('https://vivenu.com/api/scan-groups/507f191e810c19729de860ea', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "name": "Some fancy Name",
  "sellerId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "scanConfig": {
    "mode": "lock",
    "events": [
      {
        "eventId": "507f191e810c19729de860ea",
        "allowAllTicketTypes": false,
        "allowedTicketTypeIds": [
          "string"
        ],
        "timeslotSettings": {
          "beforeMinutes": 0,
          "afterMinutes": 0
        },
        "eventTimeSettings": {
          "active": false,
          "beforeHours": 0,
          "afterHours": 0
        }
      }
    ],
    "scanZoneId": "507f191e810c19729de860ea",
    "scanTypes": {
      "checkin": true,
      "checkout": true
    },
    "enableMultiCheckin": true,
    "checkTimeslots": true,
    "tapAndGo": {
      "enabled": true,
      "eventIds": [
        "string"
      ]
    }
  },
  "deviceSettings": {
    "colorSettings": {
      "success": "green",
      "declined": "red",
      "repeated": "green",
      "highlighted": "green",
      "actionRequired": "green"
    },
    "enableSoundFeedback": true,
    "enableHapticFeedback": true,
    "scanRevealInterval": 1,
    "ticketSyncInterval": 5
  }
}

PUT/api/scan-groups/:id

Update a Scan Group

Payload

Required attributes

Name
name
Type
string
Description
The name of the scan group.

Optional attributes

Name
scanConfig
Type
object
Description
The scan configuration of the scan group.
Required nested attributes (1)
Name
mode
Type
enum(lock, default)
Description
The mode of the scan config.
Optional nested attributes (6)
Name
events
Type
array<object>
Description
The events settings of the scan config.
Required nested attributes (1)
Name
eventId
Type
string
Description
The ID of the event.
Optional nested attributes (4)
Name
allowAllTicketTypes
Type
boolean
Description
Whether an all ticket type available or not.
Name
allowedTicketTypeIds
Type
array<string>
Description
The array of the allowed ticket type IDs.
Name
timeslotSettings
Type
object
Description
Optional nested attributes (2)
Name
beforeMinutes
Type
number
Description
Minutes before a timeslot when tickets become valid for this event.
Name
afterMinutes
Type
number
Description
Minutes after a timeslot when tickets remain valid for this event.
Name
eventTimeSettings
Type
object
Description
Required nested attributes (1)
Name
active
Type
boolean
Description
Whether the event time window is enforced for this event.
Optional nested attributes (2)
Name
beforeHours
Type
number
Description
Hours before the event start when tickets become valid for this event.
Name
afterHours
Type
number
Description
Hours after the event end when tickets remain valid for this event.
Name
scanZoneId
Type
string
Description
The ID of the scan zone.
Name
scanTypes
Type
object
Description
The scan types enabled on the device. At least one of checkin or checkout must be true.
One of — Only one of the following types
Required attributes
Name
checkin
Type
enum(true)
Description
Whether check-in scanning is enabled.
Name
checkout
Type
boolean
Description
Whether check-out scanning is enabled.
Name
enableMultiCheckin
Type
boolean
Description
Whether a ticket is allowed to be checked in more than once, given the corresponding count of checkouts were created.
Name
checkTimeslots
Type
boolean
Description
Whether to validate the ticket's timeslot against the current time.
Name
tapAndGo
Type
object
Description
The tap and go configuration of the scan group.
Required nested attributes (1)
Name
enabled
Type
boolean
Description
Whether tap and go is enabled.
Optional nested attributes (1)
Name
eventIds
Type
array<string>
Description
The IDs of events available for tap and go selection.
Name
deviceSettings
Type
object
Description
The device behaviour settings of the scan group.
Optional nested attributes (5)
Name
colorSettings
Type
object
Description
The color overrides for each scan feedback type.
Optional nested attributes (5)
Name
success
Type
enum(green)
Description
The color shown for a success scan result. Fixed to green and cannot be overridden.
Name
declined
Type
enum(red)
Description
The color shown for a declined scan result. Fixed to red and cannot be overridden.
Name
repeated
Type
enum(green, orange, red, blue, pink)
Description
The color shown for a repeated scan result.
Name
highlighted
Type
enum(green, orange, red, blue, pink)
Description
The color shown for a highlighted scan result.
Name
actionRequired
Type
enum(green, orange, red, blue, pink)
Description
The color shown for a actionRequired scan result.
Name
enableSoundFeedback
Type
boolean
Description
Whether scan sound feedback is enabled.
Name
enableHapticFeedback
Type
boolean
Description
Whether haptic feedback is enabled.
Name
scanRevealInterval
Type
enum(1, 3, 5, 10, 15, 30)
Description
The scan result display duration in seconds.
Name
ticketSyncInterval
Type
enum(5, 15, 30, 60, 300, 600, 900)
Description
The ticket data synchronization interval in seconds.

Request

PUT

/api/scan-groups/:id

const response = await fetch('https://vivenu.com/api/scan-groups/507f191e810c19729de860ea', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer {token}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(  {
    "name": "Some fancy Name",
    "scanConfig": {
      "mode": "lock",
      "events": [
        {
          "eventId": "507f191e810c19729de860ea",
          "allowAllTicketTypes": false,
          "allowedTicketTypeIds": [
            "string"
          ],
          "timeslotSettings": {
            "beforeMinutes": 0,
            "afterMinutes": 0
          },
          "eventTimeSettings": {
            "active": false,
            "beforeHours": 0,
            "afterHours": 0
          }
        }
      ],
      "scanZoneId": "507f191e810c19729de860ea",
      "scanTypes": {
        "checkin": true,
        "checkout": true
      },
      "enableMultiCheckin": true,
      "checkTimeslots": true,
      "tapAndGo": {
        "enabled": true,
        "eventIds": [
          "string"
        ]
      }
    },
    "deviceSettings": {
      "colorSettings": {
        "success": "green",
        "declined": "red",
        "repeated": "green",
        "highlighted": "green",
        "actionRequired": "green"
      },
      "enableSoundFeedback": true,
      "enableHapticFeedback": true,
      "scanRevealInterval": 1,
      "ticketSyncInterval": 5
    }
  }),
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "name": "Some fancy Name",
  "sellerId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "scanConfig": {
    "mode": "lock",
    "events": [
      {
        "eventId": "507f191e810c19729de860ea",
        "allowAllTicketTypes": false,
        "allowedTicketTypeIds": [
          "string"
        ],
        "timeslotSettings": {
          "beforeMinutes": 0,
          "afterMinutes": 0
        },
        "eventTimeSettings": {
          "active": false,
          "beforeHours": 0,
          "afterHours": 0
        }
      }
    ],
    "scanZoneId": "507f191e810c19729de860ea",
    "scanTypes": {
      "checkin": true,
      "checkout": true
    },
    "enableMultiCheckin": true,
    "checkTimeslots": true,
    "tapAndGo": {
      "enabled": true,
      "eventIds": [
        "string"
      ]
    }
  },
  "deviceSettings": {
    "colorSettings": {
      "success": "green",
      "declined": "red",
      "repeated": "green",
      "highlighted": "green",
      "actionRequired": "green"
    },
    "enableSoundFeedback": true,
    "enableHapticFeedback": true,
    "scanRevealInterval": 1,
    "ticketSyncInterval": 5
  }
}

DELETE/api/scan-groups/:id

Delete a Scan Group

Request

DELETE

/api/scan-groups/:id

const response = await fetch('https://vivenu.com/api/scan-groups/507f191e810c19729de860ea', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "_id": "507f191e810c19729de860ea",
  "name": "Some fancy Name",
  "sellerId": "507f191e810c19729de860ea",
  "createdAt": "2030-01-23T23:00:00.123Z",
  "updatedAt": "2030-01-23T23:00:00.123Z",
  "scanConfig": {
    "mode": "lock",
    "events": [
      {
        "eventId": "507f191e810c19729de860ea",
        "allowAllTicketTypes": false,
        "allowedTicketTypeIds": [
          "string"
        ],
        "timeslotSettings": {
          "beforeMinutes": 0,
          "afterMinutes": 0
        },
        "eventTimeSettings": {
          "active": false,
          "beforeHours": 0,
          "afterHours": 0
        }
      }
    ],
    "scanZoneId": "507f191e810c19729de860ea",
    "scanTypes": {
      "checkin": true,
      "checkout": true
    },
    "enableMultiCheckin": true,
    "checkTimeslots": true,
    "tapAndGo": {
      "enabled": true,
      "eventIds": [
        "string"
      ]
    }
  },
  "deviceSettings": {
    "colorSettings": {
      "success": "green",
      "declined": "red",
      "repeated": "green",
      "highlighted": "green",
      "actionRequired": "green"
    },
    "enableSoundFeedback": true,
    "enableHapticFeedback": true,
    "scanRevealInterval": 1,
    "ticketSyncInterval": 5
  }
}

GET/api/scan-groups

Get All Scan Groups

Query parameters

Optional query parameters

Name
top
Type
integer
Description
A limit on the number of objects to be returned. Can range between 1 and 1000.
Name
skip
Type
integer
Description
The number of objects to skip for the requested result
Name
name
Type
string
Description
The filter by name.

Request

GET

/api/scan-groups

const response = await fetch('https://vivenu.com/api/scan-groups?top=1&skip=1&name=Some+fancy+Name', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer {token}',
  },
})

const data = await response.json()

Response (200)

{
  "docs": [
    {
      "_id": "507f191e810c19729de860ea",
      "name": "Some fancy Name",
      "sellerId": "507f191e810c19729de860ea",
      "createdAt": "2030-01-23T23:00:00.123Z",
      "updatedAt": "2030-01-23T23:00:00.123Z",
      "scanConfig": {
        "mode": "lock",
        "events": [
          {
            "eventId": "507f191e810c19729de860ea",
            "allowAllTicketTypes": false,
            "allowedTicketTypeIds": [
              "string"
            ],
            "timeslotSettings": {
              "beforeMinutes": 0,
              "afterMinutes": 0
            },
            "eventTimeSettings": {
              "active": false,
              "beforeHours": 0,
              "afterHours": 0
            }
          }
        ],
        "scanZoneId": "507f191e810c19729de860ea",
        "scanTypes": {
          "checkin": true,
          "checkout": true
        },
        "enableMultiCheckin": true,
        "checkTimeslots": true,
        "tapAndGo": {
          "enabled": true,
          "eventIds": [
            "string"
          ]
        }
      },
      "deviceSettings": {
        "colorSettings": {
          "success": "green",
          "declined": "red",
          "repeated": "green",
          "highlighted": "green",
          "actionRequired": "green"
        },
        "enableSoundFeedback": true,
        "enableHapticFeedback": true,
        "scanRevealInterval": 1,
        "ticketSyncInterval": 5
      }
    }
  ],
  "total": 1
}