Skip to main content

Guides

Issues

FAQ

What’s ChangedImports is now a dedicated top-level page, consolidating all import functionality — both Data Warehouse and Lake Imports and Second-Party Data imports — that previously lived across a Sources tab and the Audience Imports page. Setting up and managing your warehouse/storage connections now lives on the separate Connections page; once a connection is Active, come here to configure what data to import.

​
Overview

Imports is the area within the Connectivity Suite where you configure how external data flows into Permutive, allowing you to further enrich your available first-party data and build cohorts from it. There are two import flows, depending on where your data lives:
  • Data Warehouse and Lake Imports — bring data in from a data warehouse or cloud storage platform (such as BigQuery, Snowflake, Amazon S3, or Google Cloud Storage) that you’ve already connected to Permutive. Use this flow for user profile, activity, identity, group identity, or segment data that lives in your own systems. Data Warehouse and Lake Imports require an active connection — set one up on the Connections page first.
  • Second-Party Data — receive audience segments shared by a partner, CRM, or DMP, either through file upload to a Permutive-managed Google Cloud Storage bucket or through LiveRamp’s distribution network. This flow does not require a connection.
Not sure which applies to you? If you’re bringing in data from your own data warehouse or cloud storage account, you’re doing a warehouse or lake import. If a partner or CRM is sending you pre-built audience segments via file upload or LiveRamp, you’re doing a Second-Party Data import. Once processed, imported data becomes available for cohort building. Second-Party Data segments appear in the Cohort Builder under the “Audience Imports” condition type.

​
Why Use Imports?

Bring your warehouse data to life — Import user profile, activity, identity, group, or segment data directly from your connected data warehouse or cloud storage into Permutive, without needing a partner integration or file upload. Interoperability — Monetize all data points from external sources alongside your first-party data. Import segments from any system that can export user lists, enabling a unified view of your audience. Second-party data partnerships — Receive audience data from trusted partners. Partners can share their audience segments with you through GCS file uploads or LiveRamp distribution, enabling collaborative data strategies. CRM integration — Import subscriber lists, customer segments, or membership tiers from your CRM. Target known users across your properties with personalized campaigns based on their customer status. Third-party enrichment — Layer data provider segments onto your audiences. Import demographic, interest, or intent data from third-party providers to enhance your targeting capabilities.

​
Concepts

​
Definitions

  • Import: A configured pipeline that brings external data into Permutive. Imports fall into two flows: Data Warehouse and Lake Imports, which pull data from an active connection to your data warehouse or cloud storage, and Second-Party Data imports, which receive data via file upload or LiveRamp distribution.
  • Connection: A configured link between Permutive and a data warehouse or storage platform, set up and managed on the Connections page. An active connection is required before you can create a warehouse or lake import.
  • Taxonomy (Second-Party Data): A mapping that associates segment codes with human-readable names, descriptions, and optional metadata like CPM pricing. The taxonomy defines what each segment code means and how it appears in the Dashboard.
  • Data Provider / Audience Set (Second-Party Data): A logical grouping mechanism for organizing segments from different sources. Each Second-Party Data import is associated with a data provider, which helps separate segments from different partners or use cases.
  • Segment Code (Second-Party Data): A unique identifier for a segment within an import. Segment codes are defined in the taxonomy and referenced in data files. Codes are alphanumeric strings — best practice is to use sequences (e.g., “0001”, “s001”) rather than human-readable words.
  • Import Lifetime (Second-Party Data): The time-to-live (TTL) for imported segment memberships. After the lifetime expires, users are removed from the segment unless refreshed by a new data upload. Default is 60 days, set at the import level.

​
Data Warehouse and Lake Import Flow

The warehouse or lake import process follows this sequence:
  1. Connection Setup: Establish and activate a connection to your data warehouse or cloud storage on the Connections page
  2. Import Creation: Configure an import in the Dashboard, choosing the data type (User Profile, Activity, Identity Graph, Group Identity, or Segment) and the source table and columns
  3. Sync: Permutive syncs data from the source table on a recurring schedule
  4. Activation: Imported data becomes available for cohort building and targeting

​
Second-Party Data Flow

The Second-Party Data import process follows this sequence:
  1. Import Creation: Configure an import in the Dashboard, specifying the source type (GCS or LiveRamp) and data provider details
  2. Taxonomy Setup: Upload or configure the taxonomy to define segment codes and names
  3. Data Upload: Upload data files (GCS) or receive data (LiveRamp) containing user IDs and segment memberships
  4. Processing: Permutive processes the files and matches user IDs to users in your workspace
  5. Activation: Imported segments become available in the Cohort Builder

​
Workflows

​
Data Warehouse and Lake Imports: Creating an Import

Data Warehouse and Lake Imports require an active connection — see Connections if you haven’t set one up yet. Once your connection’s status is Active, you can create a warehouse or lake import to start bringing data from that connection into Permutive. When creating a warehouse or lake import, you choose the data type to import, the source table, and which columns to bring in. See the Creating an Import guide for step-by-step instructions.

​
Data Warehouse and Lake Imports: Import Types

