Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.permutive.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Import user group memberships (e.g., household relationships) from your data warehouse using Connectivity. This enables household-level identity resolution and allows you to build User Group Cohorts that target groups of users rather than individuals.
Prerequisites:
  • Connectivity set up and configured for your data warehouse
  • At least one User-level identifier configured in Identity > Identifiers
  • At least one User Group-level identifier configured in Identity > Identifiers
  • User group membership data available in your data warehouse

​
Steps

1

Configure required identifiers

In Identity > Identifiers, ensure you have:
  • At least one User-level identifier (e.g., email_sha256, appnexus) for identifying individual users
  • At least one User Group-level identifier (e.g., household_id, group_id) for identifying user groups
2

Prepare data warehouse table

Create or identify a table in your data warehouse with the following columns:
  • user_id (required): Contains user identifiers matching your configured User-level identifier
  • group_id (required): Contains group identifiers matching your configured User Group-level identifier
  • cursor (required): Timestamp column indicating when the user was added to the group (used for incremental processing)
  • is_deleted (optional): Boolean column where TRUE indicates the user should be removed from the group
3

Create Connectivity connection

In the Permutive dashboard, navigate to Connectivity and create a new connection to your data warehouse if one doesn’t exist.
4

Create Group Identity Data import

Create a new Connectivity import and select Group Identity Data as the data type. This import type is specifically designed for user group membership data.
5

Configure import columns

Map your data warehouse columns to the required fields:
  • Map the Group ID column to your User Group-level identifier
  • Map the User ID column to your User-level identifier
  • Map the Timestamp column to your cursor field
  • Optionally map the Delete column if you have an is_deleted field
6

Verify import success

After the first import runs, verify in the Connectivity dashboard that data was successfully imported. Check for any error messages in the import logs.

​
Data Format Requirements

Your data warehouse table should follow this structure:
user_idgroup_idcursoris_deleted
user123household4562025-01-01 10:00:00FALSE
user124household4562025-01-01 10:00:00FALSE
user125household4572025-01-02 14:30:00FALSE
user123household4562025-01-15 09:00:00TRUE
Important notes:
  • Each Connectivity import supports only one type of identifier for User and Group data
  • You cannot mix multiple identifier types (e.g., both HEM and AppNexus IDs) in the same import
  • The user_id can be a Permutive user ID or any configured User-level identifier
  • The group_id must match a configured User Group-level identifier

​
Managing Stale Data

There are two approaches to managing data that is no longer current: Explicit deletions (recommended for most use cases) Use the is_deleted column to signal which rows should be removed. This is the most efficient approach — only changed and deleted rows are processed, which minimizes data egress from your warehouse and keeps processing volumes low. If your source system can produce deletion rows, this is the cheaper, more deterministic option. Data retention (TTL) As an alternative, you can configure a data retention period when creating the import. This causes imported group memberships to expire automatically after the configured number of days, removing the need to explicitly signal deletions in your source data. This is useful when communicating deletions is cumbersome or not supported by your source system — for example, household graphs that are refreshed in full on a regular schedule. Set a retention period that comfortably exceeds your refresh frequency, and old memberships will roll off on their own.
We recommend setting the retention period at least 2–3 days longer than your import frequency to allow for delayed processing. For example, if you refresh daily, a retention period of 3–7 days is a good starting point. Very short retention periods risk losing active data if an import run is delayed.
Tips for user group imports:
  • Use a timestamp column that updates whenever a user-group relationship changes
  • The cursor column enables incremental processing, so only new or changed rows are processed
  • Ensure identifier values in your data match exactly the namespaces configured in Permutive
  • Test with a small dataset first to verify the import configuration
Important:
  • Both User-level and User Group-level identifiers must be configured before creating the import
  • The identifier types in your data must exactly match the namespaces configured in Permutive
  • Each import can only use one identifier type for user_id and one for group_id
  • If you need to use multiple identifier types, create separate imports for each type
  • User group membership data is processed incrementally based on the cursor column

​
Next Steps

Configuring Identifiers

Set up User-level and User Group-level identifiers

User Group Cohorts

Learn about building cohorts that target user groups

Back to Identity Graph

Return to Identity Graph overview