> ## 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.

# Imports

> Import data into Permutive — from your connected data warehouses and lakes, or via file upload and LiveRamp for second-party data partnerships — to enrich your first-party data and build cohorts from it.

export const NoBadge = () => {
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.5rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: '#F7D0E2',
    color: '#1A1A1A',
    fontWeight: '500'
  }}>
      No
    </span>;
};

export const YesBadge = () => {
  return <span style={{
    display: 'inline-block',
    padding: '0.125rem 0.5rem',
    borderRadius: '0.25rem',
    fontSize: '0.625rem',
    background: '#C7E8F9',
    color: '#1A1A1A',
    fontWeight: '500'
  }}>
      Yes
    </span>;
};

<CardGroup cols={3}>
  <Card title="Guides" href="#guides" icon="book-open" />

  <Card title="Issues" href="#troubleshooting" icon="triangle-exclamation" />

  <Card title="FAQ" href="#faq" icon="circle-question" />
</CardGroup>

<Note>
  **What's Changed**

  Imports 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](/products/connectivity/connections) page; once a connection is **Active**, come here to configure what data to import.
</Note>

## 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](/products/connectivity/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](/products/connectivity/connections) 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](/products/connectivity/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](/products/connectivity/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](/products/connectivity/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](/guides/connectivity/imports/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](/guides/signals/identity/importing-user-identity) and [Importing User Group Memberships](/guides/signals/identity/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](/guides/connectivity/imports/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](/guides/connectivity/imports/ingesting-data-via-liveramp) 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:

```
USER_ID<TAB>SEGMENT_CODES
76E5F445-1993	0002,0007,0012
5E824DCF-2C6D	0010,0011
69E0985B-50C0	0009,0005
69E0985B-50C0	0012
2DABE6C1-07DD	0001,0008,0010,0012,0013
```

<Note>
  The same user ID can appear on multiple rows. Each row adds the specified segment memberships for that user.
</Note>

**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:

```csv theme={"dark"}
Code,Name,Description,CPM (USD)
0001,Country - France,Users living in France,0
0002,Country - Spain,Users living in Spain,0
0009,Gender - Female,People that identify as Female,0
0012,Subscriber - Premium,Paying subscribers,0
```

**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](/products/connectivity/connections#troubleshooting) instead.

<AccordionGroup>
  <Accordion title="File upload fails with permission errors">
    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](mailto:technical-services@permutive.com) if credentials need to be regenerated.
  </Accordion>

  <Accordion title="File format errors during processing">
    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.
  </Accordion>

  <Accordion title="Segment codes not appearing in taxonomy">
    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.
  </Accordion>

  <Accordion title="Zero match rate or users not appearing in segments">
    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](/guides/signals/cohorts/custom/using-audience-imports#understanding-audience-size-for-import-cohorts) for details.
  </Accordion>

  <Accordion title="LiveRamp import not receiving data">
    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](mailto:technical-services@permutive.com) for assistance troubleshooting the connection.
  </Accordion>

  <Accordion title="Taxonomy API returns batch size error">
    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.
  </Accordion>
</AccordionGroup>

## 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](/products/connectivity/connections#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:

| Source | Description | Configuration |
| :- | :- | :- |
| Google Cloud Storage | Upload files directly to a Permutive-managed GCS bucket | Service account credentials provided |
| LiveRamp | Receive data through LiveRamp's distribution network | Permutive Organization ID required |

#### Second-Party Data Identifier Support

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

| Identifier Type | GCS Import | LiveRamp Import |
| :- | :- | :- |
| Permutive User ID | <YesBadge /> | <NoBadge /> |
| RampID | <YesBadge /> | <YesBadge /> |
| Custom Identifiers | <YesBadge /> | <NoBadge /> |

## Guides

Step-by-step instructions for working with Imports.

**Data Warehouse and Lake Imports**

<CardGroup cols={2}>
  <Card title="Creating an Import" icon="download" href="/guides/connectivity/imports/creating-an-import">
    Create and configure a data import from an active connection
  </Card>

  <Card title="Actioning Schema Updates" icon="arrows-rotate" href="/guides/connectivity/imports/actioning-updates-to-your-source-schema">
    Add new columns to an existing import when your source schema changes
  </Card>
</CardGroup>

**Second-Party Data**