Data Warehouse and Lake Imports support bringing in the following types of data:
  • User Profile Data — Import static user attributes such as demographics and subscription tiers for trait-based cohort building and targeting.
  • User Activity Data — Import time-stamped event or behavioral data such as purchase history or content interactions for time-bound audience building.
  • Identity Graph Data — Import user identity mappings and household graphs to enrich Permutive’s Identity Graph with identifiers and group relationships from your data warehouse. See Importing User Identity and Importing User Group Memberships for step-by-step guides.
  • User Segment Data — Import segment memberships to bring pre-built segments or audiences from your warehouse into Permutive for targeting and activation. See Importing User Segments for a step-by-step guide.

​
Second-Party Data: Creating an Import

Navigate to Connectivity > Imports in the Permutive Dashboard and click “Create Import” to begin. Select the import source (GCS or LiveRamp) and provide configuration details such as the data provider name and default segment lifetime. For GCS imports: Permutive generates a unique GCS bucket path and service account credentials. Use these credentials to upload data files to the specified bucket. For LiveRamp imports: The advertiser configures LiveRamp to distribute data to Permutive using your Permutive Organization ID (found in Settings in the Dashboard). See the LiveRamp guide for detailed setup steps.

​
Second-Party Data: Setting Up Taxonomy

The taxonomy maps segment codes to human-readable names and metadata. You can configure the taxonomy in two ways: CSV Upload: Upload a CSV file with columns for segment code, name, description, and CPM. This is ideal for initial setup or bulk updates. Taxonomy API: Use the Taxonomy API to programmatically manage segments. This supports adding, updating, and removing individual segments with batch operations of up to 5,000 operations per request.

​
Second-Party Data: Uploading Data Files

For GCS imports, upload data files containing user ID and segment mappings: Manual Upload: Use the Google Cloud Console or gsutil CLI to upload files directly to the Permutive-managed bucket. Programmatic Upload: Use the GCS service account credentials provided by Permutive to automate file uploads from your data pipeline.

​
Second-Party Data: Data File Format

Data files must follow this tab-separated format:
The same user ID can appear on multiple rows. Each row adds the specified segment memberships for that user.
Requirements:
  • Tab-separated values (USER_ID \t SEGMENTS)
  • Segment codes comma-separated (no spaces)
  • Files should be gzip compressed with .gz extension (NOT .gzip)
  • No whitespace in segment codes
  • User IDs should match identifiers tracked by your Permutive SDK

​
Second-Party Data: Taxonomy CSV Format

The taxonomy CSV defines your segments:
Fields:
  • Code (required): Unique segment code (alphanumeric, no spaces). Best practice is to use a sequence (e.g., 0001, 0002, s001) rather than human-readable words.
  • Name (required): Display name in Dashboard. Use hyphens to delimit category levels (e.g., Demographic - Inferred Gender - Female).
  • Description (optional): Segment description
  • CPM (USD) (optional): Cost per mille for third-party segments. Leave blank or 0 for self-sourced data.

​
Troubleshooting

The following issues may occur when working with Imports. For connection-level issues (authentication, catalog availability, connection status), see Connections instead.
Permission errors occur when the upload credentials don’t have write access to the Permutive-managed GCS bucket.Solution: Verify you are using the correct service account credentials provided by Permutive. Check that the credentials have not expired. If uploading via the GCS Console, ensure you are signed in with an account that has been granted access to the bucket. Contact Technical Services if credentials need to be regenerated.
File format errors occur when data files don’t match the expected format.Common issues:
  • Using spaces instead of tabs as the delimiter
  • Using .gzip extension instead of .gz
  • Whitespace in segment codes
  • Missing or malformed user IDs
Solution: Verify your files are tab-separated (not comma or space separated). Ensure files are compressed with gzip and use the .gz extension. Remove any whitespace from segment codes. Validate a sample of your file format before uploading large batches.
If uploaded segment codes don’t appear in the Dashboard, the taxonomy may not include those codes.Solution: Upload segment codes to the taxonomy before uploading data files. The taxonomy defines which segments are recognized. Codes in data files that don’t match taxonomy entries will be ignored. Use the Taxonomy API or CSV upload to add missing segment codes.
Low or zero match rates indicate that user IDs in the data file don’t match users in your Permutive workspace.Possible causes:
  • User ID format mismatch (e.g., lowercase vs uppercase)
  • Using a different identifier type than what’s tracked
  • Users haven’t visited your site/app yet
  • Segment lifetime has expired
Solution: Verify the user ID format matches exactly what your Permutive SDK tracks. Check that you’re using the correct identifier type (e.g., Permutive user ID, RampID, or custom identifier). Upload fresh data to reset segment lifetimes for expired memberships.Note that even when matching is working correctly, the Live Audience Size of cohorts built on imported data will start at zero and grow over time as users visit your properties. This is expected behavior — see Understanding Audience Size for Import Cohorts for details.
If a LiveRamp import is configured but not receiving data, there may be a configuration mismatch.Solution: Verify that the correct Permutive Organization ID was provided during LiveRamp setup (found in Settings in the Dashboard). Confirm that LiveRamp has been configured to distribute data to Permutive. Check with your LiveRamp representative that the distribution is active. Contact Permutive support at technical-services@permutive.com for assistance troubleshooting the connection.
The Taxonomy API supports a maximum of 5,000 operations per request. Requests exceeding this limit will be rejected.Solution: Split large taxonomy updates into multiple requests of 5,000 operations or fewer. Consider using CSV upload for initial bulk taxonomy creation, then use the API for incremental updates.

