# Lifecycle Events

Lifecycle management events are the granular outcome records produced by workflow actions. Each event records a single change (or attempted change) to an entity in a target system—such as creating an identity, adding a group membership, resetting a password, or disabling an account.

These APIs correspond to the **Events** tab on the [Activity Log](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/getting-started/activity-log.md) page in the Veza UI.

**Event APIs** help you:

* Audit every individual change made by lifecycle management
* Track success and failure of entity-level operations
* Filter events by type, identity, datasource, or time range
* Export event history for compliance reporting

## Endpoints

| Method | Endpoint                        | Description                                              |
| ------ | ------------------------------- | -------------------------------------------------------- |
| GET    | [List Events](#list-events)     | Retrieve a paginated list of lifecycle management events |
| GET    | [Get Event](#get-event)         | Retrieve a single event by ID                            |
| POST   | [Export Events](#export-events) | Export events to a downloadable file                     |

## Key Concepts

### Event Types

The `event_type` field classifies what happened:

| Value                         | Description                               |
| ----------------------------- | ----------------------------------------- |
| `NONE`                        | No event type specified                   |
| `CREATE_IDENTITY`             | New identity created in target system     |
| `SYNC_IDENTITY`               | Existing identity attributes synchronized |
| `ADD_RELATIONSHIP`            | Group/role membership added               |
| `REMOVE_RELATIONSHIP`         | Group/role membership removed             |
| `CREATE_EMAIL`                | Email address created for identity        |
| `CHANGE_PASSWORD`             | Identity password changed                 |
| `DELETE_IDENTITY`             | Identity deleted from target system       |
| `DISABLE_IDENTITY`            | Identity disabled in target system        |
| `WRITE_BACK_EMAIL`            | Email written back to HRIS system         |
| `ACCESS_REQUEST_COMPLETE`     | Access request completed                  |
| `CUSTOM_ACTION`               | Custom action executed                    |
| `ACTION_FAILED`               | Action failed during execution            |
| `WORKFLOW_TASK_FAILED`        | Workflow task failed                      |
| `EXTRACTION_EVENT_FAILED`     | Extraction event failed                   |
| `CREATE_ENTITLEMENT`          | Entitlement (role/group) created          |
| `CREATE_GUEST_ACCOUNT`        | Guest account created                     |
| `RENAME_ENTITLEMENT`          | Entitlement renamed                       |
| `CREATE_ACCESS_REVIEW`        | Access review campaign created            |
| `RESET_PASSWORD`              | Identity password reset                   |
| `CREATE_ACCESS_REVIEW_QUEUED` | Access review creation queued             |
| `SAFETY_LIMIT_REACHED`        | Safety limit threshold reached            |
| `SYNC_ENTITLEMENT`            | Entitlement synchronized                  |
| `INVALID_IDENTITIES_DETECTED` | Invalid identities detected in source     |
| `INVALID_IDENTITY`            | Single invalid identity detected          |
| `IDENTITY_METADATA_EDIT`      | Identity metadata manually edited         |

### Lifecycle Event Source

| Value         | Description                              |
| ------------- | ---------------------------------------- |
| `POLICY`      | Event produced by an LCM Policy workflow |
| `ACCESS_PLAN` | Event produced by an Access Plan         |

## List Events

### Endpoint

```sh
GET /api/private/lifecycle_management/events
```

### Description

Retrieve a paginated list of lifecycle management events. Supports SCIM-style filtering, ordering, and pagination. Events are ordered by `timestamp` descending by default.

### Filterable Fields

| Field                                  | Operators      | Description                                             |
| -------------------------------------- | -------------- | ------------------------------------------------------- |
| `timestamp`                            | gt, ge, lt, le | Event timestamp                                         |
| `event_type`                           | eq             | Type of event                                           |
| `success`                              | eq             | Whether the event succeeded                             |
| `identity_entity_type`                 | eq, co         | Identity entity type (case-insensitive)                 |
| `identity_entity_id`                   | eq, co         | Identity entity ID (case-insensitive)                   |
| `identity_entity_name`                 | eq, co         | Identity entity name (case-insensitive)                 |
| `identity_id`                          | eq             | Identity ID                                             |
| `data_source_id`                       | eq             | Target datasource ID                                    |
| `provider_id`                          | eq             | Provider ID                                             |
| `entity_type`                          | eq, co         | Target entity type (case-insensitive)                   |
| `entity_id`                            | eq, co         | Target entity ID (case-insensitive)                     |
| `entity_name`                          | eq, co         | Target entity name (case-insensitive)                   |
| `policy_task`                          | eq             | Parent workflow task ID                                 |
| `extraction_event`                     | eq             | Extraction event ID                                     |
| `job_id`                               | eq             | Parent job ID                                           |
| `event_source`                         | eq             | Source (POLICY or ACCESS\_PLAN)                         |
| `event_source_id`                      | eq             | Source ID                                               |
| `workflow_name`                        | eq, co         | Workflow name                                           |
| `policy_name`                          | eq             | Policy name                                             |
| `datasource_name`                      | eq             | Datasource name                                         |
| `relationship_entity_type`             | eq, co         | Relationship entity type (case-insensitive)             |
| `relationship_entity_id`               | eq, co         | Relationship entity ID (case-insensitive)               |
| `relationship_entity_name`             | eq, co         | Relationship entity name (case-insensitive)             |
| `relationship_assigned_to_entity_type` | eq, co         | Assigned-to relationship entity type (case-insensitive) |
| `relationship_assigned_to_entity_id`   | eq, co         | Assigned-to relationship entity ID (case-insensitive)   |
| `relationship_assigned_to_entity_name` | eq, co         | Assigned-to relationship entity name (case-insensitive) |
| `id`                                   | eq             | Event ID                                                |

### API Reference

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/private/lifecycle\_management/events" method="get" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Request Examples

**List failed events since a specific date:**

```bash
# Replace the timestamp value with your desired start date
curl -X GET "https://your-tenant.vezacloud.com/api/private/lifecycle_management/events?filter=success%20eq%20false%20and%20timestamp%20gt%20%222024-07-14T00:00:00Z%22&page_size=100" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

**List identity creation events:**

```bash
curl -X GET "https://your-tenant.vezacloud.com/api/private/lifecycle_management/events?filter=event_type%20eq%20%22CREATE_IDENTITY%22" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Get Event

### Endpoint

```sh
GET /api/private/lifecycle_management/events/{id}
```

### Description

Retrieve a single lifecycle management event by its unique ID. Returns the full event record including entity details, relationship information, and success/failure status.

### API Reference

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/private/lifecycle\_management/events/{id}" method="get" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Request Example

```bash
curl -X GET "https://your-tenant.vezacloud.com/api/private/lifecycle_management/events/evt-abc-123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Export Events

### Endpoint

```sh
POST /api/private/lifecycle_management/events:export
```

### Description

Export lifecycle management events matching a filter to a downloadable CSV file. The request body wraps the same filter and ordering parameters used by the List endpoint.

### API Reference

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/private/lifecycle\_management/events:export" method="post" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-f5344805587160cf141bde637e04e03e2aa86778%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Request Example

```bash
curl -X POST "https://your-tenant.vezacloud.com/api/private/lifecycle_management/events:export" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": {
      "filter": "event_type eq \"CREATE_IDENTITY\" and success eq true",
      "order_by": "timestamp desc"
    },
    "format": "CSV"
  }'
```

## Authentication

All Event API requests require authentication. See [API Authentication](/4yItIzMvkpAvMVFAamTf/developers/api/authentication.md) for details.

## Related Documentation

* [Activity Log](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/getting-started/activity-log.md)
* [Policies and Workflows](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows.md)
* [Triggered Workflows](/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/activitylog/triggeredworkflows.md)
* [Workflow Actions](/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/activitylog/workflowactions.md)
* [Integration Jobs](/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/activitylog/integrationjobs.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/activitylog/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.