GET Customer Events

Returns a list of all events associated with the specified customer.

Overview

This endpoint retrieves access control events for a specific customer. Events include door access attempts, system alerts, and other security-related activities. This is essential for monitoring and auditing access control activities.

Resource URL

https://api.volo-access.com/v1/business/customer/{CustomerGuid}/event

Authentication

This endpoint requires both application and user authentication:

• x-nonce-token: Required
• x-app-token: Required
• x-user-credential: Required

Path Parameters

Parameter	Type	Required	Description
CustomerGuid	String	Yes	The unique identifier for the customer

Query Parameters

Parameter	Type	Required	Description
fromDate	DateTime	No	Filter events from this date (ISO 8601 format)
toDate	DateTime	No	Filter events to this date (ISO 8601 format)
eventType	Integer	No	Filter by specific event type

Example URL with Filters

https://api.volo-access.com/v1/business/customer/550e8400-e29b-41d4-a716-446655440000/event?fromDate=2024-01-01T00:00:00.000Z&toDate=2024-01-31T23:59:59.000Z&eventType=1

Response

Success Response (200 OK)

Returns a ListEventDetailsResponse object containing an array of events:

Parameter	Type	Description
eventDetailsResponseList	Array	Array of event objects

Each event object contains:

Parameter	Type	Description
eventId	Integer	The event ID
displayName	String	The event display name
priorityDescription	String	The priority description
customerGuid	String	The customer unique identifier
eventDate	DateTime	The event date (ISO 8601 format)
receivedDate	DateTime	The received date (ISO 8601 format)
deviceSerialNumber	String	The device serial number
deviceName	String	The device name
deviceGuid	String	The device GUID
doorGuid	String	The door unique identifier
tokenData	String	The token data
tokenGuid	String	The token unique identifier
tokenDescription	String	The token description
tokenLost	Boolean	Whether the token is lost
userGuid	String	The user unique identifier
userFirstName	String	The user first name
userLastName	String	The user last name
userBarred	Boolean	Whether the user is barred
userDeleted	Boolean	Whether the user is deleted
siteGuid	String	The site unique identifier
siteName	String	The site name
siteCode	String	The site code
doorName	String	The door name
doorDeleted	Boolean	Whether the door is deleted
deviceDeleted	Boolean	Whether the device is deleted
siteDeleted	Boolean	Whether the site is deleted
timezoneDescription	String	The timezone description
installerCode	String	The installer code
customerName	String	The customer name
eventType	Integer	The event type
localDoorId	Integer	The local door ID
tz	Integer	The controller timezone
deviceId	Integer	The device ID
doorId	Integer	The door ID
tokenId	Integer	The token ID
customerId	Integer	The customer ID
siteId	Integer	The site ID
userId	Integer	The user ID
tokenType	Integer	The token type
tokenIfType	Integer	The token interface type

Example Success Response