​
Environment Compatibility

​
Data Warehouse and Lake Import Platforms

Data Warehouse and Lake Imports are available from any platform you can connect to. See Supported Source Platforms on the Connections page for the current list.

​
Second-Party Data Sources

Second-Party Data imports can receive data from the following sources:

​
Second-Party Data Identifier Support

Second-Party Data imports support matching on various identifier types:

​
Guides

Step-by-step instructions for working with Imports. Data Warehouse and Lake Imports

Creating an Import

Create and configure a data import from an active connection

Actioning Schema Updates

Add new columns to an existing import when your source schema changes
Second-Party Data

Second-Party Data Overview

Understand how second-party data works in Permutive

Configuring Taxonomy

Map segment codes to human-readable names

Ingesting Data via LiveRamp

Set up LiveRamp to send cohorts to Permutive

Adding Audiences in LiveRamp

Browse the LiveRamp Data Marketplace and distribute audience segments to Permutive

​
Dependencies

Imports require the following products and infrastructure:

​
Limits

Imports adhere to the following product specifications and limits.

​
Data Warehouse and Lake Import Limits

​
Second-Party Data File Limits

​
Second-Party Data Taxonomy Limits

​
Second-Party Data Segment Limits

​
FAQ

Only for Data Warehouse and Lake Imports — these pull data from an active connection to your data warehouse or cloud storage, configured on the Connections page. Second-Party Data imports (GCS file upload or LiveRamp) don’t require a connection; Permutive manages the receiving mechanism directly.
Permutive can detect and apply certain types of schema changes to an existing warehouse or lake import:
  • Add new columns to an existing import and choose which of the new columns to include
  • See detected changes flagged as Supported (can be accepted from the dashboard) or Unsupported (require reverting the change at source)
Unsupported changes — removing, renaming, reordering, or changing the data type of existing columns — must be reverted at source. Leaving unsupported changes in place can cause cohorts referencing the affected import to stop functioning correctly.For the end-to-end workflow, detection details, and CSV vs Parquet differences, see Actioning Updates to Your Source Schema.
You can use any identifier that is tracked by your Permutive SDK and configured in Identity Graph. Common identifiers include Permutive user IDs, RampIDs, and custom identifiers like CRM IDs or hashed emails. The identifier format in your import files must exactly match what’s tracked by the SDK, including case sensitivity.
Imported segments typically become available within 15-30 minutes after file upload. Processing time depends on file size and current system load. Large files (approaching the 10M user ID limit) may take longer to process.
When a segment lifetime expires, users are automatically removed from that segment. To maintain segment membership, upload fresh data before the lifetime expires. Each new upload resets the lifetime clock for the users included in that upload.
Yes, you can update the taxonomy at any time. Changes to segment names or descriptions take effect immediately in the Dashboard. Adding new segment codes makes them available for future data uploads. Removing segment codes does not delete existing user memberships—users will remain in the segment until the lifetime expires.
Users are automatically removed when their segment lifetime expires. To immediately remove users, you would need to wait for the lifetime to expire or contact Support for assistance with manual removal. There is no mechanism to upload a “removal” file.
Yes, create a separate import for each partner or data provider. Each import has its own taxonomy, bucket path (for GCS), and configuration. This keeps partner data organized and allows different segment lifetimes or settings per partner.
GCS imports give you direct control over data uploads. You manage the files, upload schedule, and data format. This is ideal for CRM data, partner file exchanges, or any data you can export to files.LiveRamp imports receive data automatically through LiveRamp’s network. This is ideal if your data partners already distribute through LiveRamp or if you want to receive third-party data segments via RampID matching.
Low match rates usually indicate an identifier mismatch. Check that:
  1. The identifier type in your file matches what’s tracked by the SDK
  2. The format is exactly correct (case sensitivity, hyphens, etc.)
  3. The users have actually visited your site/app (new users won’t match)
  4. The identifier is configured in Identity Graph
Contact Support if you need help diagnosing match rate issues.
Yes, imported segments can be used in cohorts that are activated for real-time targeting. Once a user matches an imported segment, they are added to any cohorts that include that segment, and those cohorts flow through to your ad server and SSP activations.
No, imports are point-in-time. Only data uploaded after the import is created will be processed. If you need to backfill historical segment memberships, you’ll need to upload a file containing those memberships.Similarly, when you create a cohort using imported segments, the cohort’s Live Audience Size is not backfilled — it starts at zero and grows as users are evaluated. The Predicted Audience Size shown in the Cohort Builder is a historical estimate and may be significantly higher initially. See Predicted and Live Audience Size for more details.

​
Changelog

For detailed changelog information, visit our Changelog.