Groups
Groups (called SourceAuthorCompany internally) represent companies or organizations that your users belong to. They're useful for B2B products where you want to segment feedback by company.
How groups work
Call the group function to associate a user with a company. Each group is identified by a unique groupId within a source.
Web
told('group', 'company_456', {
name: 'Acme Corp',
industry: 'SaaS',
employees: '50',
plan: 'enterprise'
});
Android (Kotlin)
Told.group("company_456", mapOf(
"name" to "Acme Corp",
"industry" to "SaaS"
))
iOS (Swift)
Told.group(id: "company_456", properties: [
"name": "Acme Corp",
"industry": "SaaS"
])
What is stored per group
| Field | Description |
|---|---|
groupId | Required. Unique company identifier in your database |
source | The source this group belongs to |
customData | Key-value object with all traits you send |
groupSize | Number of associated users |
Supported custom data fields
These fields have semantic meaning in Told:
| Trait | Type | Description |
|---|---|---|
id | String | Unique group ID (same as groupId) |
name | String | Company name |
email | String | Company email |
phone | String | Phone number |
website | String | Website URL |
industry | String | Industry |
employees | String | Number of employees |
plan | String | Current plan/subscription |
avatar | String | Logo/avatar URL |
address | Object | Postal address (city, country, postalCode, street, state) |
description | String | Company description |
createdAt | Date | Creation date (ISO-8601) |
Any additional key-value pairs are stored in customData for audience filtering.
When to call group
- When a user creates a new company
- When a user joins an existing group
- When group information changes
To remove a trait, call the function and set the trait value to null.
Import groups
Bulk import groups:
- Go to your source's Audience section → Companies tab
- Click Import
- Upload a JSON or CSV file
Each entry must include a mandatory id field. Include a users field with a list of user IDs to associate. If a user doesn't exist, they will be created.
Viewing groups
Groups are visible in the Companies tab of your source's Audience section. Click on a company to see a drawer with its details and associated users.
Using groups for targeting
Group traits can be used as filters in audiences for targeting surveys to users of specific companies.