The Identity Event object

An identity event records one change that Lumos detected on an identity: which field changed, its old and new values, and when Lumos detected the change. A user is one kind of identity. A status change, a new email address, and an identity joining a group each produce an event. A change to two fields at once produces two events. Events are read-only. You read them through one endpoint, List Identity Events.

{
  "id": "t2wKCZIBqX3pLm7dV0aE",
  "user_id": "3c4d5e6f-7081-9012-cdef-123456789012",
  "detected_time": "2026-09-24T18:02:11.482000Z",
  "changed_field": "Email",
  "old_field_value": "jane@old.example.com",
  "new_field_value": "jane.smith@example.com"
}

Attributes

Field	Type	Description
`id`	string	Unique identifier for the event. Always present.
`user_id`	string	The user `id` of the identity whose field changed. Always present.
`detected_time`	string	When Lumos detected the change, in ISO 8601 format. Always present.
`changed_field`	string	The label of the field that changed, such as `Email`, `Status`, or `Group Membership`, or a custom attribute’s label. Always present.
`old_field_value`	string or null	The field’s value before the change.
`new_field_value`	string or null	The field’s value after the change.

A group membership change shows the group’s name, and a custom attribute change shows the attribute’s value.

Who can read identity events

Of the built-in roles, Admin and Read Only Admin can list identity events.

Filtering

List Identity Events returns events newest first, by detected_time. Four filters narrow the list:

Filter	Effect
`identity_ids`	Events for these identities, by user `id`. An ID that doesn’t match an identity in your organization returns `404`.
`changed_fields`	Events for these fields, named by the labels `changed_field` returns.
`start_time`	Events detected at or after this timestamp.
`end_time`	Events detected at or before this timestamp.

changed_fields matches labels exactly, including case, so Status works and status returns 400. The built-in labels are Given Name, Family Name, Full Name, Email, Status, Identity Type, Email Is Lumos Generated, Identity Source App, and Group Membership. Any other label must be the label of one of your custom attributes. A label that matches neither returns 400, and the error message lists the built-in labels.

curl -s 'https://api.lumos.com/v1/identity-events?changed_fields=Status&changed_fields=Group%20Membership&start_time=2026-09-01T00:00:00Z' \
  --header 'Authorization: Bearer lsk_your_token'

Reading to the end

page_size defaults to 100 and is capped at 100. Every page with events has a next_page_token, including the last one, so the request after the last page returns no events, and its next_page_token is missing or null. A page can also be empty while next_page_token is still set. Short and empty pages explains when to stop.

Endpoints

Endpoint	Path
List Identity Events	`GET /v1/identity-events`

Quick Start

Lumos API

API Reference

Guides

Migrate from v0

Lumos Connectors

Webhooks

Tools

The Identity Event object

Attributes

Who can read identity events

Filtering

Reading to the end

Endpoints

​Attributes

​Who can read identity events

​Filtering

​Reading to the end

​Endpoints

Attributes

Who can read identity events

Filtering

Reading to the end

Endpoints