Companies and groups

A group type is a kind of account in your product: company, workspace, team. A group is one of them, such as the company cmp_311. “Group” is the word in code. In the app you see each type’s own name, so this page says Companies.

How it works

Each event carries the groups it belongs to, in a $groups property. An event counts for a company only when it carries that company:

{
  "name": "Report exported",
  "properties": {
    "format": "csv",
    "$distinct_id": "user_8412",
    "$groups": { "company": "cmp_311", "workspace": "ws_91" }
  }
}

• The group call remembers the company and stamps it on every later event from that browser or app. From a server, you add the company to each event yourself.
• History stays true. When Dana moves from Acme to Globex, her old events still count for Acme.
• Nothing is back-filled. Events sent before the first group call never count for the company.
• Members are worked out, not stored. A company’s members are the people whose events carried it in the dates you’re looking at.
• Traits describe the company: its name, plan, seats. They live in a company profile, separate from events.

Group analytics is on for every project and every plan. The Companies pages and the Count by controls stay hidden until your project has received its first group, so a product without company accounts sees no change.

From the browser

Call group once after sign-in, next to identify:

// After sign-in, once you know which company the person is acting for
window.clickclacks('group', 'company', 'cmp_311', {
  name: 'Acme',
  plan: 'pro',
  seats: 40,
})

// A second type, without traits
window.clickclacks('group', 'workspace', 'ws_91')

// Leave the company
window.clickclacks('group', 'company', null)

• The browser remembers one ID per type, at most 5 types, and adds them to every later event as $groups.
• With traits, the call also sends a $group_identify event that carries them. It’s free: it doesn’t count toward your monthly events.
• null as the ID leaves the group. reset and optOut forget every group.
• A call with a bad type or ID is ignored, like any other bad call.
• Groups are stored per hostname, like the identified ID. Call group on each domain where the person is signed in.

The full rules are under group in the Tracker API.

From your servers

A server doesn’t remember anything between events, so there are two parts: a group item records the company’s traits, and each event names its company.

curl https://app.clickclacks.io/api/v1/batch \
  -H "Authorization: Bearer $CLICKCLACKS_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[
    {"type":"group","group_type":"company","group_id":"cmp_311","properties":{"name":"Acme","plan":"pro","seats":40}},
    {"event":"Seats changed","distinct_id":"user_8412","properties":{"seats":41,"$groups":{"company":"cmp_311"}}}
  ]}'

// The company's traits. The newest call replaces the whole set.
clickclacks.group({
  groupType: 'company',
  groupId: 'cmp_311',
  properties: { name: 'Acme', plan: 'pro', seats: 40 },
})

// An event that counts for the company.
clickclacks.track({
  event: 'Seats changed',
  distinctId: 'user_8412',
  properties: { seats: 41 },
  groups: { company: 'cmp_311' },
})

// The company's traits. The newest call replaces the whole set.
$clickclacks->group([
    'groupType' => 'company',
    'groupId' => 'cmp_311',
    'properties' => ['name' => 'Acme', 'plan' => 'pro', 'seats' => 40],
]);

// An event that counts for the company.
$clickclacks->track([
    'event' => 'Seats changed',
    'distinctId' => 'user_8412',
    'properties' => ['seats' => 41],
    'groups' => ['company' => 'cmp_311'],
]);

• Over HTTP, an event names its company in properties.$groups. The Node and PHP SDKs take a groups option and write it for you.
• A group item has no person, so it takes no distinct_id. Group items are free.
• An event sent without its company never counts for it later.

See Groups in Send events for the item’s fields, the warnings in the response and the error codes, and the Node and PHP SDK pages.

From a mobile app

The React Native and Expo SDK has the same call. It remembers the company on the device and stamps it on every later event.

clickclacks.group('company', 'cmp_311', { name: 'Acme', plan: 'pro', seats: 40 })

clickclacks.group('company', null) // leave

Calling it again with the same traits sends nothing until 7 days have passed, so it’s safe to call on every launch. See Mobile apps.

Traits and privacy

• The newest traits replace the whole set. Send every trait you want shown each time, not only the one that changed.
• A name trait is what the app shows for the company. Without one, it shows the ID.
• Use opaque IDs, such as cmp_311, not a domain name or an email address.
• Profiles follow your data retention. A profile whose traits were last sent longer ago than the project keeps events is deleted. Sending traits at sign-in keeps the profiles of active companies current.