<CardGroup cols={3}>
  <Card title="Second-Party Data Overview" icon="users" href="/guides/connectivity/imports/second-party-data-overview">
    Understand how second-party data works in Permutive
  </Card>

  <Card title="Configuring Taxonomy" icon="list-tree" href="/guides/connectivity/imports/configuring-taxonomy">
    Map segment codes to human-readable names
  </Card>

  <Card title="Ingesting Data via LiveRamp" icon="arrow-right-to-bracket" href="/guides/connectivity/imports/ingesting-data-via-liveramp">
    Set up LiveRamp to send cohorts to Permutive
  </Card>

  <Card title="Adding Audiences in LiveRamp" icon="magnifying-glass" href="/guides/connectivity/imports/adding-audiences-in-liveramp">
    Browse the LiveRamp Data Marketplace and distribute audience segments to Permutive
  </Card>
</CardGroup>

## Dependencies

Imports require the following products and infrastructure:

| Dependency | Required | Description |
| :- | :- | :- |
| Permutive SDK | ✓ | The Permutive SDK must be deployed to track user identifiers that imported data will match against. |
| Identity Graph | ✓ | User identifiers used in imports must be configured in Identity Graph for matching to work correctly. |
| Active Connection | For Data Warehouse and Lake Imports | A connection to your data warehouse or cloud storage must be **Active** on the [Connections](/products/connectivity/connections) page before you can create a warehouse or lake import. |
| Cloud Storage Access | For GCS | GCS imports require the ability to upload files to Google Cloud Storage using provided service account credentials. |
| LiveRamp Account | For LiveRamp | LiveRamp imports require an active LiveRamp account with data distribution configured. |

## Limits

Imports adhere to the following product specifications and limits.

#### Data Warehouse and Lake Import Limits

| Feature | Description | Limit |
| :- | :- | :- |
| Data capacity | Amount of data that can be imported through a connection | Based on contract |
| Import frequency | How often data warehouse and lake imports sync from their connection | Every 24 hours |

#### Second-Party Data File Limits

| Feature | Description | Limit |
| :- | :- | :- |
| User IDs per file | Maximum number of user ID rows in a single data file. | 10,000,000 |
| Daily data volume | Maximum total file size uploaded per day. | 40 GB |
| File compression | Required compression format for data files. | gzip (.gz) |

#### Second-Party Data Taxonomy Limits

| Feature | Description | Limit |
| :- | :- | :- |
| Taxonomy API batch size | Maximum operations per API request. | 5,000 |
| Segment code length | Maximum character length for segment codes. | 256 characters |

#### Second-Party Data Segment Limits

| Feature | Description | Limit |
| :- | :- | :- |
| Default segment lifetime | Default TTL for imported segment memberships. | 60 days |
| Minimum segment lifetime | Minimum configurable segment lifetime. | 1 day |
| Maximum segment lifetime | Maximum configurable segment lifetime. | 365 days |

## FAQ

<AccordionGroup>
  <Accordion title="Do I need a connection to create an import?">
    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](/products/connectivity/connections) page. **Second-Party Data** imports (GCS file upload or LiveRamp) don't require a connection; Permutive manages the receiving mechanism directly.
  </Accordion>

  <Accordion title="What happens if my source schema changes?">
    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](/guides/connectivity/imports/actioning-updates-to-your-source-schema).
  </Accordion>

  <Accordion title="What user identifiers can I use in import files?">
    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.
  </Accordion>

  <Accordion title="How quickly do imported segments become available?">
    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.
  </Accordion>

  <Accordion title="What happens when a segment lifetime expires?">
    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.
  </Accordion>

  <Accordion title="Can I update the taxonomy after uploading data?">
    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.
  </Accordion>

  <Accordion title="How do I remove users from an imported segment?">
    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](mailto:support@permutive.com) for assistance with manual removal. There is no mechanism to upload a "removal" file.
  </Accordion>

  <Accordion title="Can I import data from multiple partners?">
    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.
  </Accordion>

  <Accordion title="What's the difference between GCS and LiveRamp imports?">
    **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.
  </Accordion>

  <Accordion title="How do I troubleshoot low match rates?">
    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](mailto:support@permutive.com) if you need help diagnosing match rate issues.
  </Accordion>

  <Accordion title="Can I use imported segments in real-time bidding?">
    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.
  </Accordion>

  <Accordion title="Is there historical backfill when I create a new import?">
    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](/products/signals/cohorts/custom#whats-the-difference-between-predicted-audience-size-and-live-audience-size) for more details.
  </Accordion>
</AccordionGroup>

## Changelog

<Info>
  For detailed changelog information, visit our
  [Changelog](https://changelog.permutive.com/).
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.