> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thena.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Account events

> Platform events related to account management operations

Account events are published whenever accounts, customer contacts, or account-related entities (activities, notes, tasks, relationships) are created, updated, or deleted. These events are delivered through the platform events system.

## Developer quickstart

### Minimal handler (accounts only)

```javascript theme={null}
app.post("/webhook/platform-events", async (req, res) => {
  const event = req.body;
  if (!event?.eventId || !event?.eventType?.startsWith("account")) {
    return res.status(200).send("OK");
  }
  res.status(200).send("OK");

  switch (event.eventType) {
    case "account:created":
      await onAccountCreated(event.payload);
      break;
    case "account-custom_field_value:changed":
      await onAccountCustomFieldChanged(event.payload);
      break;
    default:
      break;
  }
});
```

### Checklist

* Use `eventId` for idempotency to avoid duplicate updates in CRM tools.
* For relationship changes, rebuild affected hierarchies lazily.
* For bulk imports, implement queueing/backoff to protect downstream services.

## Core account events

### Account lifecycle

#### `account:created`

Triggered when a new account is created.

**Payload structure:**

```typescript theme={null}
{
  account: {
    id: string;
    name: string;
    domain?: string;
    industry?: string;
    size?: string;
    status: string;
    health: string;
    classification: string;
    metadata?: Record<string, unknown>;
    customFields?: Record<string, string[]>;
    createdAt: Date;
    updatedAt: Date;
  };
}
```

#### `account:updated`

Triggered when an account is updated.

**Payload structure:**

```typescript theme={null}
{
  account: AccountData;
  previousAccount: AccountData; // Previous state
}
```

#### `account:deleted`

Triggered when an account is deleted.

**Payload structure:**

```typescript theme={null}
{
  previousAccount: AccountData; // The deleted account data
}
```

### Account attribute change events

These events are triggered when specific account attributes change:

#### `account-health:changed`

Triggered when an account's health status changes.

#### `account-status:changed`

Triggered when an account's status changes.

#### `account-classification:changed`

Triggered when an account's classification changes.

#### `account-industry:changed`

Triggered when an account's industry changes.

### Account custom field events

#### `account-custom_field_value:added`

Triggered when a custom field value is added to an account.

**Additional payload:**

```typescript theme={null}
{
  changedCustomFields: Array<{
    fieldUid: string;
    newValues: string[];
    changeType: "added";
  }>;
}
```

#### `account-custom_field_value:removed`

Triggered when a custom field value is removed from an account.

**Additional payload:**

```typescript theme={null}
{
  changedCustomFields: Array<{
    fieldUid: string;
    previousValues: string[];
    changeType: "removed";
  }>;
}
```

#### `account-custom_field_value:changed`

Triggered when a custom field value is changed on an account.

**Additional payload:**

```typescript theme={null}
{
  changedCustomFields: Array<{
    fieldUid: string;
    previousValues: string[];
    newValues: string[];
    changeType: "updated";
  }>;
}
```

## Customer contact events

### Customer contact lifecycle

#### `customer-contact:created`

Triggered when a new customer contact is created.

**Payload structure:**

```typescript theme={null}
{
  customerContact: {
    id: string;
    firstName: string;
    lastName: string;
    email: string;
    phone?: string;
    jobTitle?: string;
    type: string;
    status: string;
    accountId: string;
    metadata?: Record<string, unknown>;
    customFields?: Record<string, string[]>;
    createdAt: Date;
    updatedAt: Date;
  };
}
```

#### `customer-contact:updated`

Triggered when a customer contact is updated.

**Payload structure:**

```typescript theme={null}
{
  customerContact: CustomerContactData;
  previousCustomerContact: CustomerContactData;
}
```

#### `customer-contact:deleted`

Triggered when a customer contact is deleted.

**Payload structure:**

```typescript theme={null}
{
  previousCustomerContact: CustomerContactData;
}
```

#### `customer-contact:type:changed`

Triggered when a customer contact's type changes.

### Customer contact custom field events

#### `customer-contact:custom_field_value:added`

Triggered when a custom field value is added to a customer contact.

#### `customer-contact:custom_field_value:removed`

Triggered when a custom field value is removed from a customer contact.

#### `customer-contact:custom_field_value:changed`

Triggered when a custom field value is changed on a customer contact.

## Account relationship events

### Account relationship lifecycle

#### `account-relationship:created`

Triggered when a new account relationship is created.

**Payload structure:**

```typescript theme={null}
{
  relationship: {
    id: string;
    parentAccountId: string;
    childAccountId: string;
    relationshipType: string;
    metadata?: Record<string, unknown>;
    createdAt: Date;
    updatedAt: Date;
  };
}
```

#### `account-relationship:updated`

Triggered when an account relationship is updated.

**Payload structure:**

```typescript theme={null}
{
  relationship: AccountRelationshipData;
  previousRelationship: AccountRelationshipData;
}
```

#### `account-relationship:deleted`

Triggered when an account relationship is deleted.

**Payload structure:**

```typescript theme={null}
{
  previousRelationship: AccountRelationshipData;
}
```

## Account activity events

### Account activity lifecycle

#### `account-activity:created`

Triggered when a new account activity is created.

**Payload structure:**

