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

# Trigger Account Event

> Record an event on an account and deliver it to its members

# Trigger Account Event

Records the event on the account timeline and delivers it to the chosen recipients as a normal contact event, so sync rules, sequence triggers and matching-field enrollment run per person. Each delivery carries `event.account.externalId`, `event.account.name`, `event.account.role` and the account attributes.

## Request

<ParamField path="externalId" type="string" required>
  Your organization ID.
</ParamField>

<ParamField body="event" type="string" required>
  Event name, for example `trial_ending`, `plan_changed`, `seat_limit_reached`.
</ParamField>

<ParamField body="properties" type="object">
  Event properties, available as `event.<name>` in sequences.
</ParamField>

<ParamField body="recipients" type="string" default="owners">
  `owners` (falls back to admins when the account has no owner), `admins`
  (owners and admins), `all` (every member) or `none` (timeline only).
</ParamField>

<ParamField body="eventId" type="string">
  Idempotency key scoped to this account. Accounts can reuse an ID even when
  they share members. Retries reuse the original recipients, properties and
  event time, even if account membership changes. Completed deliveries are
  skipped; failed deliveries resume without duplicating contact events or
  sequence enrollments. Recipients deleted since the event was recorded are
  reported with `skipped: "contact_deleted"` and are not retried. The response
  carries `duplicate: true`.
</ParamField>

<ParamField body="occurredAt" type="string">
  ISO 8601 timestamp of when the event happened. Defaults to now.
</ParamField>

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/accounts/org_123/events" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "trial_ending", "properties": { "daysLeft": 3 }, "recipients": "owners", "eventId": "trial-org_123-2026-09-04" }'
```

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "account": { "id": "acc_abc123", "externalId": "org_123", "name": "Acme", "memberCount": 3 },
    "event": { "id": "trial-org_123-2026-09-04", "name": "trial_ending", "time": "2026-09-04T09:00:00.000Z" },
    "recipients": "owners",
    "recipientCount": 1,
    "truncated": false,
    "duplicate": false,
    "deliveries": [
      { "subscriberId": "sub_1", "email": "jane@acme.com", "role": "owner", "success": true, "automationsTriggered": ["auto_trial"] }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "Account event `recipients` must be one of owners, admins, all, none."
  }
  ```

  ```json 500 theme={null}
  {
    "success": false,
    "error": "Delivered to 2 of 3 recipients; 1 failed. Retry with the same eventId to re-attempt only the failed recipients.",
    "recipientCount": 3,
    "deliveries": [
      {
        "subscriberId": "sub_2",
        "email": "bob@acme.com",
        "role": "owner",
        "success": false,
        "automationsTriggered": [],
        "error": "..."
      }
    ]
  }
  ```

  ```json 404 theme={null}
  { "success": false, "error": "Account not found" }
  ```
</ResponseExample>