Group Call

The group call tells Accoil about an account (company, team, or organization) and optionally links a user to it. In B2B analytics, the account is where most strategic decisions happen -- plan changes, revenue, health scores -- so keeping account data accurate is critical.

When to fire a group call

Account is created -- send the initial account traits (name, plan, status)
User joins an account -- link the user to the account via userId
Account traits change -- plan upgrade, MRR change, status change (trial to paid)
On a recurring schedule -- for snapshot metrics like usage counts

Required fields

Field	Type	Description
`groupId`	string	A unique, stable identifier for the account.
`userId`	string	The user being associated with this account.
`timestamp`	string (ISO 8601)	When this call occurred. Defaults to current UTC time if omitted.

Match your group ID across platforms

If you use HubSpot, Intercom, or another CRM, use the same account identifier as your groupId. This enables Accoil to push engagement scores and metrics directly into those platforms without additional mapping.

Recommended traits

Trait	Recommendation	Type	Sample values	Description
`name`	Highly recommended	string	`"Acme Corp"`	The account's display name. Without this, accounts appear as raw IDs in the Accoil UI.
`created_at`	Highly recommended	string (ISO 8601)	`"2023-01-15T12:00:00Z"`	When the account was created. Used for tenure calculations.
`status`	Highly recommended	string	`"trial"`, `"paid"`, `"canceled"`	Subscription status. Enables segmentation by lifecycle stage.
`plan`	Recommended	string	`"starter"`, `"pro"`, `"enterprise"`	The account's plan tier. Helps analyze engagement by pricing tier.
`mrr`	Recommended	integer	`100000` (for $1,000)	Monthly recurring revenue in cents. Enables revenue-weighted analysis and segment dollar values.

MRR is in cents

The mrr trait expects an integer value in cents. Send 100000 for $1,000.00, not 1000. This avoids floating-point precision issues and is consistent with how Stripe and other billing systems report revenue.

Example payload

{
  "groupId": "account_67890",
  "userId": "user_12345",
  "traits": {
    "name": "Acme Corp",
    "created_at": "2023-01-15T12:00:00Z",
    "status": "paid",
    "plan": "enterprise",
    "mrr": 100000
  },
  "timestamp": "2025-01-28T12:00:00Z"
}

cURL example (v2)

curl -X POST https://in.accoil.com/v2/group \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -d '{
    "groupId": "account_67890",
    "userId": "user_12345",
    "traits": {
      "name": "Acme Corp",
      "created_at": "2023-01-15T12:00:00Z",
      "status": "paid",
      "plan": "enterprise",
      "mrr": 100000
    },
    "timestamp": "2025-01-28T12:00:00Z"
  }'

The API returns 202 Accepted. Processing happens asynchronously.

Group calls without a user

You can send a group call with only a groupId and traits to update account information without associating a specific user. This is useful for scheduled jobs that sync account-level data like MRR or usage counts.

{
  "groupId": "account_67890",
  "traits": {
    "mrr": 120000,
    "total_project_count": 47
  },
  "timestamp": "2025-02-01T00:00:00Z"
}

Best practices

Send group early. The group call should follow the identify call so that events are attributed to both the user and the account.
Use stable account IDs. Use your database primary key or billing system ID, not the account name.
Always include name. Without a name, accounts display as opaque IDs in the Accoil dashboard.
Keep status and plan current. These fields drive segmentation. Send a group call whenever they change.
Send mrr in cents. Integer cents avoid floating-point rounding and match billing system conventions.
Use group calls for snapshot metrics. Scheduled jobs that report usage counts (e.g., total_project_count) should send group calls with those values as traits. See Snapshot Metrics.

How Accoil Works -- the three-call model overview
Identify Call -- creating user profiles
Track Call -- recording events
Group Hierarchy -- multi-level account structures
Snapshot Metrics -- tracking what exists

Group Call

On this page