Skip to main content

Guides

Issues

FAQ

​
Overview

Imports (also known as Audience Imports) enables publishers to import audience segments from external sources directly into Permutive. Publishers can bring in data from Customer Data Platforms (CDPs), data partners, DMPs, or their own CRM systems and use these imported segments to build cohorts and activate campaigns. Permutive supports two import sources:
  • Google Cloud Storage (GCS): Upload user ID and segment files directly to a Permutive-managed GCS bucket
  • LiveRamp: Receive audience data through LiveRamp’s data distribution network
Imported segments appear in the Cohort Builder under the “Audience Imports” condition type, allowing publishers to combine external data with their first-party behavioral data.

​
Why Use Imports?

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 configuration that defines the source of external audience data, access permissions, and segment lifetime. Each import represents a connection to a specific data provider or partner.
  • Taxonomy: 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: A logical grouping mechanism for organizing segments from different sources. Each import is associated with a data provider, which helps separate segments from different partners or use cases.
  • Segment Code: A unique identifier for a segment within an import. Segment codes are defined in the taxonomy and referenced in data files. Codes can be alphanumeric strings (e.g., “0001”, “demo_25_34”, “intent_auto”).
  • Import Lifetime: 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, but can be overridden per segment in the taxonomy.

​
Data Flow

The 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

​
Creating an Import

Publishers navigate to Connectivity > Imports in the Permutive Dashboard and click “Add Import” to begin. They 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. Publishers use these credentials to upload data files to the specified bucket. For LiveRamp imports: Publishers provide their LiveRamp Organization ID. Permutive configures the connection to receive data from LiveRamp’s distribution network.

​
Setting Up Taxonomy

The taxonomy maps segment codes to human-readable names and metadata. Publishers can configure the taxonomy in two ways: CSV Upload: Upload a CSV file with columns for segment ID, name, description, CPM, and lifetime. 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.

​
Uploading Data Files

For GCS imports, publishers 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.

​
Data File Format

Data files must follow this tab-separated format: 
USER_ID<TAB>SEGMENT_CODES
76E5F445-1993-4B13-A67A-76E5F4451993	0002,0007,0012
5E824DCF-2C6D-4A89-9B34-5E824DCF2C6D	0010,0011
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

​
Taxonomy CSV Format

The taxonomy CSV defines your segments: 
ID,Name,Description,CPM (USD)
0001,Country - France,Users living in France,0
0002,Country - Spain,Users living in Spain,0
demo_25_34,Age 25-34,Users aged 25 to 34,0.50
Fields:
  • ID (required): Unique segment code (alphanumeric, no spaces)
  • Name (required): Display name in Dashboard
  • Description (optional): Segment description
  • CPM (USD) (optional): Cost per mille for third-party segments

​
Troubleshooting

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.
If a LiveRamp import is configured but not receiving data, there may be a configuration mismatch.Solution: Verify your LiveRamp Organization ID is correct in the import settings. 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 [email protected] 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

​
Import Sources

Imports can receive data from the following sources:
SourceDescriptionConfiguration
Google Cloud StorageUpload files directly to a Permutive-managed GCS bucketService account credentials provided
LiveRampReceive data through LiveRamp’s distribution networkLiveRamp Organization ID required

​
Identifier Support

Imports support matching on various identifier types:
Identifier TypeGCS ImportLiveRamp Import
Permutive User IDYesNo
RampIDYesYes
Custom IdentifiersYesNo

​
Guides

Step-by-step instructions for working with Imports.

Creating an Import

Configure a new import in the Dashboard

Configuring Taxonomy

Upload and manage segment taxonomy

Uploading Data Files Manually

Upload files via GCS Console

Uploading Data Files Programmatically

Automate uploads with service account credentials

Setting Up LiveRamp Import

Configure LiveRamp data ingestion

Using Imports in Cohorts

Create cohorts with imported segments

​
Dependencies

Imports require the following products and infrastructure:
DependencyRequiredDescription
Permutive SDK✓The Permutive SDK must be deployed to track user identifiers that imported segments will match against.
Identity Graph✓User identifiers used in import files must be configured in Identity Graph for matching to work correctly.
Cloud Storage AccessFor GCSGCS imports require the ability to upload files to Google Cloud Storage using provided service account credentials.
LiveRamp AccountFor LiveRampLiveRamp imports require an active LiveRamp account with data distribution configured.

​
Limits

Imports adhere to the following product specifications and limits.

​
File Limits

FeatureDescriptionLimit
User IDs per fileMaximum number of user ID rows in a single data file.10,000,000
Daily data volumeMaximum total file size uploaded per day.40 GB
File compressionRequired compression format for data files.gzip (.gz)

​
Taxonomy Limits

FeatureDescriptionLimit
Taxonomy API batch sizeMaximum operations per API request.5,000
Segment code lengthMaximum character length for segment codes.256 characters

​
Segment Limits

FeatureDescriptionLimit
Default segment lifetimeDefault TTL for imported segment memberships.60 days
Minimum segment lifetimeMinimum configurable segment lifetime.1 day
Maximum segment lifetimeMaximum configurable segment lifetime.365 days

​
FAQ

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.

​
Changelog

For detailed changelog information, visit our Changelog.