Events

List events

Returns a paginated list of events (access control activity logs) for the authenticated user's account.
By default, returns person access events (admits and rejects) from the last 90 days.
Use event_codes parameter to filter by specific event types, or level=debug to include channel status events.

GET /api/3/events

Authentication

This endpoint requires authentication:

OAuth 2.0 Recommended

Use an OAuth 2.0 access token in the Authorization header. This is the recommended authentication method for all integrations. OAuth provides automatic token expiration, granular permission scopes, detailed usage tracking, and per-integration revocation. Learn how to obtain an access token.

Header Format:

Authorization: Bearer YOUR_ACCESS_TOKEN

Required Scopes:

account.event.access.readonly

Parameters

Query Parameters

event_codes array
Optional

Comma-separated list of event codes to filter by. If not specified, defaults to person access events (admits and rejects). Allowed event codes include: admit codes (10-18, 70), reject codes (20-29, 71-73), channel status codes (1-3), auto-unlock codes (40-42), tamper codes (90-91), door alarm codes (31-37), REX codes (30), sync codes (100-107), LDAP sync codes (220, 223-225).

first_name string
Optional

Filter by person's first name

last_name string
Optional

Filter by person's last name

channels array
Optional

Filter by channel IDs (comma-separated)

door_controllers array
Optional

Filter by door controller IDs (alias for channels parameter)

since string
Optional

Return events created since this timestamp. Defaults to 90 days ago if not specified.

level string
Optional

Set to "debug" to include channel status events in addition to access events

sort string
Optional

Sort order for results

Default: DESC

n integer
Optional

Number of results per page (max 1000)

Default: 50

page integer
Optional

Page number for pagination

Default: 1

Responses

200

List of events retrieved successfully

Response Fields

id integer required

Unique identifier for the event

eg. 123456789
event_id integer | null

Same as id (legacy field for backward compatibility)

eg. 123456789
event_code integer required

Numeric code identifying the event type. Common codes: - 10-18: Admit events (card, PIN, manual, REX, AUX, application, unlocked, Apple, Google) - 20-29: Reject events (card, out of hours, lockdown, tamper, PIN, timeout, invalid type, unauthorized, pass-back, offline) - 30: REX pressed - 31-37: Door state/alarm events - 40-42: Auto-unlock shift events - 50-63: Remote control events - 70-73: Multi-factor authentication events - 90-91: Tamper events - 100-107: Channel sync events

eg. 10
event_label string required

Human-readable description of the event

eg. John Doe admitted using card
door_controller_id integer | null

ID of the door controller (channel) where the event occurred

eg. 1340
door_controller_name string | null

Name of the door controller (channel)

eg. Front Door
channel_id integer | null

Alias for door_controller_id

eg. 1340
channel_name string | null

Alias for door_controller_name

eg. Front Door
person_id integer | null

ID of the person associated with this event (for access events)

eg. 12345
person_name string | null

Name of the person associated with this event

eg. John Doe
credentials_number string | null

Credential number used (card number, PIN, etc.)

eg. 1234567890
created_at string required

Timestamp when the event occurred

eg. 2024-01-15T14:30:00.000Z
updated_at string required

Timestamp when the event record was last updated

eg. 2024-01-15T14:30:00.000Z
400

Bad Request - Invalid event codes specified

Response Fields

error string
eg. bad_request
error_description string
eg. The following event codes are not valid for this method: 999
401

Unauthorized - Invalid or missing authentication

Response Fields

error string
eg. unauthorized
error_description string
eg. The access token is invalid
403

Forbidden - User does not have permission

Response Fields

error string
eg. forbidden
error_description string
eg. You are not authorized to access this resource
500

Internal Server Error

Response Fields

error string
eg. internal_server_error
error_description string
eg. An unexpected error occurred

Mentioned in Guides

This endpoint is used in the following guides:

After-Hours Access Workflow

Grant remote access to specific people for single-use door unlock in 3 minutes

Common Workflows • 3 min • Beginner

Events and Audit Trail

Monitor access activity with complete event code reference and filtering strategies

Webhooks & Events • 15 min • Intermediate

Request

curl -X GET \
  "https://api.doorflow.com/api/3/events" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Responses

List of events retrieved successfully

[
  {
    "id": 123456789,
    "event_id": 123456789,
    "event_code": 10,
    "event_label": "John Doe admitted using card",
    "door_controller_id": 1340,
    "door_controller_name": "Front Door",
    "channel_id": 1340,
    "channel_name": "Front Door",
    "person_id": 12345,
    "person_name": "John Doe",
    "credentials_number": "1234567890",
    "created_at": "2024-01-15T14:30:00.000Z",
    "updated_at": "2024-01-15T14:30:00.000Z"
  }
]