> ## 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 (Audience)

> Import audience data from external sources like Google Cloud Storage and LiveRamp.

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>

## 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 are alphanumeric strings — best practice is to use sequences (e.g., "0001", "s001") rather than human-readable words.

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

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

### Taxonomy CSV Format

The taxonomy CSV defines your segments:

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

**Fields:**

* `ID` (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.
* `Lifetime (days)` (optional): Per-segment TTL override in days. If omitted, the import's default lifetime is used.

## Troubleshooting

<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

#### Import Sources

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   |

#### Identifier Support

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

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

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

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

#### 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="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>