A company profile is seen by everyone who can open the project, so traits that look like personal data are left out by default:

• a trait whose value reads as an email address or a phone number;
• a trait named like email, phone, ip, address, password or secret, including names that contain one of those words, such as billing_email.

The server API lists each trait it left out in the response’s warnings, as group_trait_dropped. With ?strict=true it refuses the item instead. The browser and the mobile SDK get no answer, so there the trait is simply missing from the profile. If you do need a billing contact on the profile, turn on Allow personal data in group traits on the source’s page.

The Companies pages

Once your project has received a group, Companies appears in the sidebar under Data, after People. With two or more group types the entry reads Groups and the page has a tab for each type.

• The list shows each company’s name and ID, its active members and events in the date range, and when it was last and first seen. Search by name or ID, sort by last seen, events, active members or name, and pin up to three traits as extra columns.
• A company’s page shows its traits and when they were last updated, its members in the date range, and its activity, with Open in Insights to chart it.
• A person’s page lists the companies their recent events carried.
• Delete profile removes a company’s saved traits and can’t be undone. Events aren’t changed: they keep their company, so it still appears in reports and in the list, shown by its ID. It needs permission to change the organization’s settings.

To rename a type, reorder types or hide one, open Lexicon and the Group properties tab. A hidden type leaves the sidebar and Count by; its data is kept. The same tab is where you describe each trait.

Count by Companies

• Only stamped events count. A company-counted report says how much it left out, for example “12% of these events have no company and aren’t counted”.
• Count by is saved with the report. Funnels and Retention also carry it in the URL, as ?by=company.
• A funnel that counts companies can’t use events mode, which counts sessions, and sessions belong to people.
• Compare in Funnels and Retention lists the segments of what the report counts: company segments of that type when it counts companies, segments of people when it counts people.
• An alert on a funnel or retention report that counts companies counts companies too.
• Insights can also break a series down by company, or by a company trait. Trait breakdowns use each company’s current traits.
• Flows always counts people: a company’s events mix several people’s paths.

Filters and segments

• Filter by company. The property picker in a report’s filter bar has a Company section (the company itself) and Company properties (its traits). A chip reads “Company is Acme” or “Company plan is pro”. These filters work in reports that count people too: “people in companies on the Pro plan”.
• On boards. A board’s filters take the same company filters, and an insight tile that counts companies keeps doing so on the board.
• Company segments. When you create a segment, choose whether it holds people or companies; it can’t be changed afterwards. A company segment matches on what the company’s members did or never did, on a trait, or on a fixed list. As a filter on any report it means “events from the segment’s companies”, whatever the report counts. It also narrows the Companies list, and Funnels and Retention can compare company segments when they count that type. Realtime takes segments of people only. Company segments have no “did this, then that” sequence condition and no chart of their size over time.

Reading from an AI agent? The MCP server has tools for group types, companies and company profiles.

Limits

Groups or a project per client?

They answer different questions, so they don’t compete.

• An agency gives each client its own project. That’s the boundary that keeps one client from seeing another’s data. Groups never replace it. See Agencies.
• Use groups inside a client’s project when that client sells to companies. Its project then counts its own customers.
• Don’t run several clients through one project as groups. There is no access control per group.

Questions

Why doesn’t this old event count for Acme?

It was sent before the browser or app called group, or from a server without $groups. An event is stamped when it is sent, and is never stamped afterwards.

Why isn’t Companies in my sidebar?

It appears once the project has received an event that carries a group. If it has, check in Lexicon’s Group properties tab that the type isn’t hidden.

Someone moved to another company. What happens?

Call group with the new ID. Their later events count for the new company, and their earlier ones stay with the old one.

Can a person be in two companies at once?

A browser or app holds one ID per type at a time, so one company and one workspace, but not two companies. From a server, each event names its own company.

Do group calls use up my events?

No. The trait update ($group_identify, or a group item) is free. Ordinary events count as they always did, with or without a company.

Do merged people change company counts?

No. A merge changes who a person is. The company is on the event, so company counts stay the same.

Can I remove a company from my events?

No. Delete profile removes the traits only; events are never rewritten. Deleting a person removes their events, and with them their part of a company’s counts.

Next steps

• Tracker API: the group command in full.
• Send events: the group item, $groups and warnings.
• Mobile apps: groups from React Native and Expo.
• Identify people: the call that goes next to group.