```typescript theme={null}
{
  activity: {
    id: string;
    accountId: string;
    title: string;
    description?: string;
    activityType: string;
    status: string;
    scheduledAt?: Date;
    completedAt?: Date;
    assignedUserId?: string;
    metadata?: Record<string, unknown>;
    createdAt: Date;
    updatedAt: Date;
  };
}
```

#### `account-activity:updated`

Triggered when an account activity is updated.

**Payload structure:**

```typescript theme={null}
{
  activity: AccountActivityData;
  previousActivity: AccountActivityData;
}
```

#### `account-activity:deleted`

Triggered when an account activity is deleted.

**Payload structure:**

```typescript theme={null}
{
  previousActivity: AccountActivityData;
}
```

### Account activity comment events

#### `account-activity:comment:created`

Triggered when a comment is added to an account activity.

#### `account-activity:comment:updated`

Triggered when a comment on an account activity is updated.

#### `account-activity:comment:deleted`

Triggered when a comment is deleted from an account activity.

## Account note events

### Account note lifecycle

#### `account-note:created`

Triggered when a new account note is created.

**Payload structure:**

```typescript theme={null}
{
  note: {
    id: string;
    accountId: string;
    title: string;
    content: string;
    visibility: string;
    authorId: string;
    metadata?: Record<string, unknown>;
    createdAt: Date;
    updatedAt: Date;
  };
}
```

#### `account-note:updated`

Triggered when an account note is updated.

**Payload structure:**

```typescript theme={null}
{
  note: AccountNoteData;
  previousNote: AccountNoteData;
}
```

#### `account-note:deleted`

Triggered when an account note is deleted.

**Payload structure:**

```typescript theme={null}
{
  previousNote: AccountNoteData;
}
```

### Account note comment events

#### `account-note:comment:created`

Triggered when a comment is added to an account note.

#### `account-note:comment:updated`

Triggered when a comment on an account note is updated.

#### `account-note:comment:deleted`

Triggered when a comment is deleted from an account note.

## Account task events

### Account task lifecycle

#### `account-task:created`

Triggered when a new account task is created.

**Payload structure:**

```typescript theme={null}
{
  task: {
    id: string;
    accountId: string;
    title: string;
    description?: string;
    status: string;
    priority: string;
    dueDate?: Date;
    assignedUserId?: string;
    metadata?: Record<string, unknown>;
    createdAt: Date;
    updatedAt: Date;
  };
}
```

#### `account-task:updated`

Triggered when an account task is updated.

**Payload structure:**

```typescript theme={null}
{
  task: AccountTaskData;
  previousTask: AccountTaskData;
}
```

#### `account-task:deleted`

Triggered when an account task is deleted.

**Payload structure:**

```typescript theme={null}
{
  previousTask: AccountTaskData;
}
```

### Account task comment events

#### `account-task:comment:created`

Triggered when a comment is added to an account task.

#### `account-task:comment:updated`

Triggered when a comment on an account task is updated.

#### `account-task:comment:deleted`

Triggered when a comment is deleted from an account task.

## Event structure

All account events follow the standard platform event structure:

```typescript theme={null}
interface AccountEventEnvelope<T> {
  eventId: string;
  eventType: string; // One of the AccountEvents enum values
  timestamp: string;
  orgId: string;
  actor: {
    id: string;
    type: string;
    email: string;
  };
  payload: T;
}
```

## Integration examples

### Account health monitoring

```javascript theme={null}
function handleAccountHealthChange(payload) {
  const { account, previousAccount } = payload;

  if (account.health === "At Risk" && previousAccount.health !== "At Risk") {
    // Account became at risk
    triggerAccountReview(account.id);
    notifyAccountManager(account.id);
  } else if (
    account.health === "Healthy" &&
    previousAccount.health === "At Risk"
  ) {
    // Account recovered
    logAccountRecovery(account.id);
  }
}
```

### Customer contact synchronization

```javascript theme={null}
function handleContactCreated(payload) {
  const { customerContact } = payload;

  // Sync to CRM
  syncToCRM({
    type: "contact",
    id: customerContact.id,
    email: customerContact.email,
    name: `${customerContact.firstName} ${customerContact.lastName}`,
    accountId: customerContact.accountId,
  });

  // Update marketing lists
  updateMarketingSegmentation(customerContact);
}
```

### Task management integration

```javascript theme={null}
function handleTaskCreated(payload) {
  const { task } = payload;

  if (task.priority === "High" && task.dueDate) {
    // Create calendar reminder
    createCalendarEvent({
      title: task.title,
      date: task.dueDate,
      assignee: task.assignedUserId,
    });
  }

  // Update project management tool
  syncToProjectManagement(task);
}
```

## Best practices

1. **Account hierarchy**: Use relationship events to maintain account hierarchies in external systems
2. **Data consistency**: Process events in order using the timestamp to maintain data consistency
3. **Bulk operations**: Be prepared for high-volume events during bulk imports or updates
4. **Custom fields**: Monitor custom field events for account scoring and segmentation
5. **Activity tracking**: Use activity events to build comprehensive account timelines

## Event frequency

Account events have moderate frequency but can spike during:

* Bulk imports
* Account health reassessments
* Custom field updates
* Integration synchronizations

Consider implementing appropriate rate limiting and queuing strategies for downstream processing.