Skip to main content

​
Overview

Import user identity data from your data warehouse using Connectivity. This enables you to link additional user-level identifiers to existing users in the Identity Graph, allowing for cross-device and cross-system identity resolution.
Prerequisites:
  • Connectivity set up and configured for your data warehouse
  • A first User-level identifier configured in Identity > Identifiers (acts as the match key)
  • A second User-level identifier configured in Identity > Identifiers (the identifier to import)
  • User identity data available in your data warehouse

​
Steps

1

Configure required identifiers

In Identity > Identifiers, ensure you have:
  • A first User-level identifier (e.g., permutive_user_id, email_sha256) that will act as the match key. Note: both columns are treated symmetrically, but it helps to think of the first as the match key.
  • A second User-level identifier (e.g., rampid, uid2) that you want to import and link to users
2

Prepare data warehouse table

Create or identify a table in your data warehouse with three columns (names can be anything):
  • Match key column (required): Contains user identifiers matching your first User-level identifier — used to find existing users
  • Identifier to import column (required): Contains the new identifiers you want to link to matched users
  • Timestamp column (optional): Indicates when the identity mapping was created (used for incremental processing)
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 User Identity Data import

Create a new Connectivity import and select User Identity Data as the data type. This import type is specifically designed for linking user-level identifiers.
5

Configure import columns

Map your data warehouse columns to the required fields:
  • Map the First ID field to your primary User-level identifier (the match key)
  • Map the Second ID field to your secondary User-level identifier (the identifier to import)
  • Map the Timestamp field to your cursor column
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 needs three columns. The column names can be anything — what matters is the data each column contains:
Match Key (First ID)Identifier to Import (Second ID)Timestamp (Cursor)
user123ramp_abc1232025-01-01 10:00:00
user124ramp_def4562025-01-01 10:00:00
user125ramp_ghi7892025-01-02 14:30:00
Important notes:
  • Match Key (First ID): Contains the identifier used to find existing users in your Identity Graph. If no matching user is found, a new user is created with both identifiers.
  • Identifier to Import (Second ID): Contains the new identifiers you want to add to matched users.
  • Timestamp (Cursor): Used for incremental processing — only rows with timestamps newer than the last import are processed.
  • Each import supports only one identifier type per column. You cannot mix multiple identifier types (e.g., both HEM and AppNexus IDs) in the same import.
  • If you need to import multiple identifier types, create separate imports for each type.

​
How Conflicts with Existing Data Are Handled

When import data references users that already exist in the Identity Graph, the outcome depends on the current state:
ScenarioOutcome
Both users exist, target has no identity of that typeSecond identity added to first user
Both users exist, target already has that identifier typeRow skipped
Only first user existsSecond identity added to first user
Only second user existsFirst identity added to second user
Neither user existsNew user created with both identities
Tips for user identity imports:
  • Use a timestamp column that records when the identity mapping was created
  • The timestamp column enables incremental processing, so only new rows are processed on each sync
  • Ensure identifier values in your data match exactly the namespaces configured in Permutive
  • Test with a small dataset first to verify the import configuration
  • If a match key identifier exists in the Identity Graph, the second identifier is linked to the existing user. Otherwise, a new user is created
Important:
  • Both User-level identifiers (First ID and Second ID) must be configured in Identity > Identifiers before creating the import
  • The First ID and Second ID must be of different identifier types — you cannot use the same type (e.g., email_sha256) for both columns
  • If using permutive_id as an identifier type, ensure all values are valid UUIDs
  • The identifier types in your data must exactly match the namespaces configured in Permutive
  • Each import can only use one identifier type for the First ID and one for the Second ID
  • If you need to import multiple identifier types, create separate imports for each combination
  • User identity data is processed incrementally based on the timestamp column
  • If neither identifier exists in the Identity Graph, a new user will be created with both identifiers associated with it

​
Next Steps

Configuring Identifiers

Set up User-level identifiers for your Identity Graph

Importing User Group Memberships

Learn about importing household and group relationships

Back to Identity Graph

Return to Identity Graph overview