Skip to main content

​
Overview

The taxonomy maps segment codes in your data files to human-readable names, descriptions, and optional metadata. You must configure your taxonomy before uploading data files—codes that don’t exist in the taxonomy will be ignored during processing.
Prerequisites:
  • An import already created in the Permutive Dashboard
  • Segment codes from your data provider (the codes that will appear in data files)
  • Optionally: CPM pricing and lifetime overrides for each segment

​
Understanding Taxonomy

Your taxonomy defines:
  • Segment Code: The unique identifier used in data files (e.g., “0001”, “demo_25_34”)
  • Name: Human-readable name shown in the Dashboard (e.g., “Age 25-34”)
  • Description: Optional explanation of the segment
  • CPM: Optional cost-per-mille for third-party data pricing
  • Lifetime: Optional per-segment TTL override (days)

​
Method 1: CSV Upload

The simplest way to configure taxonomy is through CSV upload in the Dashboard.
1

Navigate to Your Import

In the Permutive Dashboard, go to Connectivity > Imports and select the import you want to configure.
2

Access Taxonomy Settings

Click on the Taxonomy tab or section within your import settings.
3

Download the Template (Optional)

If available, download the CSV template to ensure your file matches the expected format.
4

Prepare Your CSV File

Create a CSV file with the following columns:
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
demo_25_34,Age 25-34,Users aged 25 to 34,0.50,30
intent_auto,Auto Intenders,Users showing automotive purchase intent,1.25,14
Field requirements:
  • ID (required): Unique segment code, alphanumeric with no spaces
  • Name (required): Display name in Dashboard
  • Description (optional): Segment description
  • CPM (USD) (optional): Cost per mille for third-party segments
  • Lifetime (days) (optional): Per-segment TTL override
5

Upload the CSV

Upload your CSV file through the Dashboard. The taxonomy will be validated and applied to your import.
6

Verify Segments Appear

After upload, verify that your segments appear in the taxonomy list with the correct names and settings.

​
Method 2: Taxonomy API

Use the Taxonomy API for programmatic management of segments. This is ideal for automated workflows, incremental updates, or integration with your internal systems.

​
API Details

PropertyValue
Base URLhttps://api.permutive.app/audience-api/v1
AuthenticationPrivate API key via x-api-key header
Max operations per request5,000
See the API Authentication documentation for details on obtaining and using your private API key.

​
Identifying Your Import

When making API calls, you can identify your import using either:
  • Import Code: A human-readable string identifier (e.g., “my-import”)
  • Import Public ID: A UUID identifier (e.g., “f336d0bc-b841-465b-8045-024475c079dd”)
Both identifiers are available in the Dashboard when viewing your import settings.

​
Bulk Operations Endpoint

The bulk endpoint allows you to create, update, and delete multiple segments in a single request. Endpoint: POST /imports/{import_id}/segments/bulk Request body: 
{
  "operations": [
    {
      "operation": "Create",
      "data": {
        "name": "New Segment",
        "code": "new_segment_001",
        "description": "Description of the new segment",
        "cpm": 2,
        "categories": ["category1", "category2"]
      }
    },
    {
      "operation": "Update",
      "code": "existing_segment_002",
      "data": {
        "name": "Updated Segment Name",
        "description": "Updated description"
      }
    },
    {
      "operation": "Delete",
      "code": "old_segment_003"
    }
  ]
}

​
Operation Types

Create — Add a new segment to the taxonomy: 
{
  "operation": "Create",
  "data": {
    "name": "Segment Name",
    "code": "segment_code",
    "description": "Optional description",
    "cpm": 0.50,
    "categories": ["optional", "categories"]
  }
}
Update — Modify an existing segment: 
{
  "operation": "Update",
  "code": "existing_code",
  "data": {
    "name": "New Name",
    "description": "New description"
  }
}
Delete — Remove a segment from the taxonomy: 
{
  "operation": "Delete",
  "code": "segment_to_delete"
}

​
Example: Full API Request

curl -X POST "https://api.permutive.app/audience-api/v1/imports/my-import/segments/bulk" \
  -H "x-api-key: YOUR_PRIVATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "operation": "Create",
        "data": {
          "name": "High Value Shoppers",
          "code": "hv_shoppers_001",
          "description": "Users with high purchase intent",
          "cpm": 1.50,
          "categories": ["commerce", "intent"]
        }
      },
      {
        "operation": "Create",
        "data": {
          "name": "Newsletter Subscribers",
          "code": "newsletter_active",
          "description": "Active newsletter subscribers",
          "cpm": 0,
          "categories": ["crm"]
        }
      }
    ]
  }'

​
Handling Large Taxonomies

The API supports a maximum of 5,000 operations per request. For larger taxonomies:
  1. Split your operations into batches of 5,000 or fewer
  2. Make multiple sequential API requests
  3. Consider using CSV upload for initial bulk creation, then API for incremental updates
Requests exceeding 5,000 operations will be rejected with a batch size error. Always validate your batch size before submission.

​
Best Practices

  • Set up taxonomy before uploading data: Segment codes not in the taxonomy are ignored
  • Use descriptive names: Help your team understand what each segment represents
  • Document segment codes: Maintain a mapping between provider codes and their meanings
  • Use categories: Group related segments for easier organization
  • Review CPM values: Ensure pricing is accurate for third-party data monetization

​
Next Steps

Uploading Data Files Manually

Upload files via GCS Console

Uploading Data Files Programmatically

Automate uploads with service account

Using Imports in Cohorts

Create cohorts with imported segments

Back to Imports

Return to Imports overview