{
  "eventDetailsResponseList": [
    {
      "eventId": 12345,
      "displayName": "Access Granted",
      "priorityDescription": "Normal",
      "customerGuid": "550e8400-e29b-41d4-a716-446655440000",
      "eventDate": "2024-01-15T09:30:15.000Z",
      "receivedDate": "2024-01-15T09:30:16.000Z",
      "deviceSerialNumber": "VOLO001234",
      "deviceName": "Main Entrance Controller",
      "deviceGuid": "789e0123-e89b-12d3-a456-426614174002",
      "doorGuid": "456e7890-e89b-12d3-a456-426614174001",
      "tokenData": "1234567890",
      "tokenGuid": "234e5678-e89b-12d3-a456-426614174004",
      "tokenDescription": "Proximity Card",
      "tokenLost": false,
      "userGuid": "123e4567-e89b-12d3-a456-426614174000",
      "userFirstName": "John",
      "userLastName": "Doe",
      "userBarred": false,
      "userDeleted": false,
      "siteGuid": "567e8901-e89b-12d3-a456-426614174005",
      "siteName": "Main Office",
      "siteCode": "MAIN",
      "doorName": "Main Entrance",
      "doorDeleted": false,
      "deviceDeleted": false,
      "siteDeleted": false,
      "timezoneDescription": "Europe/London",
      "installerCode": "INST001",
      "customerName": "Acme Corporation",
      "eventType": 1,
      "localDoorId": 1,
      "tz": 0,
      "deviceId": 1001,
      "doorId": 2001,
      "tokenId": 3001,
      "customerId": 12345,
      "siteId": 4001,
      "userId": 1001,
      "tokenType": 1,
      "tokenIfType": 1
    },
    {
      "eventId": 12346,
      "displayName": "Access Denied",
      "priorityDescription": "High",
      "customerGuid": "550e8400-e29b-41d4-a716-446655440000",
      "eventDate": "2024-01-15T09:35:22.000Z",
      "receivedDate": "2024-01-15T09:35:23.000Z",
      "deviceSerialNumber": "VOLO001234",
      "deviceName": "Main Entrance Controller",
      "deviceGuid": "789e0123-e89b-12d3-a456-426614174002",
      "doorGuid": "456e7890-e89b-12d3-a456-426614174001",
      "tokenData": "9876543210",
      "tokenGuid": "345e6789-e89b-12d3-a456-426614174006",
      "tokenDescription": "Unknown Token",
      "tokenLost": false,
      "userGuid": null,
      "userFirstName": null,
      "userLastName": null,
      "userBarred": false,
      "userDeleted": false,
      "siteGuid": "567e8901-e89b-12d3-a456-426614174005",
      "siteName": "Main Office",
      "siteCode": "MAIN",
      "doorName": "Main Entrance",
      "doorDeleted": false,
      "deviceDeleted": false,
      "siteDeleted": false,
      "timezoneDescription": "Europe/London",
      "installerCode": "INST001",
      "customerName": "Acme Corporation",
      "eventType": 2,
      "localDoorId": 1,
      "tz": 0,
      "deviceId": 1001,
      "doorId": 2001,
      "tokenId": null,
      "customerId": 12345,
      "siteId": 4001,
      "userId": null,
      "tokenType": null,
      "tokenIfType": null
    }
  ]
}

Error Responses

400 Bad Request

Returned for invalid customer GUID format or invalid date parameters:

{
  "applicationMessage": "Invalid GUID format provided",
  "consumerMessage": "The customer identifier format is invalid"
}

401 Unauthorized

Returned when authentication is missing or invalid:

{
  "applicationMessage": "Missing or invalid authentication headers",
  "consumerMessage": "Authentication required"
}

403 Forbidden

Returned when user lacks permission to view the customer's events:

{
  "applicationMessage": "User does not have permission to access customer event data",
  "consumerMessage": "You do not have permission to view this information"
}

404 Not Found

Returned when the customer doesn't exist:

{
  "applicationMessage": "Customer with GUID 550e8400-e29b-41d4-a716-446655440000 not found",
  "consumerMessage": "Customer not found"
}

500 Internal Server Error

Returned for server-side errors:

{
  "applicationMessage": "Database connection failed",
  "consumerMessage": "An error occurred while retrieving event data"
}

Example Request

GET https://api.volo-access.com/v1/business/customer/550e8400-e29b-41d4-a716-446655440000/event?fromDate=2024-01-01T00:00:00.000Z&toDate=2024-01-31T23:59:59.000Z
x-nonce-token: MDU4ZmQ5Y2EtNTExNi00N2E0LWI0Y2EtNjM1YWRjZTZjYmNi
x-app-token: d1d0ecac-3cca-48ef-a4c3-83005c6376ca
x-user-credential: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Usage Notes

• Large Datasets: Event data can be very large. Always use date filters to limit the response size
• Performance: For large date ranges, consider breaking requests into smaller time periods
• Event Types: Common event types include access granted (1), access denied (2), system alerts, etc.
• Real-time Data: Events are typically available within seconds of occurrence
• Deleted Entities: Events may reference deleted users, devices, or doors
• Timezone: Events include timezone information for proper interpretation
• Pagination: Consider implementing client-side pagination for large result sets
• Filtering: Use the query parameters to filter events by date range and type

Related Endpoints

• List Customer Devices - Get devices for this customer
• List Customer Doors - Get doors for this customer
• Get User Details - Get details for a specific user