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

# Configuring Taxonomy

> Set up a taxonomy to map segment codes to human-readable names for your imported audience data

## Overview

A taxonomy maps raw audience segment codes from your imported data to human-readable names, so they can be used in Permutive cohort definitions and insights.

Each taxonomy is one-to-one with an audience set (also called a Data Provider). An audience set is a way to separate and group different segments together.

For example, you may have:

* One audience set for your own first-party data analyzed and brought back in
* Another audience set for self-sourced data through a partnership with another platform sharing demographic data

Each audience set has its own taxonomy to keep the data separated in the UI and in the system.

## Taxonomy Fields

| Field           | Required | Description                                                                                                                                                                                                                    |
| :-------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Code**        | Yes      | A unique identifier for the segment. Alphanumeric string, never displayed in the UI. Best practice is to use a sequence (e.g., `s001`, `s002`, `s003`) rather than human-readable words. This value can never be changed.      |
| **Name**        | Yes      | The display name shown in the Permutive Dashboard. Use hyphens to delimit category levels (e.g., `Demographic - Inferred Gender - Female`). Can be updated.                                                                    |
| **Description** | No       | Description of the segment, shown in the Dashboard.                                                                                                                                                                            |
| **CPM (USD)**   | No       | The CPM for the segment, typically for third-party partner segments. Leave blank or set to `0` for self-sourced data. If using partner segments billed through Permutive, add the CPM per segment as per the partner taxonomy. |

## Example Taxonomy

Below is an example taxonomy with four segments:

| Code | Name                                   | Description                                      | CPM  |
| :--- | :------------------------------------- | :----------------------------------------------- | :--- |
| 4412 | Demographic - Inferred Gender - Female | Users whose gender has been inferred as female.  |      |
| 4981 | Demographic - Inferred Gender - Male   | Users whose gender has been inferred as male.    |      |
| 4011 | Demographic - Declared Gender - Female | Users who have specified their gender as female. |      |
| 4099 | Demographic - Declared Gender - Male   | Users who have specified their gender as male.   | 1.50 |

## Taxonomy CSV Format

Upload your taxonomy as a CSV file with the following columns:

```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
0006,"Income < $20,000","Having income of less than $20,000",0,60
0009,Gender - Female,People that identify as Female,0,30
0012,Subscriber - Premium,Paying subscribers,0,30
0013,Interest - Cars,Those who are interested in cars.,0,30
```

<Note>
  The taxonomy for a given Data Provider/Audience Set must be exhaustive and cover every possible segment code present in the data.
</Note>

To manage taxonomy programmatically, use the [Batch Update](/api/taxonomy/batch-update) endpoint to create, update, and delete multiple segments in a single request.

## Important Guidelines

* **Avoid major changes to existing segments.** We advise only cosmetic changes such as descriptions. Changing the name of a segment or category could impact teams creating cohorts in the Dashboard.
* **Create new segments instead of recycling old ones.** If you need to change the definition of a segment, create a new segment rather than repurposing an existing code.
* **Taxonomy is separate from data.** The taxonomy is relatively static and defines what segments mean. The audience data files are more transient and updated as needed to reflect users' membership in segments.

<Warning>
  If you find yourself needing to make major changes to segment definitions, contact [support](mailto:support@permutive.com) or your Customer Service Representative so they can help you plan the migration.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Second-Party Data Overview" icon="users" href="/guides/connectivity/imports/second-party-data-overview">
    Learn about using second-party data in Permutive
  </Card>

  <Card title="Taxonomy API" icon="code" href="/api/taxonomy/introduction">
    Manage taxonomy programmatically via the API
  </Card>
</CardGroup>