Amplitude

The Accoil streaming integration for Amplitude forwards events, user data, and account data directly into Accoil. Once configured, Amplitude events stream to Accoil in real time.

Prerequisites

Before configuring the integration, ensure you have:

• An active Accoil workspace
• An API key from your Accoil account

Create a New Sync in Amplitude

1. In Amplitude, go to Data > Catalog and select the Destinations tab.
2. Under Customer Engagement, select Accoil.
3. Enter a Sync Name, then click Create Sync.

Enter Credentials

1. Paste your Accoil API key into the input field.
2. Under Select & filter events, select All Events.
3. Click Test Connection.

Accoil will validate the connection. If successful, data streaming begins immediately. After enabling the connection, it may take 1 to 2 minutes for events to appear in Accoil.

Configure Sync Settings

1. Select and Filter Events

By default, all events in Amplitude are selected for forwarding. This is the recommended setting to maximize visibility into product usage across the user lifecycle.

You may optionally:

• Filter to include only events with a User ID
• Manually select specific event types to send

2. Map Properties to Destination

Map a unique user identifier from Amplitude to Accoil:

• Amplitude Property: Select the user property that uniquely identifies users in your product (e.g., user_id, email, or a custom ID).
• Accoil Property: This automatically maps to userId.

This ensures all event data is associated with the correct user profile in Accoil.

3. Select Additional Properties (Optional)

Specify additional event or user properties to send to Accoil. These are included as metadata with each event and can be used for segmentation, filtering, and targeting.

Examples: trial_end, plan_type, api_key, api_token_id, status.

Send any attributes that may be useful for building user cohorts or dashboards, even if you are not using them immediately.

Finalize and Enable Sync

1. Review your configuration.
2. Toggle the Status switch to Enabled.
3. Click Save.

Your Amplitude events will now stream to Accoil in real time.

Group and Account Data Mapping

When streaming events from Amplitude to Accoil, group-level data (such as account identifiers and associated metadata) is extracted from the Amplitude event payload and mapped into a structure that Accoil can process for account-level insights.

Where Group Data Comes From

Amplitude events can include:

• A groups object that identifies which group(s) the event is associated with (e.g., an Account).
• A group_properties object that contains metadata for each group (e.g., domain, name, or other custom traits).

These two fields are used together to determine which account each event belongs to and what traits should be attached to that account in Accoil.

Identifying Groups in the Event

If both groups and group_properties are present in the event, the mapping logic:

• Iterates through all group types (e.g., Account).
• Collects the group IDs under each type.
• Retrieves associated metadata (traits) for each group ID from group_properties.

This produces a list of candidate groups, each containing a groupId (the unique identifier) and traits (metadata fields).

Selecting a Primary Group

If multiple groups are present, they are sorted by groupId in ascending order, and the first group is selected as the primary group. This ensures consistency in how group data is attached to events.

Most implementations use a single group type (e.g., Account) per event, so this logic typically selects the expected group by default.

Mapped Group Traits

Once the primary group is selected, its identifier and metadata are formatted into the Accoil-compatible structure under the groupTraits field:

"groupTraits": [
  {
    "groupId": "210000",
    "traits": {
      "domain": "accoil.com",
      "group_type": "Account",
      "name": "Released Import Test"
    }
  }
]

These traits are used in Accoil to enrich account profiles, support segmentation and cohort analysis, and enable filtering within dashboards.

Summary

• Amplitude events must include both groups and group_properties to pass account-level data to Accoil.
• A single group is selected per event based on a predictable sort order.
• Group metadata is included in the payload and used to build account-level context in Accoil.