# Events

> Track what people and companies do — signups, purchases, page visits — and use it in campaigns, segments, workflows and reports.

An **event** is something a person or company did: upgraded a plan, finished checkout, viewed your pricing page. Each event is recorded with **who** did it, **when**, and **details** about it (like `plan: pro` or `amount: 49`).

Events are how Workstation reacts to what happens outside the CRM — in your website, your app or your own systems. Once they're flowing you can start campaigns from them, build segments on them, run workflows, and see trends.

Open **Marketing → Events**. It has four tabs:

| Tab | What it's for |
| --- | --- |
| **Event types** | The list of events your workspace knows, with their details. |
| **Activity** | Every event as it arrives, with who did it and the details. |
| **Analytics** | Trends, breakdowns and funnels. |
| **Monitor** | Events that were turned away, and how much of your monthly allowance you've used. |

Events are part of [Send](https://workstation.repzo.com/docs/marketing/send) (the Marketing add-on).

## Event types

An event type describes one event: its name (what your code sends, like `plan_upgraded`), a display name, which record it belongs to, and its details.

There are three kinds:

| Kind | Where it comes from |
| --- | --- |
| **Defined** | Created on the **Event types** tab (or through the API). Its details have fixed types, and events that don't match are turned away. |
| **Learned** | Created automatically the first time a new event name arrives. Details are added as they appear and are not strict. |
| **Built-in** | What Workstation records for you: lead form submitted (your website forms and Meta, LinkedIn and Google lead forms), deal created, deal stage changed, deal won, deal lost, order created, order stage changed, ticket created, ticket status changed. |

Editing a learned type makes it defined.

### Attaches to

Each type belongs to one kind of record: **Contacts**, **Accounts**, **Deals**, **Tickets**, or **No record**. Related records fill in automatically — an event on a deal also shows on the deal's contact and account; an event on a contact also shows on their account.

### Details (properties)

Event details use the same field types as [Properties](https://workstation.repzo.com/docs/administration/properties): text, long text, number, currency, yes/no, date, date & time, dropdown, multiple choice, URL, email, phone and country. On a defined type, a value that doesn't fit its type turns the event away (you'll see why in **Monitor**).

### Visitor details

With **Fill in visitor details automatically** on, each event also gets where and how it happened: city, region, country, time zone, device type, browser, operating system, and the page URL, path and referrer. The visitor's IP address is used to find the place and is never stored.

## Sending events

### From your website

The Workstation [Messenger](https://workstation.repzo.com/docs/operations/inbox) on your site can record events:

```js
RepzoWidget.track("viewed_pricing", { page: "/pricing" });
```

Forms on your site record **Lead form submitted** for you, with the form's answers — no code needed. See [Forms](https://workstation.repzo.com/docs/marketing/forms).

Website visitors are tracked even before they tell you who they are. When the same visitor later becomes a contact — they sign up, or your server sends an event with their email and the visitor's id — their earlier website events move onto that contact.

### From your server (API)

Send one event with `POST /api/v1/send/events`:

```bash
curl -X POST https://your-workspace.example.com/api/v1/send/events \
  -H "Authorization: Bearer foxa-…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "plan_upgraded",
    "email": "maya@example.com",
    "properties": { "plan": "pro", "seats": 12 },
    "dedupeKey": "invoice-1042"
  }'
```

Or up to 500 at once with `POST /api/v1/send/events/batch` — each event gets its own result, so one bad event never stops the rest. Use batch for anything more than a handful of events: the API allows **120 requests a minute**.

**Finding the record.** Send whichever identifier you have. For a contact event Workstation tries, in order: `contactId`, `identityId` (website or app visitor), `match`, `email`, then `phone`. Accounts use `accountId`, `match` or `domain`; deals `dealId` or `match`; tickets `ticketId`, `ticketNumber` or `match`. `match` finds a record by any property whose value is unique, like `{ "property": "custom_…", "value": "C-1042" }`.

**New contacts.** Add `"createContact": true` to create the contact when nobody matches the email or phone. An optional `contact` block (first and last name, phone, company, title, source, UTM fields) fills in the **new** contact only — an existing contact is never changed.

**No double counting.** Give each occurrence a `dedupeKey`. Sending the same name and key again returns `200` with `duplicate: true` and records nothing.

The Developer App needs the **Tracked Events** scope: `tracking:write` to send, `tracking:read` to read. A key with only that scope can't send messages. See [Developer API](https://workstation.repzo.com/docs/configuration/developer-api).

### Other ways in

- **Mobile app**: events your app logs through the Messenger SDK.
- **Import**: past events from a CSV or Excel file — see [Data import & export](https://workstation.repzo.com/docs/administration/data-import-export). Imported events never start campaigns or workflows.
- **CLI**: `repzo send event`, `repzo send events batch`, `repzo send events list`, `repzo send event-types …`.

## Where events show up

- **Activity** tab — everything, filterable by event, source, record, and date.
- The **Events** tab and the **Timeline** on contacts, accounts, deals and tickets. Admins can show or hide the Events tab in [Objects](https://workstation.repzo.com/docs/administration/objects).

## Using events

- **Start a send** — in [Send](https://workstation.repzo.com/docs/marketing/send), choose **When someone does an event** as the start, pick the event, and optionally add conditions on its details ("plan is pro").
- **Mobile push** — the same, from the push's rules.
- **Segments** — "has done / has not done an event", how often and when, with detail conditions. See [Segments](https://workstation.repzo.com/docs/marketing/segments).
- **Workflows** — start a workflow with the **Event Happens** trigger, or pause one with **Wait Until Event Happens** (for example, wait up to 3 days for `channel_connected` and remind them if it doesn't happen). See [Workflows](https://workstation.repzo.com/docs/administration/workflows).
- **Goals** — a send's goal can be an event done after receiving it.
- **Personalisation** — use `{{event.plan}}` and other event details in messages started by an event.

## Analytics

The **Analytics** tab has three views:

- **Trends** — how often events happened over time, as totals or unique contacts or accounts, compared with the previous period.
- **Breakdown** — split one event by a detail, a visitor detail (country, device…) or source.
- **Funnel** — 2–5 steps in order within a time window (for example viewed pricing → started signup → became paying), with drop-off between steps.

Click a bar or step to see the events behind it.

## Monitor

When an event is turned away it's listed in **Monitor** with the reason — for example no matching contact, a detail of the wrong type, an archived event, or a limit reached — and what was sent. Errors are kept 30 days.

## Limits and retention

| Limit | Value |
| --- | --- |
| Event types per workspace | 500 |
| Details per event | 50 |
| Event and detail names | 100 / 50 characters |
| Text values | 256 characters (1,024 for URLs) |
| Events per batch | 500 |
| API requests | 120 a minute |
| Events per month | 5,000,000 |

Events are kept for two years. Daily counts are kept for good, so long-range charts keep working.

## Exporting

Export events from **Settings → Data Management → Export** — filter by event, date, source and record type. Each detail gets its own column.

## Permissions

| Permission | Allows |
| --- | --- |
| View events | See Activity, Analytics, Monitor and record Events tabs; export. |
| View event types | See the event types list. |
| Manage event types | Create, edit, archive and delete event types; record events through a CLI login. |

## Related pages

- [Send](https://workstation.repzo.com/docs/marketing/send)
- [Segments](https://workstation.repzo.com/docs/marketing/segments)
- [Workflows](https://workstation.repzo.com/docs/administration/workflows)
- [Data import & export](https://workstation.repzo.com/docs/administration/data-import-export)
- [Developer API](https://workstation.repzo.com/docs/configuration/developer-api)